Skip to content

Docs · Internals

What happens inside one agent turn

The agent runtime is the part of the backend that drives a nexus session for the chat. This page follows one turn, then what surrounds it: images, the queue, permission scopes, graph content in a prompt and the timing of each tool call.

What it does

It persists your message (or queues it when a turn is running), starts the turn, masks secrets in every event, maps events to the chat format and broadcasts them.

A turn that fails with a retryable error before showing anything is retried. One that already showed output, or failed for good, never is.

What a session cannot do is listed in the degraded_features of its session start event, so the dashboard can say so: for example sub-agents on an ACP agent, images on a model without vision, or the Project Orchestrator tools on an agent that refuses per-session MCP servers.

The diagram

One agent turn in the chat runtimeFlow diagram. The ChatManager sends a message. If a turn is already running, the message is queued instead of refused: a plain send interrupts the turn, a held message waits and interrupts nothing, and send now cuts the turn short. Otherwise attached images become image blocks, the user message is persisted and the turn starts. Every provider event is masked for vault secrets, failing closed. A retryable error with nothing shown yet is retried up to three times. Events are mapped from AgentEvent to ChatEvent, then emitted: persisted, broadcast and kept in a mid-stream snapshot. At the end of a turn, one stopped on its limit continues by itself up to five times in a row, then the queue drains. Separately, output outside a turn is grouped and emitted as background output, session commands such as answer_permission, interrupt, set_model and close go to the session, graph hooks run before and after tools, and the session start event lists degraded features.yesnonext turnChatManagercreate, send, permissions, interrupt, closenexus AgentSessionchosen by the provider resolvera turn already running?a message sent meanwhile is queued, not refused:a plain send interrupts the turn,a held message waits and interrupts nothing,send now cuts the turn shortattached images: one image block each,the model must have visionotherwise images_refusedpersist the UserMessageStreamingStatus truesession.send_turnmask vault secrets in every eventfail closed: an event that cannot be maskedbecomes a visible markerretryable error and nothing shown yet:Retrying, same turn, 3 tries,retry_after from the provider else backoffEventMapperAgentEvent to ChatEventunknown cost is never 0emit: persist (except deltas),broadcast, keep the mid-stream snapshotend of turn: a turn stopped on its limit continues by itself,at most 5 in a row, 500 ms apart(CHAT_AUTO_CONTINUE=false turns it off),then the queue drains; a Stop discards automatic entriesanswer_permissioninterrupt (turn and tools)set_model, set_policy_modeclose: provider closed (5 s max),session_closed emitted, session forgottenout of turn: pump_out_of_bandgroup by provider message number,mask, emit background_outputsystem_init lists degraded_featuresmessage_queue, auto_continue, nats, enrichment,plus what the session capabilities do not coverGraphSessionHooksbefore_tool, after_tool, before_compactionsame hook table as the Claude path

Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.

Zoom outZoom inFull screen
Redrawn from the verified diagram po-chat-agent-runtime (verified 459cab6f). Labels are the names used in the code.
Text description of the diagram

Flow diagram. The ChatManager sends a message. If a turn is already running, the message is queued instead of refused: a plain send interrupts the turn, a held message waits and interrupts nothing, and send now cuts the turn short. Otherwise attached images become image blocks, the user message is persisted and the turn starts. Every provider event is masked for vault secrets, failing closed. A retryable error with nothing shown yet is retried up to three times. Events are mapped from AgentEvent to ChatEvent, then emitted: persisted, broadcast and kept in a mid-stream snapshot. At the end of a turn, one stopped on its limit continues by itself up to five times in a row, then the queue drains. Separately, output outside a turn is grouped and emitted as background output, session commands such as answer_permission, interrupt, set_model and close go to the session, graph hooks run before and after tools, and the session start event lists degraded features.

Guided reading

  1. Step 1. One turn at a time

    A message sent while a turn is running is queued, not refused. Sent as a plain message, it interrupts the running turn and is read next, as on Claude Code. Held in the queue, it is listed, waits for the turn to end and interrupts nothing; Send now cuts the turn short for it. The decision is taken under the queue lock.

  2. Step 2. Persist and send

    The graph context of the turn and the attached files are put in front of your message. Then it is persisted, the streaming status is set to true and send_turn starts the stream.

  3. Step 3. Mask

    Every provider event goes through the vault-secret masker before it is stored or broadcast. It fails closed: an event that cannot be masked becomes a visible marker, and a withheld terminal event still ends the turn.

  4. Step 4. Retry

    A retryable done.error or error with nothing shown yet emits a Retrying event and replays the same turn, up to 3 tries. It waits for retry_after when the provider gives one, otherwise it backs off.

  5. Step 5. Map

    EventMapper turns neutral events into chat events. Replaying a recorded 21-message conversation gives the same chat events as the older path. A cost that is unknown stays unknown, never 0.

  6. Step 6. Emit

    emit adds provider, capabilities, tool_policy, engine and degraded_features to the session start event, persists the event (except stream deltas and streaming status), broadcasts it and keeps the mid-stream snapshot for clients that reconnect.

  7. Step 7. Out of turn, commands, close

    Output that arrives outside a turn is grouped by the provider message number, masked and emitted as background_output. Permission answers, interrupt, model and policy changes go to the session. Close shuts the provider (5 seconds at most), emits session_closed and forgets the session.

  8. Step 8. Graph hooks

    GraphSessionHooks plugs the same hook table as the Claude path into before_tool, after_tool and before_compaction: context can be added, a call can be denied or its input replaced, and a hook that fails is ignored. Only the native engine and Claude Code are given them, not Codex or ACP.

  9. Step 9. Images

    Images attached to a message are read from the document store and sent after the text, in order, as image blocks, on Claude Code and on a native model. The model decides: a native model whose catalogue says it can see gets them, a model without vision refuses with an images_refused error, and the turn is not sent. Claude Code takes png, jpeg, gif and webp, up to 5 MiB once decoded.

  10. Step 10. End of a turn: auto-continue and the queue

    When a turn ends on its turn limit, the runtime continues it by itself after 500 ms, at most 5 times in a row; only CHAT_AUTO_CONTINUE=false turns that off. Then the queued messages are sent one after the other until the queue is empty. A Stop discards the automatic entries.

  11. Step 11. Permission scopes

    A permission request can be answered once, for the session or, in a conversation that has an owner and a project, always. Whatever you pick, the provider is only ever answered once: PO keeps the grant and answers the later requests it covers itself, because the engines match loosely (a command is split on ; & | only) and a wider match once turned an approval of one command into another. A session grant covers only the identical call, kept in the memory of that session. For a command it applies only when every program of the line is on a short list of programs that run nothing from the project; the Codex shell and patches, and any ACP agent, are always answered once, and an unknown tool is refused with a typed error so that you answer once. A grant never allows what the engine policy refuses, because only the requests the engine asked reach it.

  12. Step 12. Lasting rules

    An always rule is stricter still: no file tool, and a single simple command with no operator, redirection or glob. It belongs to a person and a project, in a private directory of the machine that owns the session; a symbolic link, a foreign owner or a file others can write is ignored, and every rule read back is checked again, so a rule edited by hand into something broader holds nothing. A person can list their rules and revoke one (GET and DELETE on /api/chat/permission-rules). A session without an owner keeps no lasting rule, and always is not offered there.

  13. Step 13. Graph content is data

    Notes, decisions, personas, skills, the user profile, file context and the descriptions of third-party MCP tools are written by people, agents and imported packages. Before such text goes into a prompt it is wrapped in an untrusted_data container with a random nonce: it cannot contain the closing tag, the nonce, a code fence or a heading, nor direction-override characters, and the prompt tells the model to treat it as data. That lowers the odds that a model obeys an instruction hidden in a note; it does not make it impossible. The instructions of a protocol state are deliberately outside the container, so whoever can edit a protocol definition is trusted like the operator.

  14. Step 14. Timing of each tool call

    The server times every tool call itself, to the millisecond, on both chat engines (the Claude Code CLI path and the agent engine), so the conversation timeline does not depend on what a provider reports. The clock starts when the engine takes the call up, before any permission is asked, and notes when you answered; a tool_timing event is stored and sent right after the result. A start time the engine did not see, as for a remote session, Codex or ACP, is left out rather than guessed.

  15. Step 15. Questions from a native model

    The native engine offers its own AskUserQuestion tool, shown as the same question card as on Claude Code. The answer is a user turn: the turn ends once the calls of the step are done, and your reply starts the next one. A model without tool support is not given it.

Why it is built this way

Fail closed on secrets

Masking an event that cannot be parsed would be guesswork, so the event is replaced by a visible marker rather than passed through in clear.

Never retry what you have seen

Replaying a turn that already produced output would duplicate text and tool calls. Only a retryable failure before any output is replayed.

Say what is missing

Features the runtime does not carry, and capabilities the session lacks, are written into the session start event instead of silently disappearing.

Unknown is not zero

A provider that reports no cost leaves the cost unknown. Showing 0 would look like a free turn.

What is not established

  • This path has never been run against the real Claude CLI, a real model endpoint or a real Codex or ACP agent: only fake providers and fake executables, plus one real native harness for background tasks and cancellation. NATS was tested against an in-process test broker, never a real server or two real instances. As on the older path, memory records a turn only when it is configured.