Protocol and event stream

Start from a normal product scene. One client starts a task. Another client joins later and should see the current turn, streamed assistant output, a pending command approval, the latest diff, and token usage. If the page reloads, history should still reconstruct the important parts of the turn.

The source sequence is clearer than the final UI. The core protocol accepts typed submissions and emits typed events; app-server v2 converts those events into the notifications, requests, and list items that clients consume.

This part follows five questions:

1. What runtime parameters does a client send when it starts a turn?
2. Why does core reduce interaction to one submission queue and one event queue?
3. Which EventMsg variants describe lifecycle, content, tools, approvals, usage, and diff?
4. Why does app-server v2 translate core events instead of forwarding them verbatim?
5. How can rollout be reduced back into turns after resume?

1. Start From What Clients Need To See

Protocols are hard to read when they begin as enum lists. The easier route is to ask what client-visible state must remain coherent while a Codex turn is running.

That is the shape of the problem: accept intent, preserve runtime facts, and let different clients consume those facts through their own view.

2. Input Side: A Typed Work Order

app-server v2 requests are not loose JSON blobs. The protocol macro generates ClientRequest, where each request has fixed params and response types. The turn/start request uses TurnStartParams.

TurnStartParams includes the obvious thread_id and input, but it also carries runtime boundaries: client metadata, additional context, environment selection, cwd, workspace roots, approval policy, sandbox policy, permissions, model, and service tier. Starting a turn is therefore more like submitting a typed work order than sending chat text.

In turn_start_inner, app-server converts v2 input into TurnInput, collects settings overrides, and builds a TurnInputRequest. start_or_steer_turn lets core decide whether to start an idle thread, steer an active turn that can accept input, or decline the submission. The caller does not need to read state and race that decision.

The same ordering idea appears in Op::ThreadSettings. It does not start a turn, but it uses the same submission queue so app-server can preserve caller order between settings mutations and turn starts.

3. Core exposes a queue pair

The public thread object is now CodexThread. Runtime state lives in Session, while SessionIo holds the submission and event endpoints: tx_sub: Sender<Submission> and rx_event: Receiver<Event>. Separating the endpoints allows the session loop to terminate when all senders disappear and gives callers a shared shutdown completion future.

Ordinary submit allocates a unique id, wraps an Op in a Submission, and enqueues it. The envelope contains id, op, trace, and causal parent_turn_id / root_turn_id fields for multi-agent work. The client user-message id belongs to TurnInput::UserInput. submit_turn_input also includes a one-shot reply channel: it waits for core’s start, steer, or decline decision, not model completion. next_event independently consumes runtime events.

4. Output Side: EventMsg Is the Fact List

EventMsg is a long tagged enum with #[serde(tag = "type", rename_all = "snake_case")]. That wire shape matters: runtime facts are structured variants, not informal strings.

The key distinction is that EventMsg is lower-level than the final UI. A TurnDiffEvent carries the unified diff. A TokenCountEvent carries token usage and rate-limit snapshots. Layout, grouping, folding, and emphasis are decisions for client rendering.

5. app-server v2 converts core events for clients

At app-server, the protocol supports multiple clients. OpenAI's App Server article describes JSON-RPC between clients and the Codex harness: it accepts client requests, turns them into core operations, and converts the harness event stream into stable client notifications. In source, app-server v2 defines those notifications through ServerNotification. The method list includes turn/started, turn/completed, item/started, item/completed, turn/diff/updated, and thread/tokenUsage/updated.

The v2 view is built around Turn and ThreadItem. A turn exposes status such as completed, interrupted, failed, and in progress. A ThreadItem turns user messages, assistant messages, plans, reasoning, and tool calls into client list items.

The main translation point is apply_bespoke_event_handling. It receives core Event { id, msg }, matches on EventMsg, and emits v2 notifications or server requests. Turn lifecycle events become turn notifications; approval requests become server requests that need a client response; token usage and diff have dedicated handlers.

Stateless one-to-one item mappings live in item_event_to_server_notification. That helper covers assistant message deltas, plan deltas, reasoning deltas, item started/completed, exec output deltas, and similar direct mappings. Anything that needs state checks, pending request cleanup, or legacy-event suppression stays in the bespoke handler.

This example starts a new turn and reaches a command requiring approval. Steering an existing turn does not open another turn; command events and text deltas may interleave:

turn/start request
  -> EventMsg::TurnStarted -> turn/started notification
  -> EventMsg::AgentMessageContentDelta -> item delta
  -> EventMsg::ExecApprovalRequest -> server request
  -> Op::ExecApproval -> core continues
  -> EventMsg::ItemCompleted -> item/completed notification
  -> EventMsg::TurnComplete -> turn/completed notification

The mapping code also suppresses or redirects events when that keeps the v2 view coherent. For example, legacy ContextCompacted and some patch/exec events are not blindly forwarded because v2 clients receive canonical items elsewhere.

6. Rollout Rebuilds Turns From Facts

The RolloutItem policy persists session metadata, response items, turn context, compaction and token-usage records, plus selected runtime events. Legacy history retains corresponding older message events; paginated history primarily stores completed TurnItem records. Intermediate deltas, approval requests, and ItemStarted are not all persisted. Historical ThreadRolledBack markers still participate in reconstruction, but the current request enum no longer exposes thread/rollback.

InitialHistory exposes get_event_msgs() for resumed and forked histories by extracting RolloutItem::EventMsg. Core record_initial_history applies rollout reconstruction and seeds token usage from the last persisted TokenCount.

app-server has a dedicated reducer too: build_turns_from_rollout_items converts persisted rollout items into Turn values. Its ThreadHistoryBuilder handles persisted event messages, compacted items, response items, and turn context. TurnStarted opens a turn; TurnComplete closes it.

At shape level, the reduction looks like this:

rollout items (simplified persisted records):
  EventMsg(TurnStarted)
  EventMsg(ItemCompleted(exec))
  EventMsg(TurnComplete)

ThreadHistoryBuilder:
  -> Turn { status: completed, items: [...] }

7. A Reading Checklist

The opening question now has a compact answer: clients can share one set of facts because Codex separates input, runtime events, client views, and replayable recovery records. The same reading rule applies to tools: once the model asks for a tool call, how does Codex route, execute, approve, and record it?

Sources

• Pinned openai/codex source snapshot
• OpenAI: Unlocking the Codex harness: how we built the App Server
• ClientRequest macro
• turn/start request definition
• TurnStartParams
• turn_start_inner mapping to Op::TurnInput
• Submission
• Op
• SessionIo submission/event endpoints
• submit / submit_with_id
• next_event
• Event / EventMsg
• ServerNotification macro
• apply_bespoke_event_handling
• item_event_to_server_notification
• Approval request mapping
• TokenCount mapping
• TurnDiff mapping
• RolloutItem
• build_turns_from_rollout_items
• ThreadHistoryBuilder