@bastani/atomic 0.9.19-alpha.5 → 0.9.19-alpha.7

package/docs/rpc.md

@@ -1,9 +1,24 @@
+---
+title: "RPC"
+description: "Drive a long-lived Atomic process over stdin/stdout JSONL."
+---
+
 # RPC Mode
 
 RPC mode enables headless operation of the coding agent via a JSON protocol over stdin/stdout. This is useful for embedding the agent in other applications, IDEs, or custom UIs.
 
 **Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `@bastani/atomic` instead of spawning a subprocess. See [`src/core/agent-session.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/agent-session.ts) for the API. For a subprocess-based TypeScript client, see [`src/modes/rpc/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts).
 
+## Where to go next
+
+This page starts RPC mode and walks one client end to end. The rest is split by job:
+
+- [RPC protocol](/rpc/protocol) — every command, event, type, and error contract.
+- [RPC extension UI protocol](/rpc/extension-ui) — drive extension-rendered UI over RPC.
+- [RPC client examples](/rpc/examples) — additional client implementations.
+
+Not sure RPC is the right integration mode? Compare it with the SDK and JSON mode on [Programmatic use](/programmatic).
+
 ## Starting RPC Mode
 
 ```bash
@@ -42,1529 +57,331 @@ In particular, Node `readline` is not protocol-compliant for RPC mode because it
 
 ## Commands
 
-### Prompting
-
-#### prompt
-
-Send a user prompt to the agent. The command response is emitted after the prompt is accepted, queued, or handled. Events continue streaming asynchronously after acceptance.
-
-```json
-{"id": "req-1", "type": "prompt", "message": "Hello, world!"}
-```
+Moved to [RPC protocol](/rpc/protocol#commands).
 
-With images:
-```json
-{"type": "prompt", "message": "What's in this image?", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
-```
-
-**During streaming**: If the agent is already streaming, you must specify `streamingBehavior` to queue the message:
-
-```json
-{"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}
-```
-
-- `"steer"`: Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
-- `"followUp"`: Wait until the agent finishes. Message is delivered only when agent stops.
-
-If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.
-
-**Extension commands**: If the message is an extension command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.
-
-**Input expansion**: Skill commands (`/skill:name`) and prompt templates (`/template`) are expanded before sending/queueing.
+### Prompting
 
-Response:
-```json
-{"id": "req-1", "type": "response", "command": "prompt", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#prompting).
 
-`success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.
+#### prompt
 
-The `images` field is optional. Each image uses `ImageContent` format: `{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}`.
+Moved to [RPC protocol](/rpc/protocol#prompt).
 
 #### steer
 
-Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
-
-```json
-{"type": "steer", "message": "Stop and do this instead"}
-```
-
-With images:
-```json
-{"type": "steer", "message": "Look at this instead", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
-```
-
-The `images` field is optional. Each image uses `ImageContent` format (same as `prompt`).
-
-Response:
-```json
-{"type": "response", "command": "steer", "success": true}
-```
-
-See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.
+Moved to [RPC protocol](/rpc/protocol#steer).
 
 #### follow_up
 
-Queue a follow-up message to be processed after the agent finishes. Delivered only when agent has no more tool calls or steering messages. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead).
-
-```json
-{"type": "follow_up", "message": "After you're done, also do this"}
-```
-
-With images:
-```json
-{"type": "follow_up", "message": "Also check this image", "images": [{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}]}
-```
-
-The `images` field is optional. Each image uses `ImageContent` format (same as `prompt`).
-
-Response:
-```json
-{"type": "response", "command": "follow_up", "success": true}
-```
-
-See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.
+Moved to [RPC protocol](/rpc/protocol#follow_up).
 
 #### abort
 
-Abort the current operation and wait for the session to become idle before responding.
-
-```json
-{"type": "abort"}
-```
-
-Response:
-```json
-{"type": "response", "command": "abort", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#abort).
 
 #### clear_queue
 
-Remove queued steering and follow-up messages and return their text.
-
-```json
-{"type": "clear_queue"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "clear_queue",
-  "success": true,
-  "data": {
-    "steering": ["Change direction"],
-    "followUp": ["Summarize when finished"]
-  }
-}
-```
-
-To implement interactive Esc behavior, send `clear_queue` before `abort`, then restore the returned text in the client editor. `abort` continues queued messages when they remain in the session.
+Moved to [RPC protocol](/rpc/protocol#clear_queue).
 
 #### new_session
 
-Start a fresh session. Can be cancelled by a `session_before_switch` extension event handler.
-
-```json
-{"type": "new_session"}
-```
-
-With optional parent session tracking:
-```json
-{"type": "new_session", "parentSession": "/path/to/parent-session.jsonl"}
-```
-
-Response:
-```json
-{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}
-```
-
-If an extension cancelled:
-```json
-{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": true}}
-```
+Moved to [RPC protocol](/rpc/protocol#new_session).
 
 ### State
 
-#### get_state
-
-Get current session state.
-
-```json
-{"type": "get_state"}
-```
+Moved to [RPC protocol](/rpc/protocol#state).
 
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_state",
-  "success": true,
-  "data": {
-    "model": {...},
-    "thinkingLevel": "medium",
-    "isStreaming": false,
-    "isCompacting": false,
-    "steeringMode": "all",
-    "followUpMode": "one-at-a-time",
-    "sessionFile": "/path/to/session.jsonl",
-    "sessionId": "abc123",
-    "sessionName": "my-feature-work",
-    "autoCompactionEnabled": true,
-    "messageCount": 5,
-    "pendingMessageCount": 0
-  }
-}
-```
+#### get_state
 
-The `model` field is a full [Model](#model) object or `null`. Its `contextWindow` is the model's token budget. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
+Moved to [RPC protocol](/rpc/protocol#get_state).
 
 #### get_messages
 
-Get all messages in the conversation.
-
-```json
-{"type": "get_messages"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_messages",
-  "success": true,
-  "data": {"messages": [...]}
-}
-```
-
-Messages are `AgentMessage` objects (see [Types](#types)).
+Moved to [RPC protocol](/rpc/protocol#get_messages).
 
 ### Model
 
-#### set_model
-
-Switch to a specific model. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also save `defaultProvider`, `defaultModel`, and the effective thinking level in settings, matching an interactive `/model` selection.
+Moved to [RPC protocol](/rpc/protocol#model).
 
-```json
-{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}
-```
-
-Persist as the startup default:
-```json
-{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514", "persist": true}
-```
+#### set_model
 
-Response contains the full [Model](#model) object:
-```json
-{
-  "type": "response",
-  "command": "set_model",
-  "success": true,
-  "data": {...}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#set_model).
 
 #### cycle_model
 
-Cycle to the next available model. Returns `null` when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a `null` or unchanged result does not. Set `"persist": true` to also write the cycled model as the startup default.
-
-```json
-{"type": "cycle_model"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "cycle_model",
-  "success": true,
-  "data": {
-    "model": {...},
-    "thinkingLevel": "medium",
-    "isScoped": false
-  }
-}
-```
-
-The `model` field is a full [Model](#model) object.
+Moved to [RPC protocol](/rpc/protocol#cycle_model).
 
 #### get_available_models
 
-List all configured models.
-
-```json
-{"type": "get_available_models"}
-```
-
-Response contains an array of full [Model](#model) objects:
-```json
-{
-  "type": "response",
-  "command": "get_available_models",
-  "success": true,
-  "data": {
-    "models": [...]
-  }
-}
-```
-
-The subprocess protocol returns full `Model` objects. The exported TypeScript `RpcClient.getAvailableModels()` keeps its smaller backward-compatible `ModelInfo` shape (`provider`, `id`, `contextWindow`, `reasoning`) and adds optional `compat`. When present, `compat` exposes constrained-sampling capability claims including `supportsStrictTools`, `supportsStrictMode`, canonical `supportsOpenAIGrammarTools`, and Atomic's synchronized `supportsGrammarTools` alias. Treat absence as unknown/unsupported; do not infer enforcement from the provider name.
-
-```typescript
-const models = await client.getAvailableModels();
-const capabilities = models[0]?.compat;
-if (capabilities?.supportsStrictTools) {
-  // The selected model advertises Anthropic/Bedrock strict-tool support.
-}
-```
+Moved to [RPC protocol](/rpc/protocol#get_available_models).
 
 #### logout_provider
 
-Remove a provider's stored credential in the authoritative agent process, refresh its available-model catalog, and return the remaining authentication status and new catalog. Environment variables and `models.json` authentication are reported but are not modified.
-
-```json
-{"type": "logout_provider", "provider": "github-copilot"}
-```
-
-Response:
-
-```json
-{
-  "type": "response",
-  "command": "logout_provider",
-  "success": true,
-  "data": {
-    "provider": "github-copilot",
-    "authStatus": {"configured": false},
-    "models": [],
-    "scopedModels": []
-  }
-}
-```
-
-`models` preserves the refreshed catalog order. `scopedModels` is optional. If authentication remains through an environment variable, `authStatus.source` is `"environment"` and `authStatus.label` names the variable.
-
+Moved to [RPC protocol](/rpc/protocol#logout_provider).
 
 ### Thinking
 
-#### set_thinking_level
+Moved to [RPC protocol](/rpc/protocol#thinking).
 
-Set the reasoning/thinking level for models that support it. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also save `defaultThinkingLevel` and, when a model is active, its per-model override. Interactive `/thinking` choices request persistence automatically.
-
-```json
-{"type": "set_thinking_level", "level": "high"}
-```
-
-Persist as the startup default:
-```json
-{"type": "set_thinking_level", "level": "high", "persist": true}
-```
-
-Levels: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`.
-
-`xhigh` and `max` are available only when the active model's capability mapping supports them; unsupported levels are clamped by the session model controls.
-
-Response may omit `data` for compatibility with older clients:
-```json
-{"type": "response", "command": "set_thinking_level", "success": true}
-```
-
-Current engines include the effective level after capability clamping and, when a model is active, the provider/model the engine persisted against:
-```json
-{"type": "response", "command": "set_thinking_level", "success": true, "data": {"level": "high", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}}
-```
+#### set_thinking_level
 
-Isolated interactive hosts must apply a persisted thinking default using that ACK target, not the host session model at callback time. A later `model_changed` event must not re-key the saved override. A later `thinking_level_changed` event must keep the host session's effective level even if an older ACK settles afterward. `RpcClient.setThinkingLevel(level)` stays one-argument `Promise<void>`; isolated persist reads the ACK through an internal client path.
+Moved to [RPC protocol](/rpc/protocol#set_thinking_level).
 
 #### cycle_thinking_level
 
-Cycle through available thinking levels. Returns `null` data if model doesn't support thinking.
-
-```json
-{"type": "cycle_thinking_level"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "cycle_thinking_level",
-  "success": true,
-  "data": {"level": "high"}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#cycle_thinking_level).
 
 #### get_available_thinking_levels
 
-Return the thinking levels supported by the current model, in cycle order.
-
-```json
-{"type": "get_available_thinking_levels"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_available_thinking_levels",
-  "success": true,
-  "data": {"levels": ["off", "low", "medium", "high"]}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#get_available_thinking_levels).
 
 ### Queue Modes
 
-#### set_steering_mode
-
-Control how steering messages (from `steer`) are delivered.
-
-```json
-{"type": "set_steering_mode", "mode": "one-at-a-time"}
-```
+Moved to [RPC protocol](/rpc/protocol#queue-modes).
 
-Modes:
-- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls
-- `"one-at-a-time"`: Deliver one steering message per completed assistant turn (default)
+#### set_steering_mode
 
-Response:
-```json
-{"type": "response", "command": "set_steering_mode", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#set_steering_mode).
 
 #### set_follow_up_mode
 
-Control how follow-up messages (from `follow_up`) are delivered.
-
-```json
-{"type": "set_follow_up_mode", "mode": "one-at-a-time"}
-```
-
-Modes:
-- `"all"`: Deliver all follow-up messages when agent finishes
-- `"one-at-a-time"`: Deliver one follow-up message per agent completion (default)
-
-Response:
-```json
-{"type": "response", "command": "set_follow_up_mode", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#set_follow_up_mode).
 
 ### Compaction
 
-#### compact
-
-Run Atomic's verbatim line compactor. The selected session model receives the complete active numbered transcript except for exactly the newest `preserve_recent` context-visible messages and returns bare `start,end` deletion records; Atomic validates them and mechanically reconstructs retained lines with `(filtered N lines)` markers. The default tail is two messages, with no user-turn alignment. A value of zero sends the entire active transcript and persists `firstKeptEntryId: null`. The command appends a durable `compaction` entry with `details.strategy: "verbatim-lines"`.
+Moved to [RPC protocol](/rpc/protocol#compaction).
 
-```json
-{"type": "compact"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "compact",
-  "success": true,
-  "data": {
-    "compactedText": "[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.",
-    "firstKeptEntryId": "m7",
-    "tokensBefore": 150000,
-    "promptVersion": 3,
-    "parameters": {
-      "compression_ratio": 0.5,
-      "preserve_recent": 2,
-      "query": "fix the test"
-    },
-    "rung": "planned",
-    "stats": {
-      "linesBefore": 812,
-      "linesDeleted": 417,
-      "linesKept": 395,
-      "rangeCount": 63,
-      "tokensBefore": 150000,
-      "tokensAfter": 72000,
-      "percentReduction": 52
-    },
-    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
-  }
-}
-```
+#### compact
 
-`firstKeptEntryId` is a string when at least one ordinary message remains outside compaction and `null` when none does. RPC clients must accept both values.
+Moved to [RPC protocol](/rpc/protocol#compact).
 
 #### set_auto_compaction
 
-Enable or disable automatic compaction when context is nearly full.
-
-```json
-{"type": "set_auto_compaction", "enabled": true}
-```
-
-Response:
-```json
-{"type": "response", "command": "set_auto_compaction", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#set_auto_compaction).
 
 ### Retry
 
-#### set_auto_retry
+Moved to [RPC protocol](/rpc/protocol#retry).
 
-Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).
-
-```json
-{"type": "set_auto_retry", "enabled": true}
-```
+#### set_auto_retry
 
-Response:
-```json
-{"type": "response", "command": "set_auto_retry", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#set_auto_retry).
 
 #### abort_retry
 
-Abort an in-progress retry (cancel the delay and stop retrying).
-
-```json
-{"type": "abort_retry"}
-```
-
-Response:
-```json
-{"type": "response", "command": "abort_retry", "success": true}
-```
+Moved to [RPC protocol](/rpc/protocol#abort_retry).
 
 ### Bash
 
-#### bash
-
-Execute a shell command and add output to conversation context.
-
-```json
-{"type": "bash", "command": "ls -la"}
-```
+Moved to [RPC protocol](/rpc/protocol#bash).
 
-Response:
-```json
-{
-  "type": "response",
-  "command": "bash",
-  "success": true,
-  "data": {
-    "output": "total 48\ndrwxr-xr-x ...",
-    "exitCode": 0,
-    "cancelled": false,
-    "truncated": false
-  }
-}
-```
-
-While the command runs, Atomic emits ordered deltas correlated by the command `id`:
-
-```json
-{"type":"bash_execution_update","id":"req-1","channel":"stdout","delta":"building...\n"}
-{"type":"bash_execution_update","id":"req-1","channel":"stderr","delta":"warning\n"}
-```
-
-`channel` is exactly `"stdout"` or `"stderr"`. Deltas preserve the order observed for that request; concurrent bash requests may interleave globally but never share IDs. Request ownership survives `new_session`, `switch_session`, `import_session`, fork, and clone while the command is running: later deltas still stream under the original ID, the replacement session is not contaminated, and exactly one ordinary `response` remains the terminal record for completion, cancellation, or error.
-
-If output was truncated, includes `fullOutputPath`. Persisted bash output lives in the owner- and session-scoped temp tree (`<tmpdir>/atomic-<uid>/<session-id>/`), not at the temp root — see [Tools](/tools#persisted-tool-output) for the layout, permissions, size cap, and retention:
-```json
-{
-  "type": "response",
-  "command": "bash",
-  "success": true,
-  "data": {
-    "output": "truncated output...",
-    "exitCode": 0,
-    "cancelled": false,
-    "truncated": true,
-    "fullOutputPath": "/tmp/atomic-501/019fdf86-cf98-7327-8a73-21365028f6ae/atomic-bash-abc123.log"
-  }
-}
-```
-
-`fullOutputPath` is `null` when the temp directory could not be created or the write was refused; treat it as absent rather than assuming a path exists.
-
-**How bash results reach the LLM:**
-
-The `bash` command executes immediately and returns a `BashResult`. Internally, a `BashExecutionMessage` is created and stored exactly once in the session where that request started, even if an RPC session replacement completes before the command. The message does NOT emit an event.
-
-When the next `prompt` command is sent, all messages (including `BashExecutionMessage`) are transformed before being sent to the LLM. The `BashExecutionMessage` is converted to a `UserMessage` with this format:
-
-````
-Ran `ls -la`
-```
-total 48
-drwxr-xr-x ...
-```
-````
+#### bash
 
-This means:
-1. Bash output is included in the LLM context on the **next prompt**, not immediately
-2. Multiple bash commands can be executed before a prompt; all outputs will be included
-3. No event is emitted for the `BashExecutionMessage` itself
+Moved to [RPC protocol](/rpc/protocol#bash-2).
 
 #### abort_bash
 
-Abort running bash commands. Omit `requestId` to retain the legacy behavior of aborting every active RPC-owned bash request, including requests that began before a session replacement, or provide the target bash command's `id` to cancel only that request. Targeted and legacy cancellation remain isolated across concurrent IDs. Closing RPC cancels and drains remaining owned requests before shutdown.
-
-```json
-{"id":"cancel-1","type":"abort_bash","requestId":"req-1"}
-```
-
-Response:
-```json
-{"id":"cancel-1","type":"response","command":"abort_bash","success":true}
-```
+Moved to [RPC protocol](/rpc/protocol#abort_bash).
 
 ### Session
 
-#### get_session_stats
-
-Get token usage, cost statistics, and current context window usage.
+Moved to [RPC protocol](/rpc/protocol#session).
 
-```json
-{"type": "get_session_stats"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_session_stats",
-  "success": true,
-  "data": {
-    "sessionFile": "/path/to/session.jsonl",
-    "sessionId": "abc123",
-    "userMessages": 5,
-    "assistantMessages": 5,
-    "toolCalls": 12,
-    "toolResults": 12,
-    "totalMessages": 22,
-    "tokens": {
-      "input": 50000,
-      "output": 10000,
-      "cacheRead": 40000,
-      "cacheWrite": 5000,
-      "total": 105000
-    },
-    "cost": 0.45,
-    "contextUsage": {
-      "tokens": 60000,
-      "contextWindow": 200000,
-      "percent": 30
-    }
-  }
-}
-```
-
-`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.
+#### get_session_stats
 
-`contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.
+Moved to [RPC protocol](/rpc/protocol#get_session_stats).
 
 #### export_html
 
-Export session to an HTML file.
-
-```json
-{"type": "export_html"}
-```
-
-With custom path:
-```json
-{"type": "export_html", "outputPath": "/tmp/session.html"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "export_html",
-  "success": true,
-  "data": {"path": "/tmp/session.html"}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#export_html).
 
 #### switch_session
 
-Load a different session file. Can be cancelled by a `session_before_switch` extension event handler.
-
-```json
-{"type": "switch_session", "sessionPath": "/path/to/session.jsonl"}
-```
-
-Response:
-```json
-{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": false}}
-```
-
-If an extension cancelled the switch:
-```json
-{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": true}}
-```
+Moved to [RPC protocol](/rpc/protocol#switch_session).
 
 #### fork
 
-Create a new fork from a previous user message on the active branch. Can be cancelled by a `session_before_fork` extension event handler. Returns the text of the message being forked from.
-
-```json
-{"type": "fork", "entryId": "abc123"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "fork",
-  "success": true,
-  "data": {"text": "The original prompt text...", "cancelled": false}
-}
-```
-
-If an extension cancelled the fork:
-```json
-{
-  "type": "response",
-  "command": "fork",
-  "success": true,
-  "data": {"text": "The original prompt text...", "cancelled": true}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#fork).
 
 #### clone
 
-Duplicate the current active branch into a new session at the current position. Can be cancelled by a `session_before_fork` extension event handler.
-
-```json
-{"type": "clone"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "clone",
-  "success": true,
-  "data": {"cancelled": false}
-}
-```
-
-If an extension cancelled the clone:
-```json
-{
-  "type": "response",
-  "command": "clone",
-  "success": true,
-  "data": {"cancelled": true}
-}
-```
+Moved to [RPC protocol](/rpc/protocol#clone).
 
 #### get_fork_messages
 
-Get user messages available for forking.
-
-```json
-{"type": "get_fork_messages"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_fork_messages",
-  "success": true,
-  "data": {
-    "messages": [
-      {"entryId": "abc123", "text": "First prompt..."},
-      {"entryId": "def456", "text": "Second prompt..."}
-    ]
-  }
-}
-```
+Moved to [RPC protocol](/rpc/protocol#get_fork_messages).
 
 #### get_entries
 
-Get all session entries in append order (excluding the session header). The session is an append-only tree of entries with stable ids, so an entry id works as a durable cursor: pass the last entry id you have seen as `since` to get only entries strictly after it, even across client restarts. Unlike `get_messages`, this includes pre-compaction history and abandoned branches.
-
-```json
-{"type": "get_entries"}
-```
-
-With a cursor:
-```json
-{"type": "get_entries", "since": "abc123"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_entries",
-  "success": true,
-  "data": {
-    "entries": [
-      {"type": "message", "id": "def456", "parentId": "abc123", "timestamp": "...", "message": {"role": "user", "...": "..."}}
-    ],
-    "leafId": "def456"
-  }
-}
-```
-
-`leafId` is the id of the current leaf entry (`null` for an empty session), so a client can tell in one round trip whether the active branch moved. If `since` does not match any entry id, the response is `success: false`.
+Moved to [RPC protocol](/rpc/protocol#get_entries).
 
 #### get_tree
 
-Get the session as a tree of entries. Each node is `{entry, children, label?, labelTimestamp?}`. A well-formed session has a single root; orphaned entries (broken parent chain) also appear as roots.
-
-```json
-{"type": "get_tree"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_tree",
-  "success": true,
-  "data": {
-    "tree": [
-      {
-        "entry": {"type": "message", "id": "abc123", "parentId": null, "...": "..."},
-        "children": [
-          {"entry": {"type": "message", "id": "def456", "parentId": "abc123", "...": "..."}, "children": []}
-        ]
-      }
-    ],
-    "leafId": "def456"
-  }
-}
-```
+Moved to [RPC protocol](/rpc/protocol#get_tree).
 
 #### get_last_assistant_text
 
-Get the text content of the last assistant message.
-
-```json
-{"type": "get_last_assistant_text"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_last_assistant_text",
-  "success": true,
-  "data": {"text": "The assistant's response..."}
-}
-```
-
-Returns `{"text": null}` if no assistant messages exist.
+Moved to [RPC protocol](/rpc/protocol#get_last_assistant_text).
 
 #### set_session_name
 
-Set a display name for the current session. The name appears in session listings and helps identify sessions.
-
-```json
-{"type": "set_session_name", "name": "my-feature-work"}
-```
-
-Response:
-```json
-{
-  "type": "response",
-  "command": "set_session_name",
-  "success": true
-}
-```
-
-The current session name is available via `get_state` in the `sessionName` field. To set the initial name when starting RPC mode, pass `--name <name>` or `-n <name>` to the `atomic --mode rpc` process.
+Moved to [RPC protocol](/rpc/protocol#set_session_name).
 
 ### Commands
 
-#### get_commands
-
-Get available commands (extension commands, prompt templates, and skills). These can be invoked via the `prompt` command by prefixing with `/`.
-
-```json
-{"type": "get_commands"}
-```
+Moved to [RPC protocol](/rpc/protocol#commands-2).
 
-Response:
-```json
-{
-  "type": "response",
-  "command": "get_commands",
-  "success": true,
-  "data": {
-    "commands": [
-      {"name": "session-name", "description": "Set or clear session name", "source": "extension", "path": "/home/user/.atomic/agent/extensions/session.ts"},
-      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.atomic/prompts/fix-tests.md"},
-      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.atomic/agent/skills/brave-search/SKILL.md"}
-    ]
-  }
-}
-```
+#### get_commands
 
-Each command has:
-- `name`: Command name (invoke with `/name`)
-- `description`: Human-readable description (optional for extension commands)
-- `source`: What kind of command:
-  - `"extension"`: Registered via `pi.registerCommand()` in an extension
-  - `"prompt"`: Loaded from a prompt template `.md` file
-  - `"skill"`: Loaded from a skill directory (name is prefixed with `skill:`)
-- `location`: Where it was loaded from (optional, not present for extensions):
-  - `"user"`: User-level (`~/.atomic/agent/`)
-  - `"project"`: Project-level (`./.atomic/`)
-  - `"path"`: Explicit path via CLI or settings
-- `path`: Absolute file path to the command source (optional)
-
-**Note**: Built-in TUI commands (`/settings`, `/hotkeys`, etc.) are not included. They are handled only in interactive mode and would not execute if sent via `prompt`.
+Moved to [RPC protocol](/rpc/protocol#get_commands).
 
 ## Events
 
-Events are streamed to stdout as JSON lines. Most events do not include an `id`; `bash_execution_update` is the deliberate exception and uses the originating bash request ID.
+Moved to [RPC protocol](/rpc/protocol#events).
 
 ### Event Types
 
-| Event | Description |
-|-------|-------------|
-| `agent_start` | Agent begins processing |
-| `agent_end` | Agent completes (includes all generated messages) |
-| `turn_start` | New turn begins |
-| `turn_end` | Turn completes (includes assistant message and tool results) |
-| `message_start` | Message begins |
-| `message_update` | Streaming update (text/thinking/toolcall deltas) |
-| `message_end` | Message completes |
-| `tool_execution_start` | Tool begins execution; includes `toolCallId`, `toolName`, and initial arguments |
-| `tool_execution_update` | Tool execution progress (streaming output) |
-| `tool_execution_end` | Tool completes |
-| `bash_execution_update` | Correlated direct-bash stdout/stderr delta |
-| `queue_update` | Pending steering/follow-up queue changed |
-| `compaction_start` | Verbatim line compaction begins |
-| `compaction_end` | Verbatim line compaction completes |
-| `auto_retry_start` | Auto-retry begins (after transient error) |
-| `auto_retry_end` | Auto-retry completes (success or final failure) |
-| `summarization_retry_scheduled` | Retry scheduled for a transient compaction or branch-summary provider error |
-| `summarization_retry_attempt_start` | Retried summarization request starts |
-| `summarization_retry_finished` | Summarization retry loop completes |
-| `extension_error` | Extension threw an error |
+Moved to [RPC protocol](/rpc/protocol#event-types).
 
 ### agent_start
 
-Emitted when the agent begins processing a prompt.
-
-```json
-{"type": "agent_start"}
-```
+Moved to [RPC protocol](/rpc/protocol#agent_start).
 
 ### agent_end
 
-Emitted when the agent completes. Contains all messages generated during this run.
-
-```json
-{
-  "type": "agent_end",
-  "messages": [...]
-}
-```
+Moved to [RPC protocol](/rpc/protocol#agent_end).
 
 ### turn_start / turn_end
 
-A turn consists of one assistant response plus any resulting tool calls and results.
-
-```json
-{"type": "turn_start"}
-```
-
-```json
-{
-  "type": "turn_end",
-  "message": {...},
-  "toolResults": [...]
-}
-```
+Moved to [RPC protocol](/rpc/protocol#turn_start-/-turn_end).
 
 ### message_start / message_end
 
-Emitted when a message begins and completes. The `message` field contains an `AgentMessage`.
-
-```json
-{"type": "message_start", "message": {...}}
-{"type": "message_end", "message": {...}}
-```
+Moved to [RPC protocol](/rpc/protocol#message_start-/-message_end).
 
 ### message_update (Streaming)
 
-Emitted during streaming of assistant messages. Carries the streaming delta plus the latest cumulative usage.
-
-`message_update` deliberately omits the cumulative message snapshot: there is no `message`
-field, and `assistantMessageEvent` has no `partial`. `message_start` provides the
-initial message, the deltas build it, and `message_end` provides the final
-authoritative message. Repeating a snapshot on every frame would make the bytes
-written per assistant turn grow with the square of its length.
-
-The top-level `usage` field carries the latest cumulative provider-reported usage; it may
-remain zero until completion when a provider does not report usage during streaming. When
-the provider reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`,
-for example OpenAI Codex `end_turn`), the update carries it as a top-level `endTurn`
-boolean — present only when the provider reported one.
-
-```json
-{
-  "type": "message_update",
-  "usage": {
-    "input": 100,
-    "output": 1,
-    "cacheRead": 0,
-    "cacheWrite": 0,
-    "totalTokens": 101,
-    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}
-  },
-  "assistantMessageEvent": {
-    "type": "text_delta",
-    "contentIndex": 0,
-    "delta": "Hello "
-  }
-}
-```
-
-The `assistantMessageEvent` field contains one of these delta types:
-
-| Type | Description |
-|------|-------------|
-| `start` | Message generation started |
-| `text_start` | Text content block started |
-| `text_delta` | Text content chunk |
-| `text_end` | Text content block ended |
-| `thinking_start` | Thinking block started |
-| `thinking_delta` | Thinking content chunk |
-| `thinking_end` | Thinking block ended |
-| `toolcall_start` | Tool call started |
-| `toolcall_delta` | Tool call arguments chunk |
-| `toolcall_end` | Tool call ended (includes full `toolCall` object) |
-| `done` | Message complete (reason: `"stop"`, `"length"`, `"toolUse"`) |
-| `error` | Error occurred (reason: `"aborted"`, `"error"`) |
-
-Example streaming a text response:
-```json
-{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
-{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
-{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
-{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
-```
+Moved to [RPC protocol](/rpc/protocol#message_update-streaming).
 
 ### tool_execution_start / tool_execution_update / tool_execution_end
 
-Emitted when a tool begins, streams progress, and completes execution.
-
-```json
-{
-  "type": "tool_execution_start",
-  "toolCallId": "call_abc123",
-  "toolName": "bash",
-  "args": {"command": "ls -la"}
-}
-```
-
-During execution, `tool_execution_update` events stream partial results (e.g., bash output as it arrives):
-
-```json
-{
-  "type": "tool_execution_update",
-  "toolCallId": "call_abc123",
-  "toolName": "bash",
-  "args": {"command": "ls -la"},
-  "partialResult": {
-    "content": [{"type": "text", "text": "partial output so far..."}],
-    "details": {"truncation": null, "fullOutputPath": null}
-  }
-}
-```
-
-When complete:
-
-```json
-{
-  "type": "tool_execution_end",
-  "toolCallId": "call_abc123",
-  "toolName": "bash",
-  "result": {
-    "content": [{"type": "text", "text": "total 48\n..."}],
-    "details": {...}
-  },
-  "isError": false
-}
-```
-
-Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.
+Moved to [RPC protocol](/rpc/protocol#tool_execution_start-/-tool_execution_update-/-tool_execution_end).
 
 ### bash_execution_update
 
-Emitted only for direct `bash` and non-intercepted `user_bash` RPC execution. Each event is `{type, id?, channel, delta}` where `channel` is `"stdout"` or `"stderr"`; use `id` to keep concurrent streams separate. Tool-call bash continues to use `tool_execution_update` and its `toolCallId`.
+Moved to [RPC protocol](/rpc/protocol#bash_execution_update).
 
 ### queue_update
 
-Emitted whenever the pending steering or follow-up queue changes.
-
-```json
-{
-  "type": "queue_update",
-  "steering": ["Focus on error handling"],
-  "followUp": ["After that, summarize the result"]
-}
-```
+Moved to [RPC protocol](/rpc/protocol#queue_update).
 
 ### compaction_start / compaction_end
 
-Emitted when default Verbatim Compaction runs, whether manual or automatic. The result records deletion targets and stats rather than a generated summary.
-
-```json
-{"type": "compaction_start", "reason": "threshold"}
-```
-
-The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
-
-```json
-{
-  "type": "compaction_end",
-  "reason": "threshold",
-  "result": {
-    "compactedText": "[User]: fix the test\n(filtered 42 lines)",
-    "firstKeptEntryId": "m7",
-    "tokensBefore": 150000,
-    "promptVersion": 3,
-    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the test"},
-    "rung": "planned",
-    "stats": {
-      "linesBefore": 812,
-      "linesDeleted": 417,
-      "linesKept": 395,
-      "rangeCount": 63,
-      "tokensBefore": 150000,
-      "tokensAfter": 72000,
-      "percentReduction": 52
-    }
-  },
-  "aborted": false,
-  "willRetry": false
-}
-```
-
-If `reason` was `"overflow"` and compaction succeeds, `willRetry` is `true` and the agent will automatically retry the prompt. Public prompt/RPC callers wait for that post-compaction continuation before the prompt is considered complete.
-
-If compaction was aborted, `result` is `null` and `aborted` is `true`.
-
-If compaction failed (e.g., API quota exceeded), `result` is `null`, `aborted` is `false`, and `errorMessage` contains the error description.
-
-`result` and `errorMessage` are independent. A mid-turn post-tool compaction can commit a boundary and *then* fail the provider hard-input-limit gate, so one `compaction_end` may carry both a non-null `result` and an `errorMessage`. Treat the result as a committed durable boundary in that case; the error describes the follow-up request that was not sent.
-
-If overflow recovery exhausts the same-model compact-and-retry attempt, `compaction_end` includes `"unresolvedOverflow": true` and an `errorMessage`. Workflow orchestration treats that signal as a context-length failure that can advance configured model fallback tiers.
-
-There is no `context_compact` command; Atomic reports it as an unknown command. Use `compact`. Only `compaction_start` and `compaction_end` events are emitted.
+Moved to [RPC protocol](/rpc/protocol#compaction_start-/-compaction_end).
 
 ### auto_retry_start / auto_retry_end
 
-Emitted when automatic retry is triggered after a transient error (overloaded, rate limit, 5xx).
-
-```json
-{
-  "type": "auto_retry_start",
-  "attempt": 1,
-  "maxAttempts": 3,
-  "delayMs": 2000,
-  "errorMessage": "529 {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}}"
-}
-```
-
-```json
-{
-  "type": "auto_retry_end",
-  "success": true,
-  "attempt": 2
-}
-```
-
-On final failure (max retries exceeded):
-```json
-{
-  "type": "auto_retry_end",
-  "success": false,
-  "attempt": 3,
-  "finalError": "529 overloaded_error: Overloaded"
-}
-```
-
+Moved to [RPC protocol](/rpc/protocol#auto_retry_start-/-auto_retry_end).
 
 ### summarization_retry_scheduled / summarization_retry_attempt_start / summarization_retry_finished
 
-Emitted when compaction planning or branch summarization retries after a transient provider error. These events use the same retry settings as automatic assistant-turn retries.
-
-```json
-{
-  "type": "summarization_retry_scheduled",
-  "attempt": 1,
-  "maxAttempts": 3,
-  "delayMs": 2000,
-  "errorMessage": "terminated"
-}
-```
-
-```json
-{
-  "type": "summarization_retry_attempt_start",
-  "source": "compaction",
-  "reason": "threshold"
-}
-```
-
-For branch summaries, `source` is `"branchSummary"` and no `reason` is present. The loop then emits:
+Moved to [RPC protocol](/rpc/protocol#summarization_retry_scheduled-/-summarization_retry_attempt_start-/-summarization_retry_finished).
 
-```json
-{"type": "summarization_retry_finished"}
-```
 ### extension_error
 
-Emitted when an extension throws an error.
-
-```json
-{
-  "type": "extension_error",
-  "extensionPath": "/path/to/extension.ts",
-  "event": "tool_call",
-  "error": "Error message..."
-}
-```
+Moved to [RPC protocol](/rpc/protocol#extension_error).
 
 ## Extension UI Protocol
 
-Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()`, etc. In RPC mode, these are translated into a request/response sub-protocol on top of the base command/event flow.
-
-There are two categories of extension UI methods:
-
-- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
-- **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
-
-If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
-
-Some `ExtensionUIContext` methods are not supported or degraded in RPC mode because they require direct TUI access:
-- `custom()` returns `undefined`
-- `setWorkingMessage()`, `setWorkingIndicator()`, `setFooter()`, `setHeader()`, `setEditorComponent()` are no-ops
-- `getEditorText()` returns `""`
-- `setToolsExpanded()` and `getToolsExpanded()` maintain context-local expansion state; `getChatRenderSettings().toolOutputExpanded` reports the same value. A same-value `setToolsExpanded()` call is a no-op and does not request a custom-UI render. This state is not sent through the client extension-UI protocol.
-- `pasteToEditor()` delegates to `setEditorText()` (no paste/collapse handling)
-- `getAllThemes()` returns `[]`
-- `getTheme()` returns `undefined`
-- `setTheme()` returns `{ success: false, error: "..." }`
-
-Note: `ctx.mode` is `"rpc"` and `ctx.hasUI` is `true` in RPC mode because the dialog and fire-and-forget methods are functional via the extension UI sub-protocol. Use `ctx.mode === "tui"` to guard TUI-specific features like `custom()` that require a real terminal.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#extension-ui-protocol).
 
 ### Extension UI Requests (stdout)
 
-All requests have `type: "extension_ui_request"`, a unique `id`, and a `method` field.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#extension-ui-requests-stdout).
 
 #### select
 
-Prompt the user to choose from a list. Dialog methods with a `timeout` field include the timeout in milliseconds; the agent auto-resolves with `undefined` if the client doesn't respond in time.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-1",
-  "method": "select",
-  "title": "Allow dangerous command?",
-  "options": ["Allow", "Block"],
-  "timeout": 10000
-}
-```
-
-Expected response: `extension_ui_response` with `value` (the selected option string) or `cancelled: true`.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#select).
 
 #### confirm
 
-Prompt the user for yes/no confirmation.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-2",
-  "method": "confirm",
-  "title": "Clear session?",
-  "message": "All messages will be lost.",
-  "timeout": 5000
-}
-```
-
-Expected response: `extension_ui_response` with `confirmed: true/false` or `cancelled: true`.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#confirm).
 
 #### input
 
-Prompt the user for free-form text.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-3",
-  "method": "input",
-  "title": "Enter a value",
-  "placeholder": "type something..."
-}
-```
-
-Expected response: `extension_ui_response` with `value` (the entered text) or `cancelled: true`.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#input).
 
 #### editor
 
-Open a multi-line text editor with optional prefilled content.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-4",
-  "method": "editor",
-  "title": "Edit some text",
-  "prefill": "Line 1\nLine 2\nLine 3"
-}
-```
-
-Expected response: `extension_ui_response` with `value` (the edited text) or `cancelled: true`.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#editor).
 
 #### notify
 
-Display a notification. Fire-and-forget, no response expected.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-5",
-  "method": "notify",
-  "message": "Command blocked by user",
-  "notifyType": "warning"
-}
-```
-
-The `notifyType` field is `"info"`, `"warning"`, or `"error"`. Defaults to `"info"` if omitted.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#notify).
 
 #### setStatus
 
-Set or clear a status entry in the footer/status bar. Fire-and-forget.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-6",
-  "method": "setStatus",
-  "statusKey": "my-ext",
-  "statusText": "Turn 3 running..."
-}
-```
-
-Send `statusText: undefined` (or omit it) to clear the status entry for that key.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#setstatus).
 
 #### setWidget
 
-Set or clear a widget (block of text lines) displayed above or below the editor. Fire-and-forget.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-7",
-  "method": "setWidget",
-  "widgetKey": "my-ext",
-  "widgetLines": ["--- My Widget ---", "Line 1", "Line 2"],
-  "widgetPlacement": "aboveEditor"
-}
-```
-
-Send `widgetLines: undefined` (or omit it) to clear the widget. The `widgetPlacement` field is `"aboveEditor"` (default) or `"belowEditor"`. Only string arrays are supported in RPC mode; component factories are ignored.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#setwidget).
 
 #### setTitle
 
-Set the terminal window/tab title. Fire-and-forget.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-8",
-  "method": "setTitle",
-  "title": "atomic - my project"
-}
-```
+Moved to [RPC extension UI protocol](/rpc/extension-ui#settitle).
 
 #### set_editor_text
 
-Set the text in the input editor. Fire-and-forget.
-
-```json
-{
-  "type": "extension_ui_request",
-  "id": "uuid-9",
-  "method": "set_editor_text",
-  "text": "prefilled text for the user"
-}
-```
+Moved to [RPC extension UI protocol](/rpc/extension-ui#set_editor_text).
 
 ### Extension UI Responses (stdin)
 
-Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+Moved to [RPC extension UI protocol](/rpc/extension-ui#extension-ui-responses-stdin).
 
 #### Value response (select, input, editor)
 
-```json
-{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}
-```
+Moved to [RPC extension UI protocol](/rpc/extension-ui#value-response-select-input-editor).
 
 #### Confirmation response (confirm)
 
-```json
-{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}
-```
+Moved to [RPC extension UI protocol](/rpc/extension-ui#confirmation-response-confirm).
 
 #### Cancellation response (any dialog)
 
-Dismiss any dialog method. The extension receives `undefined` (for select/input/editor) or `false` (for confirm).
-
-```json
-{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}
-```
+Moved to [RPC extension UI protocol](/rpc/extension-ui#cancellation-response-any-dialog).
 
 ## Error Handling
 
-Failed commands return a response with `success: false`:
-
-```json
-{
-  "type": "response",
-  "command": "set_model",
-  "success": false,
-  "error": "Model not found: invalid/model"
-}
-```
-
-Parse errors:
-
-```json
-{
-  "type": "response",
-  "command": "parse",
-  "success": false,
-  "error": "Failed to parse command: Unexpected token..."
-}
-```
+Moved to [RPC protocol](/rpc/protocol#error-handling).
 
 ## Types
 
-Source files and installed definitions:
-- `node_modules/@bastani/pi-ai/dist/types.d.ts` - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
-- `node_modules/@earendil-works/pi-agent-core/dist/types.d.ts` - `AgentMessage`, `AgentEvent`
-- [`src/core/messages.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/messages.ts) - `BashExecutionMessage`
-- [`src/modes/rpc/rpc-types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
+Moved to [RPC protocol](/rpc/protocol#types).
 
 ### Model
 
-```json
-{
-  "id": "claude-sonnet-4-20250514",
-  "name": "Claude Sonnet 4",
-  "api": "anthropic-messages",
-  "provider": "anthropic",
-  "baseUrl": "https://api.anthropic.com",
-  "reasoning": true,
-  "input": ["text", "image"],
-  "contextWindow": 200000,
-  "maxTokens": 16384,
-  "cost": {
-    "input": 3.0,
-    "output": 15.0,
-    "cacheRead": 0.3,
-    "cacheWrite": 3.75
-  }
-}
-```
-
-`contextWindow` is the model's token budget used by Atomic's local budgeting, footer/stats, and compaction logic.
+Moved to [RPC protocol](/rpc/protocol#model-2).
 
 ### UserMessage
 
-```json
-{
-  "role": "user",
-  "content": "Hello!",
-  "timestamp": 1733234567890
-}
-```
-
-The `content` field can be a string or an array of `TextContent`/`ImageContent` blocks.
+Moved to [RPC protocol](/rpc/protocol#usermessage).
 
 ### AssistantMessage
 
-```json
-{
-  "role": "assistant",
-  "content": [
-    {"type": "text", "text": "Hello! How can I help?"},
-    {"type": "thinking", "thinking": "User is greeting me..."},
-    {"type": "toolCall", "id": "call_123", "name": "bash", "arguments": {"command": "ls"}}
-  ],
-  "api": "anthropic-messages",
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-20250514",
-  "usage": {
-    "input": 100,
-    "output": 50,
-    "cacheRead": 0,
-    "cacheWrite": 0,
-    "cost": {"input": 0.0003, "output": 0.00075, "cacheRead": 0, "cacheWrite": 0, "total": 0.00105}
-  },
-  "stopReason": "stop",
-  "timestamp": 1733234567890
-}
-```
-
-Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`. A streaming message carries `"pending"` until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it. On the wire the pending reason appears on the `message_start` message — `message_update` frames carry no message at all — and `message_end` carries the terminal reason. A provider that reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`, for example OpenAI Codex `end_turn`) sets `endTurn: true` on the assistant message; `message_update` frames echo it as a top-level boolean only when the provider reported one.
+Moved to [RPC protocol](/rpc/protocol#assistantmessage).
 
 ### ToolResultMessage
 
-```json
-{
-  "role": "toolResult",
-  "toolCallId": "call_123",
-  "toolName": "bash",
-  "content": [{"type": "text", "text": "total 48\ndrwxr-xr-x ..."}],
-  "isError": false,
-  "timestamp": 1733234567890
-}
-```
+Moved to [RPC protocol](/rpc/protocol#toolresultmessage).
 
 ### BashExecutionMessage
 
-Created by the `bash` RPC command (not by LLM tool calls):
-
-```json
-{
-  "role": "bashExecution",
-  "command": "ls -la",
-  "output": "total 48\ndrwxr-xr-x ...",
-  "exitCode": 0,
-  "cancelled": false,
-  "truncated": false,
-  "fullOutputPath": null,
-  "timestamp": 1733234567890
-}
-```
+Moved to [RPC protocol](/rpc/protocol#bashexecutionmessage).
 
 ### Attachment
 
-```json
-{
-  "id": "img1",
-  "type": "image",
-  "fileName": "photo.jpg",
-  "mimeType": "image/jpeg",
-  "size": 102400,
-  "content": "base64-encoded-data...",
-  "extractedText": null,
-  "preview": null
-}
-```
+Moved to [RPC protocol](/rpc/protocol#attachment).
 
 ## Example: Basic Client (Python)
 
@@ -1604,58 +421,4 @@ for event in read_events():
 
 ## Example: Interactive Client (Node.js)
 
-See [`test/rpc-example.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) for a typed client implementation.
-
-For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/rpc-demo.ts) extension.
-
-```javascript
-const { spawn } = require("child_process");
-const { StringDecoder } = require("string_decoder");
-
-const agent = spawn("atomic", ["--mode", "rpc", "--no-session"]);
-
-function attachJsonlReader(stream, onLine) {
-    const decoder = new StringDecoder("utf8");
-    let buffer = "";
-
-    stream.on("data", (chunk) => {
-        buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
-
-        while (true) {
-            const newlineIndex = buffer.indexOf("\n");
-            if (newlineIndex === -1) break;
-
-            let line = buffer.slice(0, newlineIndex);
-            buffer = buffer.slice(newlineIndex + 1);
-            if (line.endsWith("\r")) line = line.slice(0, -1);
-            onLine(line);
-        }
-    });
-
-    stream.on("end", () => {
-        buffer += decoder.end();
-        if (buffer.length > 0) {
-            onLine(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
-        }
-    });
-}
-
-attachJsonlReader(agent.stdout, (line) => {
-    const event = JSON.parse(line);
-
-    if (event.type === "message_update") {
-        const { assistantMessageEvent } = event;
-        if (assistantMessageEvent.type === "text_delta") {
-            process.stdout.write(assistantMessageEvent.delta);
-        }
-    }
-});
-
-// Send prompt
-agent.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");
-
-// Abort on CTRL+C
-process.on("SIGINT", () => {
-    agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n");
-});
-```
+Moved to [RPC client examples](/rpc/examples#example-interactive-client-node-js).