acp spec

research/agents/claude.md

@@ -9,6 +9,21 @@ Research notes on Claude Code's configuration, credential discovery, and runtime
 - **Session Persistence**: Session ID (string)
 - **SDK**: None (spawns CLI directly)
 
+## ACP Terminology (Sandbox Agent v2)
+
+Use these terms consistently when discussing Claude's ACP path:
+
+| Term | Meaning |
+|------|---------|
+| **ACP agent process launcher** | The command used to start the ACP agent process, commonly an `npx` launcher script that executes `claude-code-acp`. |
+| **ACP agent process** | The running ACP agent process spawned by Sandbox Agent from the launcher command. |
+| **ACP client** | The client-visible transport handle identified by `X-ACP-Connection-Id`; requests and SSE are scoped to this ACP client. |
+
+Related IDs:
+
+- **ACP client ID**: value of `X-ACP-Connection-Id` (transport identity).
+- **ACP session ID**: `sessionId` returned by `session/new` (conversation/session identity within ACP).
+
 ## Credential Discovery
 
 ### Priority Order

research/agents/codex.md

@@ -157,6 +157,41 @@ The server can send JSON-RPC requests (with `id`) for approvals:
 
 These require JSON-RPC responses with a decision payload.
 
+## App Server WebSocket Transport (Experimental)
+
+Codex app-server also supports an experimental WebSocket transport:
+
+```bash
+codex app-server --listen ws://127.0.0.1:4500
+```
+
+### Transport constraints
+
+- Listen URL must be `ws://IP:PORT` (not `localhost`, not `http://...`)
+- One JSON-RPC message per WebSocket text frame
+- Incoming: text frame JSON is parsed as a JSON-RPC message
+- Outgoing: JSON-RPC messages are serialized and sent as text frames
+- Ping/Pong is handled; binary frames are ignored
+
+### Connection lifecycle
+
+- Each accepted socket becomes a distinct connection with its own session state
+- Every connection must send `initialize` first
+- Sending non-`initialize` requests before init returns `"Not initialized"`
+- Sending `initialize` twice on the same connection returns `"Already initialized"`
+- Broadcast notifications are only sent to initialized connections
+
+### Operational notes
+
+- WebSocket mode is currently marked experimental/unsupported upstream
+- It is a raw WS server (no built-in TLS/auth); keep it on loopback or place it behind your own secure proxy/tunnel
+
+### Upstream implementation references (openai/codex `main`, commit `03adb5db`)
+
+- `codex-rs/app-server/src/transport.rs`
+- `codex-rs/app-server/src/message_processor.rs`
+- `codex-rs/app-server/README.md`
+
 ## Response Schema
 
 ```typescript