Skip to content

Bot Runtime Simplification Roadmap

Why the inbound-turn runtime is divided the way it is, the invariants its seams protect, and the simplifications still planned. The AI reply lifecycle belongs to Reply messages, and the event journal's decisions and the homeserver behaviour behind them belong to the event journal contracts; this page does not repeat them.

Why

The runtime abstractions should be concrete, honest, and easy to trace. Turn handling applies the general architecture principles with three runtime-specific rules:

  • One inbound turn can be traced without jumping between multiple coordinators.
  • The durable turn truth is singular.
  • A change that moves ownership deletes the old owner instead of adding a second one.

Target Boundaries

  • AgentBot owns Matrix lifecycle only.
  • TurnIngress owns one inbound event from its Matrix callback to coalescing-gate admission; VoiceIngress admits voice messages and InteractiveSelections admits answers to interactive questions for it.
  • TurnDispatcher owns one turn from the gate's exit to its recorded outcome.
  • TurnPolicy owns pure decision logic only: it sends nothing, runs no AI, and writes no persistence state.
  • ResponseRunner owns response execution and lifecycle only.
  • TurnStore owns durable turn truth.
  • DeliveryGateway owns Matrix transport only.

The gate-to-dispatch seam is one-way: the gate hands dispatch each turn together with what dispatch may know about the queue it left, so dispatch never holds the gate and the gate is built after the dispatcher it calls. The queued notices of follow-ups still waiting behind a flushed batch are a snapshot taken at the flush, but whether the queue holds another run stays a live read, because dispatch asks after awaiting the turn's context and a message admitted meanwhile must still keep a newer message from absorbing the turn out of receipt order. An interactive selection crosses the gate as a value its owner runs after the gate, not as a closure.

The dispatch-to-execution seam is one-way too: dispatch hands the runner immutable values, and the runner assembles the final payload itself after it takes the lifecycle lock. A callback that runs payload building back inside turn dispatch after the lock was rejected, because data must cross the seam as values, not closures.

Edit regeneration runs on a runner-owned task and does not wait for its claim, so another reply holding the conversation never holds up the room's event lane.

The response-to-approval seam is one-way as well: the response runner hands a paused turn to the approval continuation runner, and both settle through the locked-turn owner bot.py builds for them. A host protocol the approval runner called back into the response runner through was rejected, because neither runner could then change shared settlement alone. What a response did with its sources crosses back to its entry point as a returned value that one rule settles, for the same reason dispatch hands the runner values rather than closures.

Ordering Identities

Requester identity is split into several identities because each protects a different invariant.

  • Physical sender and effective requester differ when trusted-relay promotion attributes a turn to someone other than the account that sent it.
  • Acting requester: an agent's or team's reply names the human or configured bot account it answered, and an entity that reply mentions authorizes and executes as that requester, while receipt lanes, coalescing, the chatter gate, self-echo drops, and speaker labels stay on the replying entity. A reply's final text arrives as a completed m.replace of its placeholder, so that edit is the journal source and the placeholder its discovery alias, which keeps later completed edits of the same reply from dispatching again.
  • Batching owner: a batch holds only one owner's messages and ends where the effective requester or the acting author changes, because a turn runs under exactly one requester's identity and takes its origin from its latest event.

Turn Ownership

The crash guarantee is durable callback acceptance with retryable callback execution, then durable turn ownership and terminal deduplication once the turn record exists.

A physical source event ID is an exclusive turn claim, while a discovery alias is only an advisory settlement key. Aliases stay separate from canonical source identity so recovery can index every triggering event, such as an interactive selection or the human sources of a coalesced router relay, and later edits and redactions reach the owned prompt, without making one message look coalesced.

Approval replies and reactions can have several semantic consumers, so a durable claim selects exactly one before any side effect, and recovery routes only to the claimed consumer instead of rediscovering intent from mutable runtime state. Each consumer owns the replay semantics of its own side effects; generic reaction hooks, for example, are at-least-once.

Interactive selections:

  • Reaction and numeric-answer admission snapshot the prompt revision the projection exposes, so later edits cannot reinterpret a stored selection; unrelated Matrix origin clocks are never treated as causal order.
  • Active prompts are derived by joining those immutable revisions to the visible projection, so history recovery can restore an unconsumed revision without resurrecting an answered one.
  • The selecting source, not the reusable question event, is the turn's execution and deduplication identity.
  • The selection's history ends at the selecting source while the question stays the reply target, so clarification in between remains available.
  • An interactive reaction stays pending while its detached response owns the selection, so a restart can replay it until delivery is durable.

When the current event is in thread history, its turn's history is bounded at that event, so later entries cannot enter a backlog turn's context or displace its earlier history from the budget.

An interrupted turn stays pending, and its replay continues the reply in place. A run saves a checkpoint of itself before each tool batch runs and before each request after one, because a kill keeps only what storage holds; the checkpoint is a cancelled row, which history skips, so a run that ends on its own stores and replays exactly what it would without one. The replay of an interrupted turn, and the settlement of an interrupted subagent turn, finish that row as a turn of the run's own stored messages, reasoning included, adding only an answer for each call that had none: the next request then starts with the bytes the interrupted run already sent, which a provider's prompt cache still holds, where a prose account of the whole work would be sent, and billed, as new input. A reply its user stops settles its run the same way at once, since no replay continues it: the run keeps its own messages, each call still running answered, and ends with the text of the response the Stop cut off and a note that the user stopped the turn, so the next turn's request starts with the bytes the stopped run sent. A run stopped before it called a tool settles the same way once a response of it had begun, and so does an attempt that continues an approved run's turn. The note is MindRoom's, not the agent's words, so memory extraction, compaction hooks and the knowledge graph keep the text the stopped response showed and leave the note out. A run stopped before its first response began, a team's reply, and a turn that another cancellation ended, such as a failed delivery, keep the prose record of what the reply showed. An approved run stopped while it still works after its approval keeps the cancelled row it stored, which history skips. A recovered run is history like any finished run, so the agent's limits, the request's budget and compaction apply to it unchanged; the replay's prompt therefore still lists the bounded previews of the recorded tool calls, after the cached prefix, so a request that history trimmed or folded still names the calls whose effects stand. The retry of an edit's regeneration recovers that edit's own attempts the same way, so the edit's commit, which every retry repeats, removes what answered the text before the edit and keeps the runs that read the edit itself; a newer edit's regeneration takes over no attempt and starts fresh. A turn restarts cut short more than twice stops continuing from its recovered runs and takes them out of history, in case continuing from them is what stops it, which leaves it the bounded previews of its recorded tool calls. An approved run's resume saves no checkpoint, since the paused row is what an approval cut short settles from; a run that paused for a subagent without tool jobs is continued by its own turn with the subagent's answer and checkpoints as before. A subagent job's child is the exception: its job asks for its approvals and resumes each paused row once, so nothing settles from that row, and its approved resume checkpoints as its fresh run does, and before each approved call, because a crash that left the paused row would end its job where a restart continues it. An interrupted edit regeneration also stays pending: a retry of the same edit recovers its attempts as above, and a newer edit's regeneration starts fresh, because it replaced the prompt the stopped attempts answered; a regeneration's approved resume that was cut short continues below what it showed, as an interrupted turn does.

Potentially mutating chat commands are at-most-once: the start of execution is recorded before the handler runs, and the exact result before visible delivery. Recovery re-delivers a recorded result, while an interrupted attempt without one is not rerun and instead tells the requester its outcome is uncertain and to inspect state before retrying. !config set keeps its own Matrix-backed preview, decision, execution, and result journal, because its mutation begins only after the requester reacts to the preview.

Durable Dispatch Boundary

Nio owns receive cursors, prepared batches, provenance, encryption recipients, and room-key sharing; the event journal contracts record that MindRoom trusts nio for these instead of re-deriving them.

Retention and deduplication

Classic Sync tokens are opaque and may be invalidated, forcing a sync without since whose limited timeline backfill can redeliver an older event. No checkpoint-relative pruning frontier can therefore preserve exact deduplication, so settled rows are kept: settling clears a row's replay payload in place, and the row goes on proving that its event already produced its one turn.

Failure, refusal, and ignored traffic

A callback that raises stays pending at the head of its room lane and retries with capped backoff for as long as it fails, so a homeserver, provider, or network outage delays events instead of dropping them; a cancelled callback stays pending for startup replay. Only a callback that recognizes a deterministic refusal settles its event, by returning an outcome instead of raising. A message or media event whose relation target the homeserver refuses to serve can never be placed in a conversation, so it settles as intentionally ignored. A successful but empty readiness result settles as intentionally ignored instead of repeating download or transcription work forever. Pure-policy ignores, such as unmentioned managed senders, blocked deep synthetic relays, and commands another entity owns, settle their journal rows without recording a turn, which keeps high-volume ignored traffic out of the turn tables without weakening deduplication.

Room lanes

A global scan only discovers rooms; each room's lane runs its pending callbacks in receipt order, and a failure pauses only that room. Revisiting a receipt at or before the room's latest admitted receipt also backs off, because immediate downstream handoffs would otherwise trap recovery in a retry loop. A periodic liveness sweep exists because a downstream owner can vanish without a completion notification. A running turn stays a pending row until its owner hands it back, so discovery does not page through running turns again on every wake: while turns are in flight it reads only what was admitted after its last finished scan. A lane still starts each pass at the front of its room, because a commit is visible before anything announces it, and an older source it made runnable has to run before the room's newer ones. A retry or a lost owner rewinds its room, and so does a departing router that fails a reply paused on its approval card, so the freed source still runs before later messages in its room. The same sweep, which starts with the first turn in flight, sends discovery over the whole backlog again, which reopens a room for work that became runnable with nothing to announce it.

Shutdown, replacement, and crash

Orderly shutdown, entity replacement, and a crash leave the same pending state, so one replay path recovers all three, and the interrupted reply stays visibly streaming until replay adopts it. Interrupted callbacks stay pending for exact replay, including edits whose revision has not reached a final response, and an approved run cut short releases its continuation without settling its sources, unless a FINAL is already owed, so replay adopts its reply too. Shutdown closes callback admission before withdrawing runtime capabilities, and its quiescence request stays latched across supervisor retries and late startup completion, so transport lifecycle notifications cannot reopen admission. A cleanup that outlasts its budget keeps its owners, and the Matrix client and journal stay open until it finishes. Shutdown invalidates membership readiness only after owners finish, so readiness loss cannot settle an accepted source as revoked authorization. Replay does not wait for a later sync token or Sliding Sync position: recovered callbacks may rely on the room ID, but cached membership and state are best-effort. Recovery intent travels with queued ingress, so lane and coalescing workers cannot turn a recovered turn whose router target is temporarily unavailable into a terminal fallback response.

Delivery and membership

Only the durable INITIAL outbox row may put a placeholder in the room, so a send whose outcome Matrix never confirmed is resolved by resending that row under its own transaction ID, not by a second, unowned send. Every outbox delivery freezes the room membership epoch that authorized it, except an approval card whose delivery stages atomically transfer their already-decided terminal cleanup to a successor membership.

Invites

Invites have no stable event ID for a journal row, so the pending room and inviter are persisted before background handling starts. That record only wakes unfinished work and never grants inviter authority: routers and agents re-read Nio's current inviter after the join fence is durable and immediately before requesting the join.

Best-effort inputs

  • An event that never reached either durable owner and later falls outside Matrix replay is lost; this is the explicit pre-admission loss boundary.
  • Live room-member-joined hooks are at-least-once, because they are emitted before durable settlement.
  • Call-manager membership and unknown-event callbacks only wake reconciliation, because their standalone payloads cannot replay the current room call state.
  • Auxiliary room callbacks are gated by the provenance of their own event, so one live event cannot license unrelated historical call-state mutations.
  • To-device call inputs and desktop pairing receivers are best-effort and have no journal ownership, because they lack a stable replayable timeline-event identity.

Inspecting and repairing records

The journal is tracking/event_journal.db under the storage directory, or the configured PostgreSQL database. journal_events grows by one row per admitted event and is never pruned, for the deduplication reason above. Inspect its growth with SELECT state, COUNT(*) FROM journal_events GROUP BY state;. Do not delete settled rows unless duplicate callback execution after a later Matrix redelivery is acceptable. Recovery logs and skips a pending row it cannot decode and keeps it pending for repair, so other rows continue. A row that decodes but whose payload is corrupt or does not match its stored kind is logged as corrupt and settled, which clears its replay payload. To repair a retained unreadable pending row, stop MindRoom, back up the affected database, and restore a known-good copy before restarting. Deleting such a row is a last resort that accepts losing that callback. Repair cannot recover payloads that settlement already cleared.

Voice Readiness

A voice message's batching scope and its echo thread are distinct: a root audio message can join the room's batch while its echo starts a thread rooted at it, and the final coalesced reply target follows the current dispatch policy.

Turn State

  • One runtime process owns each agent's turn state and its semantic ordering, so nothing defines cross-process precedence; a second runtime against the same event journal refuses to start.
  • Every turn fact is a row with one writer, read by query, so there is no in-memory copy to publish or reconcile; what a sibling store of the same agent (a hot replacement) could not see is an in-flight turn, and the claim registry every store of the agent shares covers that.
  • A turn is one immutable ordered tuple of physical sources; a different tuple is a new turn that absorbs the unfinished owners of its sources, while an alias only indexes, so an original and the relay answering it stay two live turns.
  • A write refused because an answered or delivery-bound turn owns a source writes nothing and hands each source back to the journal once the claim releases, so a conflicting source settles as handled at precheck and an unrelated one in the same batch is answered.
  • A non-AI FINAL binds its turn in the transaction that makes the row durable and settles the turn's sources there, so a reshape before the acknowledgement cannot redirect which turn the acknowledgement completes.
  • Retention keeps replayable incomplete turns and every turn an unsettled journal row references; redactions are kept apart from turns, so a turn that once read a deleted message ages out like any other.

Redaction

The user-visible history behavior is on Conversation history.

  • A redaction is recorded once per agent, in the transaction that admits it, and applied there to every Matrix login of that agent and to the agent's turns; it is kept when the bot leaves the room, because an earlier login the agent returns to, or a rejoin the server does not replay the redaction to, would otherwise show the deleted text again.
  • Deleting the human message a router relayed deletes the relay that answers for it: the routed reply ends, and its approval wait with it, exactly as for a directly sent message, because reply discovery matches exact logical ids and the redacted alias is resolved to its sources first.
  • Nothing durable records that history cleanup is owed: every response derives it from the recorded redactions, so a crash between redaction and cleanup, or a redacted event no turn owns, needs no recovery path.
  • Approval creation and source-redaction admission serialize, so an approval cannot acquire a source that a deletion already settled.
  • Redacted replay can stay in local session storage until its history scope next serves a response, because cleanup runs only then. Approval continuations, manual compaction, and voice-call turns do not run the check either.
  • Semantic memory backends such as Mem0 keep their own lifecycle and are not changed by this cleanup.

Approval Event Client Contract

Clients consume approval events under these rules, which this repository's code cannot enforce:

  • Policy approval events eligible for timed grants expose a canonical approval_scope with an opaque scope ID, entity, invoking agent, and concrete operation, including the MCP server and remote tool when applicable; one-shot-only approvals omit it and stay individually reviewable.
  • Approved calls carry immutable approval_provenance: kind: once, or kind: timed_grant with grant ID, originating card, granting user, decision time, duration, and fixed expiry.
  • Clients associate approval history with the response through response_event_id, never by tool names or argument similarity. A paused reply's cards always carry it. A background job's card for the reply's own tool call carries it when that reply showed an event before making the call, and names the job in background_run_id as tool-job:<job_id>, the job_id of the call's job handle. A job card without it names no reply: a background subagent's card, whose call is the child's, or a card for a call made before its reply showed an event, such as every card of a silent schedule, a contact turn, or a participation-judged turn that does not stream, and the card of a call that is the first output of a turn that compacts first. The field names the reply, not the call: an edit regenerates a reply in place, so a job its earlier generation started can still hold a pending card naming the same event as the new generation's cards, and a client prefers the job that the call's job handle names when the call has one.
  • Clients render compact history from the original event plus its latest same-sender terminal edit, taking complete argument evidence from the original, inline or as its Matrix attachment, because terminal edits omit it.
  • Only the originating grant card carries mutable auto-approval controls, and revocation or expiry never changes the historical authorization of calls the grant covered.
  • After a device change, a missing terminal receipt may be republished because it offers no action, so clients deduplicate receipts by exact approval and tool-call identity, scoped to the event sender.

Simplifications Still Planned

  • bot.py, turns/dispatch.py, turns/interactive_selection.py, and edit_regenerator.py still reach InboxResponses through ResponseRunner; injecting the inbox into them would leave the runner only the locked turn and its delivery.
  • IngressHookRunner is a thin hook adapter with a vague name; it may stay a helper but must not grow into another top-level orchestration object.
  • Only after those steps, revisit MessageTarget, which combines conversation identity and delivery placement, and split them only if the runtime still needs it.