@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/docs/rpc.md

@@ -0,0 +1,2050 @@
+# 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 `@hansjm10/volt-coding-agent` instead of spawning a subprocess. See [`src/core/agent-session.ts`](../src/core/agent-session.ts) for the API. For typed RPC clients, use [`RpcClient`](../src/modes/rpc/rpc-client.ts) for subprocess stdio, [`RpcTransportClient`](../src/modes/rpc/rpc-transport-client.ts) for caller-provided transports, or [`createInProcessRpcClient`](../src/modes/rpc/in-process-rpc-client.ts) to run RPC mode in the same process.
+
+## Starting RPC Mode
+
+```bash
+volt --mode rpc [options]
+```
+
+Common options:
+- `--provider <name>`: Set the LLM provider (anthropic, openai, google, etc.)
+- `--model <pattern>`: Model pattern or ID (supports `provider/id` and optional `:<thinking>`)
+- `--name <name>` / `-n <name>`: Set the session display name at startup
+- `--no-session`: Disable session persistence
+- `--session-dir <path>`: Custom session storage directory
+
+## Protocol Overview
+
+- **Commands**: JSON objects sent to stdin, one per line
+- **Responses**: JSON objects with `type: "response"` indicating command success/failure
+- **Events**: Agent events streamed to stdout as JSON lines
+
+All commands support an optional `id` field for request/response correlation. If provided, the corresponding response will include the same `id`.
+
+### Framing
+
+RPC mode uses strict JSONL semantics with LF (`\n`) as the only record delimiter.
+
+This matters for clients:
+- Split records on `\n` only
+- Accept optional `\r\n` input by stripping a trailing `\r`
+- Do not use generic line readers that treat Unicode separators as newlines
+
+In particular, Node `readline` is not protocol-compliant for RPC mode because it also splits on `U+2028` and `U+2029`, which are valid inside JSON strings.
+
+### Lifecycle and Cancellation
+
+Transport lifetime is separate from cancellation semantics. A clean input close, socket close, stream EOF, or write failure is a transport event, not an RPC command, and must not be interpreted as an implicit `abort`.
+
+Clients that intend to stop active agent work must send the `abort` command and wait for its response. Plain subprocess RPC mode still treats transport close as mode/process shutdown, and remote transports may use close as detach/reconnect; neither path changes the RPC cancellation command.
+
+RPC mode is not durable job recovery. If the Volt process or embedding host process exits or crashes, in-memory work stops; clients can only reopen persisted session state that was written before exit.
+
+## 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!"}
+```
+
+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 `volt.sendMessage()`.
+
+**Input expansion**: Skill commands (`/skill:name`) and prompt templates (`/template`) are expanded before sending/queueing.
+
+Response:
+```json
+{"id": "req-1", "type": "response", "command": "prompt", "success": true}
+```
+
+`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.
+
+The `images` field is optional. Each image uses `ImageContent` format: `{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}`.
+
+#### 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.
+
+#### 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.
+
+#### abort
+
+Abort the current agent operation.
+
+```json
+{"type": "abort"}
+```
+
+Response:
+```json
+{"type": "response", "command": "abort", "success": true}
+```
+
+`abort` is the semantic cancellation command. Closing the RPC transport without sending `abort` requests transport shutdown or remote detach according to the transport, but it does not ask Volt to cancel the active run.
+
+#### 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}}
+```
+
+### State
+
+#### get_state
+
+Get current session state.
+
+```json
+{"type": "get_state"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_state",
+  "success": true,
+  "data": {
+    "model": {...},
+    "thinkingLevel": "medium",
+    "availableThinkingLevels": ["off", "minimal", "low", "medium", "high"],
+    "isStreaming": false,
+    "isBusy": true,
+    "isCompacting": true,
+    "steeringMode": "all",
+    "followUpMode": "one-at-a-time",
+    "sessionFile": "/path/to/session.jsonl",
+    "sessionId": "abc123",
+    "sessionName": "my-feature-work",
+    "autoCompactionEnabled": true,
+    "messageCount": 5,
+    "pendingMessageCount": 0,
+    "activeCompaction": {"reason": "threshold", "startedAt": 1782470400000}
+  }
+}
+```
+
+The `model` field is a full [Model](#model) object or `null`. `availableThinkingLevels` lists the thinking levels the current model supports (`["off"]` for non-reasoning models). `isStreaming` indicates an active provider run or session-level continuation; `isBusy` also includes asynchronous prompt preflight and standalone session operations such as manual compaction and tree navigation. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set. `activeCompaction` is present only while context compaction is currently running; `startedAt` is Unix epoch milliseconds.
+
+#### get_transcript
+
+Get a UI-ready projected transcript for the active session. The response is ordered oldest-to-newest and omits raw provider payloads, thinking blocks, image data, raw tool output, full file contents, and session file paths. Text, summaries, and mutation previews are bounded.
+
+```json
+{"type": "get_transcript", "limit": 100}
+```
+
+Use `beforeEntryId` to request older items than the first item already loaded:
+
+```json
+{"type": "get_transcript", "limit": 100, "beforeEntryId": "entry-id"}
+```
+
+`limit` defaults to 100 and is capped at 200.
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_transcript",
+  "success": true,
+  "data": {
+    "sessionId": "abc123",
+    "items": [
+      {"id": "entry-user", "role": "user", "text": "User prompt", "timestamp": "2026-06-22T15:00:00.000Z"},
+      {"id": "entry-assistant", "role": "assistant", "text": "Assistant response", "timestamp": "2026-06-22T15:01:00.000Z"},
+      {"id": "entry-tool", "role": "tool", "toolName": "read", "status": "completed", "path": "src/file.ts", "summary": "Read src/file.ts (completed)", "timestamp": "2026-06-22T15:01:30.000Z"},
+      {"id": "entry-summary", "role": "summary", "title": "Conversation compacted", "text": "Earlier conversation summary...", "timestamp": "2026-06-22T15:02:00.000Z"}
+    ],
+    "hasMore": false,
+    "nextBeforeEntryId": null
+  }
+}
+```
+
+Tool items may include bounded `diffPreview` and `patchPreview` fields for mutation tools.
+
+Recommended resume flow for remote or headless UI clients:
+
+1. After a successful connection or reconnect, send `get_state`, then `get_transcript` for the active persisted session.
+2. After a successful `switch_session_by_id`, clear or replace the visible transcript with a loading state, refresh with `get_state`, then call `get_transcript` for the selected session.
+3. After a successful `new_session`, refresh state only and keep the fresh empty transcript; do not reuse or load older transcript from the previous session.
+4. For pagination, keep `hasMore` and `nextBeforeEntryId`; when `hasMore` is true, request older items with `beforeEntryId` and prepend returned items by stable `id`.
+
+#### 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 [Message Types](#message-types)).
+
+### Subagents (local RPC only)
+
+Local RPC clients can manage definition-backed subagents over the same connection. These commands are local RPC only for now; Iroh remote transports reject them until a later explicit remote policy slice.
+
+#### list_subagents
+
+List built-in and discovered subagent definition summaries. The response omits definition file paths, source paths, base directories, and system prompts.
+
+```json
+{"type": "list_subagents"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "list_subagents",
+  "success": true,
+  "data": {
+    "subagents": [
+      {
+        "name": "scout",
+        "description": "Fast codebase reconnaissance",
+        "source": "project",
+        "sourceInfo": {"source": "local", "scope": "project", "origin": "top-level"},
+        "tools": ["read", "grep", "find", "ls"],
+        "model": "claude-haiku-4-5",
+        "thinking": "off"
+      }
+    ]
+  }
+}
+```
+
+#### subagent_start
+
+Start a definition-backed child subagent, send its initial prompt, and return after the prompt is accepted. Child tools are clamped by the current parent/session tool policy.
+
+```json
+{"type": "subagent_start", "agent": "scout", "prompt": "Find auth code"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "subagent_start",
+  "success": true,
+  "data": {"subagentId": "sa_123", "sessionId": "child-session-id"}
+}
+```
+
+Child events are wrapped on the parent RPC stream:
+
+```json
+{"type": "subagent_event", "subagentId": "sa_123", "event": {"type": "agent_start"}}
+{"type": "subagent_end", "subagentId": "sa_123", "result": {"id": "sa_123", "sessionId": "child-session-id", "event": {"type": "agent_end", "messages": [], "willRetry": false}}}
+```
+
+`subagent_event.event` is the child RPC event. `subagent_end.result` is emitted after the child session settles, including automatic retries, overflow compaction, and queued continuations. The result contains the latest low-level `agent_end` event; `willRetry` is normalized to `false` if a planned retry was cancelled before another run started.
+
+#### subagent_abort
+
+Abort and dispose a local RPC-managed subagent.
+
+```json
+{"type": "subagent_abort", "subagentId": "sa_123"}
+```
+
+Response:
+```json
+{"type": "response", "command": "subagent_abort", "success": true}
+```
+
+#### subagent_get_state
+
+Get the child session state for an active local RPC-managed subagent.
+
+```json
+{"type": "subagent_get_state", "subagentId": "sa_123"}
+```
+
+Response data uses the same shape as [`get_state`](#get_state).
+
+#### subagent_get_transcript
+
+Get the child transcript projection for an active local RPC-managed subagent.
+
+```json
+{"type": "subagent_get_transcript", "subagentId": "sa_123", "limit": 100, "beforeEntryId": "entry-id"}
+```
+
+Response data uses the same shape as [`get_transcript`](#get_transcript).
+
+#### subagent_dispose
+
+Dispose a local RPC-managed subagent and remove it from this RPC connection's active subagent map. Later commands for the same `subagentId` fail with the normal RPC error shape.
+
+```json
+{"type": "subagent_dispose", "subagentId": "sa_123"}
+```
+
+Response:
+```json
+{"type": "response", "command": "subagent_dispose", "success": true}
+```
+
+Active RPC-started subagents are scoped to the RPC connection/runtime and are disposed on RPC shutdown and session replacement.
+
+### MCP management
+
+Local RPC clients can inspect and manage configured MCP servers. Iroh remote transports allow only the remote-safe subset: capabilities, list/get server status, recent calls, disconnect, and device-code auth start/poll/cancel.
+
+#### get_mcp_capabilities
+
+```json
+{"type": "get_mcp_capabilities"}
+```
+
+Response data:
+
+```json
+{"protocolVersion": 1, "features": ["mcp_management.v1", "mcp_oauth.v1", "mcp_device_auth.v1", "mcp_events.v1"], "remoteSafeByDefault": ["list_mcp_servers", "get_mcp_server", "list_mcp_recent_calls", "disconnect_mcp_server", "start_mcp_server_auth", "poll_mcp_server_auth", "cancel_mcp_server_auth"]}
+```
+
+#### list_mcp_servers / get_mcp_server
+
+```json
+{"type": "list_mcp_servers"}
+{"type": "get_mcp_server", "server": "github"}
+```
+
+Responses return sanitized server summaries with status, auth state, transport/lifecycle, tool counts, capabilities, and recent call summaries. File paths, raw env, headers, tokens, and schemas are omitted.
+
+#### connect_mcp_server / refresh_mcp_server / disconnect_mcp_server / set_mcp_server_enabled
+
+```json
+{"type": "connect_mcp_server", "server": "github"}
+{"type": "refresh_mcp_server", "server": "github"}
+{"type": "disconnect_mcp_server", "server": "github"}
+{"type": "set_mcp_server_enabled", "server": "github", "enabled": false}
+```
+
+`connect_mcp_server` and `refresh_mcp_server` connect to the MCP server and refresh cached metadata; they are local RPC only. `disconnect_mcp_server` closes a live connection. `set_mcp_server_enabled` persists an overlay in the relevant Volt-owned MCP config file and is local RPC only.
+
+#### MCP OAuth auth
+
+Browser auth-code + PKCE is local RPC only:
+
+```json
+{"type": "start_mcp_server_auth", "server": "linear", "flow": "browser", "redirectUrl": "http://127.0.0.1:49152/mcp/oauth/callback/random"}
+{"type": "complete_mcp_server_auth", "server": "linear", "redirectUrl": "http://127.0.0.1:49152/mcp/oauth/callback/random", "code": "...", "state": "..."}
+```
+
+Device-code auth can be started and polled over local RPC or Iroh remote transports:
+
+```json
+{"type": "start_mcp_server_auth", "server": "linear", "flow": "device"}
+{"type": "poll_mcp_server_auth", "server": "linear"}
+{"type": "cancel_mcp_server_auth", "server": "linear"}
+```
+
+`start_mcp_server_auth` with `flow: "device"` returns `verificationUri`, optional `verificationUriComplete`, `userCode`, `expiresAt`, and `intervalMs`; it never returns the OAuth `device_code`. Tokens stay on the host in MCP OAuth storage. `logout_mcp_server` clears stored OAuth credentials and is local RPC only.
+
+#### list_mcp_tools / get_mcp_tool
+
+```json
+{"type": "list_mcp_tools", "server": "github"}
+{"type": "get_mcp_tool", "server": "github", "tool": "search_issues"}
+```
+
+Returns sanitized tool metadata, risk classification, metadata hash, stale flag, and whether the tool is currently promoted as a direct tool.
+
+#### list_mcp_resources / read_mcp_resource
+
+```json
+{"type": "list_mcp_resources", "server": "docs"}
+{"type": "read_mcp_resource", "server": "docs", "resourceUri": "file:///guide.md"}
+```
+
+Resource contents are returned through the same truncation/cache shaping as the `mcp` gateway. Remote transports do not expose resource listing or content reads by default because those operations can start MCP backends.
+
+#### list_mcp_prompts / get_mcp_prompt
+
+```json
+{"type": "list_mcp_prompts", "server": "prompts"}
+{"type": "get_mcp_prompt", "server": "prompts", "prompt": "review", "arguments": {"focus": "security"}}
+```
+
+Prompt content is available for user-initiated preview when prompts are not disabled; model-initiated access still requires `settings.prompts: "model"`. Remote transports do not expose prompt listing or content reads by default because those operations can start MCP backends.
+
+#### list_mcp_recent_calls
+
+```json
+{"type": "list_mcp_recent_calls"}
+{"type": "list_mcp_recent_calls", "server": "github"}
+```
+
+Returns bounded recent MCP tool-call summaries for one server or all servers.
+
+### Native UI Actions
+
+Native UI action commands let typed clients discover host-owned actions for native cards, buttons, toggles, pickers, and command palettes. They are distinct from raw slash command strings: slash commands are presentation aliases, while action ids are the invocation contract.
+
+The current local RPC implementation exposes the v1 protocol shape, sanitized palette descriptors, shared built-in actions, review cards, Fast mode, and prompt-like invocation for extension commands, prompt templates, and skills. Iroh remote transports allow discovery plus `invoke_ui_action` for the currently advertised remote-safe built-in, review, Fast mode, projected extension command, prompt template, and skill actions. Local-only built-ins and unreviewed action ids remain blocked remotely.
+
+Native clients should treat this as an optional capability:
+
+1. Call `get_ui_capabilities`.
+2. If `ui_actions.v1` is present, call `get_ui_actions` and render descriptors that the client supports.
+3. If `ui_action_invocation.v1` is present, invoke by descriptor `id` with `invoke_ui_action`.
+4. Keep raw `prompt` slash-text submission as compatibility for clients or hosts that do not expose native actions.
+
+`scope` defaults to `"all"`. In v1, `scope: "primary"` returns built-in cards and toggles such as Review and Fast mode. `scope: "palette"` returns descriptors with `presentation.kind: "palette"`, including searchable built-ins, extension commands, prompt templates, and skills. `scope: "all"` lets a client build both surfaces from one response.
+
+#### get_ui_capabilities
+
+Get supported native UI action protocol features.
+
+```json
+{"type": "get_ui_capabilities"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "get_ui_capabilities",
+  "success": true,
+  "data": {
+    "protocolVersion": 1,
+    "features": ["ui_actions.v1", "ui_action_invocation.v1", "ui_action_completions.v1"],
+    "maxActions": 200,
+    "maxDescriptorBytes": 65536
+  }
+}
+```
+
+`ui_actions.v1` means the host understands `get_ui_actions` descriptors. `ui_action_invocation.v1` means the host accepts `invoke_ui_action` for currently advertised actions. `ui_action_completions.v1` means the host accepts `get_ui_action_completions` for descriptor arguments that advertise a `completion` source. Clients must only rely on features present in this list.
+
+#### get_ui_actions
+
+Get native UI action descriptors. `scope` is optional, defaults to `"all"`, and may be `"primary"`, `"palette"`, or `"all"`.
+
+```json
+{"type": "get_ui_actions", "scope": "palette"}
+```
+
+Example response:
+```json
+{
+  "type": "response",
+  "command": "get_ui_actions",
+  "success": true,
+  "data": {
+    "actions": [
+      {
+        "schemaVersion": 1,
+        "id": "extension.command.ec_a1b2c3d4e5f6_1",
+        "label": "session-name",
+        "description": "Set or clear session name",
+        "source": "extension",
+        "sourceScope": "project",
+        "sourceOrigin": "top-level",
+        "sourceLabel": "Project",
+        "category": "extension",
+        "presentation": {"kind": "palette", "group": "Extensions"},
+        "args": [{"name": "arguments", "label": "Arguments", "type": "string", "required": false}],
+        "enabled": true,
+        "disabledReason": null,
+        "destructive": false,
+        "requiresConfirmation": false,
+        "streamingBehavior": "immediate",
+        "remoteSafe": true,
+        "slash": {"name": "session-name", "example": "/session-name"}
+      }
+    ]
+  }
+}
+```
+
+Each descriptor uses this v1 shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "review.uncommitted",
+  "label": "Review changes",
+  "description": "Review uncommitted workspace changes for bugs and regressions.",
+  "source": "builtin",
+  "category": "review",
+  "presentation": {
+    "kind": "card",
+    "group": "Review",
+    "priority": 100,
+    "icon": "magnifyingglass"
+  },
+  "args": [],
+  "enabled": true,
+  "disabledReason": null,
+  "destructive": false,
+  "requiresConfirmation": true,
+  "streamingBehavior": "disabled",
+  "remoteSafe": true,
+  "slash": {
+    "name": "review",
+    "example": "/review uncommitted"
+  }
+}
+```
+
+Required fields are `schemaVersion`, `id`, `label`, `source`, `category`, `enabled`, and `remoteSafe`. Clients should ignore unknown fields, skip invalid descriptors, render unknown categories as advanced or other actions, and treat unknown presentation kinds as palette rows.
+
+Descriptor fields are advisory snapshots. The host remains authoritative and may omit actions that are unavailable, unsafe, too large, or unsupported by the client. Dynamic action ids are session-local unless a future descriptor explicitly documents stronger stability.
+
+Projected extension command, prompt template, and skill actions use session-local opaque ids. Descriptors include bounded display strings, source kind, source scope/origin, and a safe source label such as `"Project"`, `"User"`, `"Temporary"`, or `"Package"`. They do not include extension source paths, prompt file paths or bodies, skill file paths, skill base directories, or raw `sourceInfo`.
+
+Built-in v1 actions currently include:
+
+| Action id | Slash alias | Remote over Iroh | Notes |
+| --- | --- | --- | --- |
+| `session.new` | `/clear` | yes | Starts a fresh session through the same host path as `new_session`. |
+| `run.cancel` | none | yes | Aborts the current agent operation through the same host path as `abort`; descriptors may be disabled when no run is active. |
+| `context.compact` | `/compact` | no | Runs host compaction through the same handler as the local `compact` RPC command. |
+| `session.rename` | `/name <name>` | no | Sets the current session display name through the same handler as `set_session_name`. |
+| `thinking.fast_mode` | none | yes | Session-local, non-persistent toggle that lowers current thinking to the fastest supported host-owned level and restores the captured level when disabled. |
+| `review.uncommitted` | `/review uncommitted` | yes | Reviews uncommitted changes against `HEAD`, requires confirmation remotely, uses host-owned git/model/session policy, and returns only bounded workflow status. |
+| `review.branch` | `/review branch [base]` | yes | Reviews `HEAD` against a base branch; optional `base` is validated by the host and omitted values use host auto-detection. |
+
+Slash aliases are display and compatibility metadata. Clients may show them in palettes or advanced detail views, but should not synthesize slash strings when an action id is available. The host may change slash syntax without changing a stable built-in action id.
+
+Unsupported or deferred native surfaces in v1:
+
+- Extension commands project as palette actions only. First-class extension cards/toggles are deferred until a future `volt.registerAction()` policy defines stable extension-owned ids, trust, descriptor validation, and remote safety.
+- Prompt templates and skills project as palette actions; descriptors omit prompt bodies, skill bodies, file paths, and base directories.
+- Model selection is not a native action; remote clients use the direct `get_available_models`/`set_model`/`set_thinking_level` RPC commands, which are forwarded over Iroh conversation streams. Profile switching, scoped-model editing, login/logout, package management, and local settings screens remain unexposed over Iroh.
+- Local-only built-ins such as `context.compact` and `session.rename` may appear in local RPC descriptors but are blocked over Iroh until separate remote policy exists.
+
+#### get_ui_action_completions
+
+Get completion options for one action argument. Clients should only call this when the descriptor argument includes a supported `completion` value. V1 currently supports extension command argument completions via `"completion": "commandArguments"`.
+
+```json
+{"type": "get_ui_action_completions", "action": "extension.command.ec_a1b2c3d4e5f6_1", "argument": "arguments", "prefix": "pr"}
+```
+
+Response:
+
+```json
+{
+  "type": "response",
+  "command": "get_ui_action_completions",
+  "success": true,
+  "data": {
+    "completions": [
+      {"value": "prod", "label": "Production", "description": "Production target"}
+    ]
+  }
+}
+```
+
+Unknown or stale action ids fail with the normal RPC error shape. Unsupported arguments or completion kinds return an empty completion list unless the argument name itself is not present in the descriptor.
+
+#### invoke_ui_action
+
+Invoke a native UI action by descriptor id.
+
+```json
+{"type": "invoke_ui_action", "action": "review.uncommitted", "args": {}, "streamingBehavior": "followUp"}
+```
+
+`args` is an optional object matching the descriptor's argument metadata. V1 hosts validate the supported descriptor subset: `string` and multiline `string` values are JSON strings, `boolean` values are JSON booleans, `enum` values are strings present in `options`, and `integer` values are JSON numbers with integer values. Unknown argument names, unknown argument types, missing required values, and mismatched value types fail before invocation. `streamingBehavior` is optional and may be `"steer"` or `"followUp"` when the descriptor allows queued invocation while the agent is streaming.
+
+Unknown, stale, disabled, unauthorized, or unavailable action ids fail with the normal RPC error shape:
+```json
+{
+  "type": "response",
+  "command": "invoke_ui_action",
+  "success": false,
+  "error": "UI action not available: prompt.template.pt_a1b2c3d4e5f6_1"
+}
+```
+
+Successful response data reports the command disposition:
+
+```json
+{
+  "type": "response",
+  "command": "invoke_ui_action",
+  "success": true,
+  "data": {
+    "action": "review.uncommitted",
+    "status": "completed",
+    "actionsChanged": true,
+    "stateChanged": true,
+    "message": "Review complete: no issues found; fresh session created with findings"
+  }
+}
+```
+
+Possible statuses:
+- `"accepted"`: a prompt-like action was accepted while idle. Normal agent events report completion; wait for `agent_settled` for final settlement.
+- `"queued"`: a prompt-like action was queued while another turn is streaming. `queuedAs` is `"steer"` or `"followUp"`.
+- `"completed"`: the action finished synchronously. No `agent_end` is expected for this invocation.
+- `"handled"`: the host, extension command, or input hook handled the action without starting an agent turn.
+- `"cancelled"`: the action was cancelled before execution.
+
+Only `accepted` and `queued` may require waiting for later agent events. Clients must clear pending UI immediately for `completed`, `handled`, `cancelled`, and RPC errors.
+
+For projected dynamic actions, invocation uses the host's existing prompt semantics:
+
+- Extension command actions invoke their registered slash command and return `handled` when the command handler completes. They do not require an `agent_end` event.
+- Prompt template and skill actions send their slash alias through host prompt expansion. While idle they return `accepted`; while the agent is streaming they require `streamingBehavior: "steer"` or `"followUp"` and return `queued`.
+- Dynamic action ids are opaque and tied to the current action catalog. After a reload, session replacement, or catalog change, clients must refresh descriptors; stale ids are rejected instead of being remapped to another action.
+- `thinking.fast_mode` uses a required boolean `enabled` argument. Enabling captures the current thinking level, applies the fastest supported lower thinking level among `off`, `minimal`, and `low`, and returns updated boolean state. Disabling restores the captured thinking level after host clamping. It never switches models, exposes model catalogs, changes scoped-model/profile settings, or persists model/thinking defaults. Manual thinking/model/profile/scoped-model changes clear the session-local restore marker.
+- Review actions run a host workflow: the host resolves git targets, applies review-model settings, runs an isolated review session with the approved tool policy, and creates a fresh session seeded with findings. Responses do not include raw diffs, review prompts, configured model names, auth state, or raw tool output. While the workflow runs, hosts may emit sanitized `workflow_*` and `tool_execution_*` activity events so clients can show progress. Remote review actions require confirmation and use the host-owned read-only tool set (`read`, `grep`, `find`, `ls`).
+- Over Iroh, v1 invocation is allowlist-based and forwards only exact reviewed built-in ids (`session.new`, `run.cancel`, `thinking.fast_mode`, `review.uncommitted`, `review.branch`) plus projected dynamic ids under `extension.command.*`, `prompt.template.*`, and `skill.*`. Local-only built-ins such as `context.compact`, `session.rename`, deferred review actions, and unreviewed prefixes are rejected with a normal RPC error. Model and thinking changes use the direct `set_model`/`set_thinking_level` RPC commands, which are forwarded over Iroh conversation streams.
+
+#### Native UI Action Security
+
+Descriptors must not expose host-local paths, extension source paths, prompt template bodies, skill content, provider secrets, environment values, auth internals, raw model/provider metadata, raw transcript payloads, or host session file paths. Iroh remote discovery responses pass through the remote outbound redaction layer in addition to descriptor-level sanitization. Remote invocation is allowlist-based and re-checks action availability, remote safety, authorization, streaming policy, and argument validity at invocation time.
+
+`get_commands` remains the legacy local command-discovery surface for raw slash invocation and may include source metadata useful to local clients. Remote clients and native mobile clients should use sanitized `get_ui_actions`; raw `get_commands` remains blocked over Iroh.
+
+### Host-Initiated Action Requests
+
+Host-initiated action requests let Volt pause a running workflow and ask an RPC client to approve a host-owned action. This is separate from native UI actions: native UI actions are client-initiated, while host action requests are emitted by Volt when it needs user/app approval to continue.
+
+Clients must opt in before Volt will block on host action requests:
+
+```json
+{"type": "set_client_capabilities", "features": ["host_action_requests.v1"]}
+```
+
+Response:
+
+```json
+{"type": "response", "command": "set_client_capabilities", "success": true}
+```
+
+When a host action is needed, Volt emits:
+
+```json
+{
+  "type": "host_action_request",
+  "id": "ha_123",
+  "action": "lsp.install_server",
+  "title": "Install typescript language server?",
+  "message": "Volt tried to use LSP for typescript, but typescript-language-server is not installed. Install it now and retry diagnostics?",
+  "confirmLabel": "Install",
+  "cancelLabel": "Skip",
+  "commandPreview": "npm install -g typescript-language-server typescript",
+  "blocking": true,
+  "destructive": false,
+  "metadata": {"server": "typescript", "binary": "typescript-language-server"}
+}
+```
+
+The client responds with one of `"approved"`, `"denied"`, or `"dismissed"`:
+
+```json
+{"type": "host_action_response", "id": "ha_123", "decision": "approved"}
+```
+
+Volt may emit progress updates for approved actions:
+
+```json
+{"type": "host_action_update", "id": "ha_123", "action": "lsp.install_server", "status": "running", "message": "Running npm install -g typescript-language-server typescript"}
+{"type": "host_action_update", "id": "ha_123", "action": "lsp.install_server", "status": "completed", "message": "typescript language server installed. Retrying diagnostics.", "exitCode": 0}
+```
+
+Use `get_pending_host_actions` to recover currently pending requests after reconnect:
+
+```json
+{"type": "get_pending_host_actions"}
+```
+
+Clients approve only the advertised host-owned action; they cannot alter the command. If the client does not advertise `host_action_requests.v1`, Volt falls back without blocking (for example, an LSP missing-server message with install instructions). Current LSP install requests are limited to trusted built-in install recipes; custom LSP commands and manual-install-only servers still produce instructions only.
+
+### Model
+
+#### set_model
+
+Switch to a specific model. Matches CLI `/model` behavior: the change is recorded in the session and persisted as the default model and provider for future sessions. Pass `"persistDefault": false` to change the current session's model without rewriting the host default (used e.g. for per-agent model overrides). Switching models re-clamps the thinking level to the new model's capabilities (emitting `thinking_level_changed` when it changes) and clears any active Fast mode overlay. Unknown provider/model pairs fail with `Model not found: <provider>/<modelId>`.
+
+```json
+{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}
+```
+
+Response contains the full [Model](#model) object plus `availableThinkingLevels`, the thinking levels the model supports:
+```json
+{
+  "type": "response",
+  "command": "set_model",
+  "success": true,
+  "data": {..., "availableThinkingLevels": ["off", "minimal", "low", "medium", "high"]}
+}
+```
+
+#### cycle_model
+
+Cycle to the next available model. Returns `null` data if only one model available.
+
+```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.
+
+#### get_available_models
+
+List all configured models. The host reloads `auth.json` and `models.json` from disk before answering, so logins, logouts, and API keys saved by other volt processes become selectable without restarting the host.
+
+```json
+{"type": "get_available_models"}
+```
+
+Response contains an array of full [Model](#model) objects, each enriched with `availableThinkingLevels` (the thinking levels that model supports, `["off"]` for non-reasoning models) so clients can present valid choices without provider capability matrices:
+```json
+{
+  "type": "response",
+  "command": "get_available_models",
+  "success": true,
+  "data": {
+    "models": [...]
+  }
+}
+```
+
+### Thinking
+
+#### set_thinking_level
+
+Set the reasoning/thinking level for models that support it. Pass `"persistDefault": false` to apply the level to the current session without persisting it as the host default.
+
+```json
+{"type": "set_thinking_level", "level": "high"}
+```
+
+Levels: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`
+
+`"xhigh"` and `"max"` are advertised only for models whose metadata explicitly supports them. GPT-5.6 Sol, Terra, and Luna expose both as distinct efforts.
+
+Levels the current model does not support are silently clamped to the nearest supported level, not rejected. The response reports the effective post-clamp level, and a `thinking_level_changed` event fires only when the effective level actually changes. Use `get_state`'s `availableThinkingLevels` to present valid choices.
+
+Response:
+```json
+{"type": "response", "command": "set_thinking_level", "success": true, "data": {"level": "high"}}
+```
+
+#### 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"}
+}
+```
+
+### Queue Modes
+
+#### set_steering_mode
+
+Control how steering messages (from `steer`) are delivered.
+
+```json
+{"type": "set_steering_mode", "mode": "one-at-a-time"}
+```
+
+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)
+
+Response:
+```json
+{"type": "response", "command": "set_steering_mode", "success": true}
+```
+
+#### 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}
+```
+
+### Compaction
+
+#### compact
+
+Manually compact conversation context to reduce token usage.
+
+```json
+{"type": "compact"}
+```
+
+With custom instructions:
+```json
+{"type": "compact", "customInstructions": "Focus on code changes"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "compact",
+  "success": true,
+  "data": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
+    "tokensBefore": 150000,
+    "details": {}
+  }
+}
+```
+
+#### 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}
+```
+
+### Retry
+
+#### set_auto_retry
+
+Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).
+
+```json
+{"type": "set_auto_retry", "enabled": true}
+```
+
+Response:
+```json
+{"type": "response", "command": "set_auto_retry", "success": true}
+```
+
+#### 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}
+```
+
+### Bash
+
+#### bash
+
+Execute a shell command and add output to conversation context.
+
+```json
+{"type": "bash", "command": "ls -la"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "bash",
+  "success": true,
+  "data": {
+    "output": "total 48\ndrwxr-xr-x ...",
+    "exitCode": 0,
+    "cancelled": false,
+    "truncated": false
+  }
+}
+```
+
+If output was truncated, includes `fullOutputPath`:
+```json
+{
+  "type": "response",
+  "command": "bash",
+  "success": true,
+  "data": {
+    "output": "truncated output...",
+    "exitCode": 0,
+    "cancelled": false,
+    "truncated": true,
+    "fullOutputPath": "/tmp/volt-bash-abc123.log"
+  }
+}
+```
+
+**How bash results reach the LLM:**
+
+The `bash` command executes immediately and returns a `BashResult`. Internally, a `BashExecutionMessage` is created and stored in the agent's message state. This 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 ...
+```
+````
+
+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
+
+#### abort_bash
+
+Abort a running bash command.
+
+```json
+{"type": "abort_bash"}
+```
+
+Response:
+```json
+{"type": "response", "command": "abort_bash", "success": true}
+```
+
+### Session
+
+#### get_session_stats
+
+Get token usage, cost statistics, and current context window usage.
+
+```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.
+
+`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.
+
+#### list_sessions
+
+List sessions for the current workspace. The response omits host file paths so remote clients can present workspace-scoped session choices safely.
+
+```json
+{"type": "list_sessions"}
+```
+
+Response:
+```json
+{
+  "type": "response",
+  "command": "list_sessions",
+  "success": true,
+  "data": {
+    "sessions": [
+      {
+        "sessionId": "abc123",
+        "sessionName": "my-feature-work",
+        "createdAt": "2026-06-22T15:00:00.000Z",
+        "modifiedAt": "2026-06-22T15:10:00.000Z",
+        "messageCount": 12,
+        "firstMessage": "Implement the feature",
+        "current": true
+      }
+    ]
+  }
+}
+```
+
+#### 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"}
+}
+```
+
+#### 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}}
+```
+
+#### switch_session_by_id
+
+Load another session from the current workspace by session ID. This is the remote-safe form of session switching; clients do not need to know host session file paths.
+
+```json
+{"type": "switch_session_by_id", "sessionId": "abc123"}
+```
+
+Response:
+```json
+{"type": "response", "command": "switch_session_by_id", "success": true, "data": {"cancelled": false}}
+```
+
+If an extension cancelled the switch:
+```json
+{"type": "response", "command": "switch_session_by_id", "success": true, "data": {"cancelled": true}}
+```
+
+#### 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}
+}
+```
+
+#### 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}
+}
+```
+
+#### 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..."}
+    ]
+  }
+}
+```
+
+#### 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.
+
+#### 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 `volt --mode rpc` process.
+
+### 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"}
+```
+
+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/.volt/agent/extensions/session.ts"},
+      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.volt/agent/prompts/fix-tests.md"},
+      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.volt/agent/skills/brave-search/SKILL.md"}
+    ]
+  }
+}
+```
+
+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 `volt.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 (`~/.volt/agent/`)
+  - `"project"`: Project-level (`./.volt/agent/`)
+  - `"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`.
+
+## Events
+
+Events are streamed to stdout as JSON lines during agent operation. Events do NOT include an `id` field (only responses do).
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `agent_start` | Agent begins processing |
+| `agent_end` | Agent run completes (includes all generated messages); a retry or continuation may still follow |
+| `agent_settled` | Prompt fully settles: no further automatic retries, compaction continuations, or queued continuations |
+| `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 |
+| `tool_execution_update` | Tool execution progress (streaming output) |
+| `tool_execution_end` | Tool completes |
+| `workflow_start` | Host-owned workflow begins (for example, review) |
+| `workflow_update` | Host-owned workflow progress update |
+| `workflow_end` | Host-owned workflow completes, fails, or is cancelled |
+| `queue_update` | Pending steering/follow-up queue changed |
+| `compaction_start` | Compaction begins |
+| `compaction_end` | Compaction completes |
+| `auto_retry_start` | Auto-retry begins (after transient error) |
+| `auto_retry_end` | Auto-retry completes (success or final failure) |
+| `subagent_event` | Wrapped child event from a local RPC-managed subagent |
+| `subagent_end` | Terminal completion result for a local RPC-managed subagent |
+| `extension_error` | Extension threw an error |
+| `models_changed` | Available model catalog changed on disk (login, logout, or API key save) |
+| `mcp_servers_changed` | MCP server list or enablement changed (`servers`: full summary list) |
+| `mcp_server_status_changed` | An MCP server's status or auth state changed (`server`: full summary) |
+| `mcp_auth_request` | An MCP OAuth flow needs user action (`serverId`, `auth`: flow, URL/device-code details) |
+| `mcp_auth_update` | An MCP OAuth flow progressed (`serverId`, `status`, `authState`, optional `server` summary) |
+| `mcp_call_start` | MCP gateway tool call began (`call`: id, server, tool, risk) |
+| `mcp_call_update` | MCP tool call progress notification (`call`, `progress`) |
+| `mcp_call_end` | MCP tool call completed, failed, or was cancelled (`call`, optional `cacheId`) |
+
+### agent_start
+
+Emitted when the agent begins processing a prompt.
+
+```json
+{"type": "agent_start"}
+```
+
+### agent_end
+
+Emitted when an agent run completes. Contains all messages generated during this run.
+
+```json
+{
+  "type": "agent_end",
+  "messages": [...]
+}
+```
+
+A single prompt can produce multiple `agent_end` events: automatic retries, overflow/threshold compaction, and queued follow-up messages each continue the run after a raw `agent_end`. Wait for `agent_settled` to know the prompt is finished.
+
+### agent_settled
+
+Emitted when all tracked prompt work reaches a global idle boundary, after any final `agent_end`, automatic retries, compaction continuations, and queued-message continuations have finished. Overlapping prompt transactions share one boundary, and handled or rejected preflight can settle without an `agent_end`; this event does not carry a prompt correlation id. Client helpers such as `waitForIdle`, `collectEvents`, and `promptAndWait` terminate on this event.
+
+```json
+{"type": "agent_settled"}
+```
+
+### 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": [...]
+}
+```
+
+### 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": {...}}
+```
+
+### message_update (Streaming)
+
+Emitted during streaming of assistant messages. Contains both the partial message and a streaming delta event.
+
+```json
+{
+  "type": "message_update",
+  "message": {...},
+  "assistantMessageEvent": {
+    "type": "text_delta",
+    "contentIndex": 0,
+    "delta": "Hello ",
+    "partial": {...}
+  }
+}
+```
+
+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","message":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0,"partial":{...}}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello","partial":{...}}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world","partial":{...}}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world","partial":{...}}}
+```
+
+### 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.
+
+Host-owned workflows can also emit sanitized tool lifecycle events with workflow metadata. For example, review actions emit tool names and bounded arguments, but omit raw file contents and raw tool output:
+
+```json
+{"type":"tool_execution_start","workflowId":"review:abc","workflowKind":"review","workflowAction":"review.uncommitted","toolCallId":"review:abc:call_1","toolName":"read","args":{"path":"src/file.ts"}}
+{"type":"tool_execution_end","workflowId":"review:abc","workflowKind":"review","workflowAction":"review.uncommitted","toolCallId":"review:abc:call_1","toolName":"read","isError":false}
+```
+
+### workflow_start / workflow_update / workflow_end
+
+Emitted for host-owned workflows that are not ordinary assistant chat turns, such as a review action. Clients can render these as a temporary live timeline until the action response and any resulting session refresh arrive.
+
+```json
+{"type":"workflow_start","workflowId":"review:abc","kind":"review","action":"review.uncommitted","title":"Review","message":"Reviewing uncommitted changes.","status":"running"}
+{"type":"workflow_update","workflowId":"review:abc","kind":"review","action":"review.uncommitted","title":"Review","message":"Finalizing findings.","status":"finalizing"}
+{"type":"workflow_end","workflowId":"review:abc","kind":"review","action":"review.uncommitted","title":"Review","message":"Review complete: 2 findings. Opening review session.","status":"completed"}
+```
+
+`status` is advisory. Known review statuses are `running`, `finalizing`, `completed`, `cancelled`, and `failed`. Unknown workflow kinds, statuses, and extra fields should be ignored or rendered generically.
+
+### 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"]
+}
+```
+
+### compaction_start / compaction_end
+
+Emitted when compaction runs, whether manual or automatic.
+
+```json
+{"type": "compaction_start", "reason": "threshold"}
+```
+
+The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
+
+```json
+{
+  "type": "compaction_end",
+  "reason": "threshold",
+  "result": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
+    "tokensBefore": 150000,
+    "details": {}
+  },
+  "aborted": false,
+  "willRetry": false
+}
+```
+
+If `reason` was `"overflow"` and compaction succeeds, `willRetry` is `true` and the agent will automatically retry the prompt.
+
+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.
+
+### 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"
+}
+```
+
+### extension_error
+
+Emitted when an extension throws an error.
+
+```json
+{
+  "type": "extension_error",
+  "extensionPath": "/path/to/extension.ts",
+  "event": "tool_call",
+  "error": "Error message..."
+}
+```
+
+### models_changed
+
+Emitted when the host detects that the available model catalog changed on disk — for example after `/login`, `/logout`, or an API key save in another volt process rewrote `auth.json` or `models.json`. The event carries no payload; clients should re-request `get_available_models` to fetch the updated catalog. Rewrites that do not change the available catalog (such as OAuth token refreshes) do not emit this event.
+
+```json
+{"type": "models_changed"}
+```
+
+## 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()`, `setToolsExpanded()` are no-ops
+- `getEditorText()` returns `""`
+- `getToolsExpanded()` returns `false`
+- `pasteToEditor()` delegates to `setEditorText()` (no paste/collapse handling)
+
+The theme facade is fully functional in RPC mode: `getAllThemes()` returns the real theme list (builtin plus extension-registered), `getTheme()` resolves by name, and `setTheme()` applies the theme to the process and persists the choice. Under the background daemon, a successful `setTheme()` also broadcasts a `theme_snapshot` to connected desktop TUIs, which apply it unless the user explicitly picked a theme in that TUI session.
+
+For conversations owned by a desktop TUI and served to phones over the daemon's byte relay, `extension_ui_request` frames are suppressed on the relayed stream: dialogs are answered on the desktop where the extension's UI actually lives, and phones receive none of them.
+
+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.
+
+### Extension UI Requests (stdout)
+
+All requests have `type: "extension_ui_request"`, a unique `id`, and a `method` field.
+
+#### 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`.
+
+#### 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`.
+
+#### 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`.
+
+#### 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`.
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### setTitle
+
+Set the terminal window/tab title. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-8",
+  "method": "setTitle",
+  "title": "volt - my project"
+}
+```
+
+#### 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"
+}
+```
+
+### Extension UI Responses (stdin)
+
+Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+
+#### Value response (select, input, editor)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}
+```
+
+#### Confirmation response (confirm)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}
+```
+
+#### 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}
+```
+
+## 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..."
+}
+```
+
+## Types
+
+Source files:
+- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
+- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `AgentEvent`
+- [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
+- [`src/core/rpc/types.ts`](../src/core/rpc/types.ts) - RPC command/response types, extension UI request/response types
+- [`src/core/rpc/transport.ts`](../src/core/rpc/transport.ts) - RPC transport abstraction and JSONL stream adapters
+- [`src/core/rpc/loopback-transport.ts`](../src/core/rpc/loopback-transport.ts) - in-memory transport pair for in-process clients
+- [`src/modes/rpc/rpc-transport-client.ts`](../src/modes/rpc/rpc-transport-client.ts) - typed RPC client for caller-provided transports
+
+### 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
+  }
+}
+```
+
+### UserMessage
+
+```json
+{
+  "role": "user",
+  "content": "Hello!",
+  "timestamp": 1733234567890,
+  "attachments": []
+}
+```
+
+The `content` field can be a string or an array of `TextContent`/`ImageContent` blocks.
+
+### 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"`
+
+### ToolResultMessage
+
+```json
+{
+  "role": "toolResult",
+  "toolCallId": "call_123",
+  "toolName": "bash",
+  "content": [{"type": "text", "text": "total 48\ndrwxr-xr-x ..."}],
+  "isError": false,
+  "timestamp": 1733234567890
+}
+```
+
+### 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
+}
+```
+
+### Attachment
+
+```json
+{
+  "id": "img1",
+  "type": "image",
+  "fileName": "photo.jpg",
+  "mimeType": "image/jpeg",
+  "size": 102400,
+  "content": "base64-encoded-data...",
+  "extractedText": null,
+  "preview": null
+}
+```
+
+## Example: Basic Client (Python)
+
+```python
+import subprocess
+import json
+
+proc = subprocess.Popen(
+    ["volt", "--mode", "rpc", "--no-session"],
+    stdin=subprocess.PIPE,
+    stdout=subprocess.PIPE,
+    text=True
+)
+
+def send(cmd):
+    proc.stdin.write(json.dumps(cmd) + "\n")
+    proc.stdin.flush()
+
+def read_events():
+    for line in proc.stdout:
+        yield json.loads(line)
+
+# Send prompt
+send({"type": "prompt", "message": "Hello!"})
+
+# Process events
+for event in read_events():
+    if event.get("type") == "message_update":
+        delta = event.get("assistantMessageEvent", {})
+        if delta.get("type") == "text_delta":
+            print(delta["delta"], end="", flush=True)
+    
+    if event.get("type") == "agent_settled":
+        print()
+        break
+```
+
+## Example: Interactive Client (Node.js)
+
+See [`test/rpc-example.ts`](../test/rpc-example.ts) for a complete interactive example, [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts) for the subprocess typed client, or [`src/modes/rpc/rpc-transport-client.ts`](../src/modes/rpc/rpc-transport-client.ts) for the transport-backed typed client.
+
+For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](../examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](../examples/extensions/rpc-demo.ts) extension.
+
+```javascript
+const { spawn } = require("child_process");
+const { StringDecoder } = require("string_decoder");
+
+const agent = spawn("volt", ["--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");
+});
+```