chore: import upstream snapshot with attribution

2026-07-13 12:40:49 +08:00
commit 98e40dac97
2013 changed files with 268743 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 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