slopus--happy/docs/competition/codex/message-protocol.md

Codex App-Server Protocol

Bottom line

Codex has the strongest server protocol of the systems reviewed so far. It is especially useful for approvals, runtime state, resume/fork, and sandbox policy.

Core transport and state model

Codex app-server speaks JSON-RPC 2.0 over stdio and an experimental websocket transport.

• the core persistent model is thread -> turn -> item
• clients start, resume, or fork threads explicitly
• turns are started explicitly and stream item updates live
• ThreadItem is a tagged union, not an untyped blob

Primary source files:

• ../happy-adjacent/research/codex/codex-rs/app-server/README.md
• ../happy-adjacent/research/codex/codex-rs/app-server-protocol/src/protocol/v2.rs

Transcript and live notifications

Codex leans heavily on typed notifications.

• notifications cover thread lifecycle, turn lifecycle, plan updates, deltas, approvals, and more
• important item families include agentMessage, reasoning, commandExecution, fileChange, mcpToolCall, dynamicToolCall, collabAgentToolCall, webSearch, and contextCompaction
• live streaming is done with dedicated delta notifications rather than a single text stream
• the README explicitly warns that initial thread or turn payloads may be sparse; live notifications are the canonical source of active state

This is a good reminder for Happy: a list endpoint and a stream endpoint should not be the same thing.

Subagents and collaboration

Codex models subagents as typed items, not hidden side effects.

• collaboration agent activity appears as CollabAgentToolCall
• supported actions include spawn, send input, resume, wait, and close
• thread metadata can indicate subagent origin and carry agent nickname/role
• thread status and collab-agent state are explicit typed fields

This is a good template for representing delegated work inside Happy without losing identity.

Primary source files:

• ../happy-adjacent/research/codex/codex-rs/app-server-protocol/src/protocol/v2.rs

Approval model

Codex's approval model is one of the best things in the repo.

• approvals are not just notifications; the server sends explicit JSON-RPC requests to the client
• there are separate approval request shapes for command execution, file changes, permission changes, user input, and MCP elicitation
• the server later emits resolution notifications so UI state can clear correctly
• reviewer identity can be the user or a guardian subagent

Happy should copy this structure: normal event stream for state, explicit server requests for blocking decisions.

Primary source files:

• ../happy-adjacent/research/codex/codex-rs/app-server-protocol/src/protocol/common.rs
• ../happy-adjacent/research/codex/codex-rs/app-server-protocol/src/protocol/v2.rs

Modes and model switching

Codex exposes this as structured protocol state.

• model/provider/service tier/effort/summary/personality can be set at thread or turn boundaries
• collaboration mode is a real protocol concept with its own list and selection surface
• model reroutes are surfaced as protocol events with reason fields

This is much better than hiding mode changes in prompt text or UI-only state.

Sandbox policy

Codex clearly wins on sandbox expressiveness.

• coarse modes include read-only, workspace-write, and full access
• richer SandboxPolicy variants allow writable roots, read-only access, network access, and external sandbox options
• there are Windows-specific setup flows for sandbox support
• some commands are explicitly unsandboxed, which is documented rather than hidden

This is a strong reference for Happy's server-side permission and sandbox contract.

Resume, fork, and lifecycle

Resume and fork are treated as first-class protocol paths.

• thread/resume supports several restore paths
• thread/fork supports persistent and ephemeral forks
• protocol has knobs such as persist_extended_history
• runtime live-watch state is separated from persisted thread history
• tests cover real edge cases like joining a running thread or replaying pending approvals on resume

This split between stored history and live watcher state is worth copying.

Sync and transport robustness

Codex is more serious than the others about backpressure and client capability drift.

• websocket support has explicit health endpoints and origin restrictions
• bounded queues protect the server
• overloaded request paths return errors instead of hanging forever
• slow websocket clients can be disconnected cleanly
• notification filtering and experimental field gating exist per connection

Happy should take this seriously if it wants robust mobile or multi-client session control.

Primary source files:

• ../happy-adjacent/research/codex/codex-rs/app-server/src/lib.rs
• ../happy-adjacent/research/codex/codex-rs/app-server/src/transport.rs
• ../happy-adjacent/research/codex/codex-rs/app-server/src/thread_state.rs

What Happy should steal

• explicit thread / turn / item protocol model
• server-initiated approval requests
• typed collab-agent items for subagents
• real sandbox policy objects with network and path controls
• clear split between persisted history and runtime watcher state