better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/rpc.md

@@ -1,523 +0,0 @@
-<!--
-source: https://omp.sh/docs/rpc
-fetched: 2026-09-06
--->
-
-# RPC mode
-
-> Run omp as a long-lived subprocess and control it with newline-delimited JSON over stdin and stdout.
-
-## Choose RPC when you own the host process
-
-RPC mode is the lowest-common-denominator way to embed omp. Your program starts `omp`, sends one JSON object per line on stdin, and receives responses and streaming events as JSON lines on stdout. It works from any language with subprocess and JSON support.
-
-| Surface | Choose it when… |
-| --- | --- |
-| Interactive omp | A person is working in the terminal and wants omp's editor, dialogs, and tool views. |
-| One-shot `text` or `json` mode | A shell or CI job needs one prompt and then exits. `json` is an event stream, but it does not accept RPC commands. |
-| [SDK](/docs/sdk) | Your TypeScript application can run omp in-process and wants typed, direct APIs instead of a process boundary. |
-| [ACP](/docs/acp) | You are building an editor or client that already speaks the standardized Agent Client Protocol. |
-| **RPC** | You need a long-lived omp session, streaming output, cancellation, state controls, or host callbacks from any language. |
-
-Start with headless RPC and an ephemeral session:
-
-```sh
-omp --mode rpc --no-session
-```
-
-Omit `--no-session` to save the conversation under omp's normal session store. Normal model, provider, working-directory, and configuration options still apply; see the [CLI reference](/docs/cli). RPC rejects `@file` command-line arguments—send file references in the prompt instead.
-
-`--mode rpc-ui` uses the same wire protocol but marks the embedded session as UI-capable and connects UI-dependent tool and extension surfaces to the RPC UI bridge. It does **not** launch a TUI or add a separate “tool card” frame type. Use it only when your host implements those UI behaviors. Either mode can emit `extension_ui_request` frames for features such as extension dialogs or login, so a complete host should understand that sub-protocol.
-
-## Complete one prompt
-
-Keep stdin open until the turn finishes. Read stdout continuously, keep stderr separate, and flush every command after its trailing newline.
-
-This is a minimal valid exchange. Every displayed line is one complete JSON object; other events such as `available_commands_update` may be interleaved after `ready`.
-
-```json
-{"type":"ready","protocolVersion":1,"supportedProtocolVersions":[1,2],"maxFrameBytes":1048576,"maxReassembledFrameBytes":67108864}
-{"id":"p1","type":"prompt","message":"Reply with only the word ok"}
-{"id":"p1","type":"response","command":"prompt","success":true}
-```
-
-The first line is stdout from omp, the second is stdin from your host, and the third is a possible acknowledgment on stdout. The acknowledgment means “accepted,” not “finished.” The turn then streams events and finishes at an `agent_end` whose `isTerminal` is not `false`.
-
-Here is a complete client using only the Python standard library. It deliberately remains on protocol v1 because its prompt produces a small response; production clients should negotiate v2 as described below.
-
-```python
-import json
-import subprocess
-
-proc = subprocess.Popen(
-    ["omp", "--mode", "rpc", "--no-session"],
-    stdin=subprocess.PIPE,
-    stdout=subprocess.PIPE,
-    text=True,
-    bufsize=1,
-)
-
-assert proc.stdin is not None
-assert proc.stdout is not None
-
-ready = json.loads(proc.stdout.readline())
-if ready.get("type") != "ready":
-    raise RuntimeError(f"expected ready, got {ready!r}")
-
-request_id = "p1"
-proc.stdin.write(json.dumps({
-    "id": request_id,
-    "type": "prompt",
-    "message": "Reply with only the word ok",
-}) + "\n")
-proc.stdin.flush()
-
-accepted = False
-finished = False
-text_parts = []
-
-for line in proc.stdout:
-    frame = json.loads(line)
-
-    if frame.get("type") == "response" and frame.get("id") == request_id:
-        if not frame.get("success"):
-            raise RuntimeError(frame.get("error", "RPC command failed"))
-        if frame.get("command") == "prompt":
-            accepted = True
-            if frame.get("data", {}).get("agentInvoked") is False:
-                finished = True
-
-    if frame.get("type") == "message_update":
-        event = frame.get("assistantMessageEvent", {})
-        if event.get("type") == "text_delta":
-            text_parts.append(event["delta"])
-
-    if (frame.get("type") == "prompt_result"
-            and frame.get("id") == request_id
-            and frame.get("agentInvoked") is False):
-        finished = True
-
-    if (frame.get("type") == "agent_end"
-            and frame.get("isTerminal") is not False):
-        finished = True
-
-    if accepted and finished:
-        break
-
-proc.stdin.close()
-if proc.wait() != 0:
-    raise RuntimeError(f"omp exited with {proc.returncode}")
-
-print("".join(text_parts))
-```
-
-Do not assume the response arrives before the events: some prompt paths can begin emitting events first. Match command responses by `id`, and independently track prompt completion.
-
-## Lifecycle, queues, and cancellation
-
-### Process lifecycle
-
-1. Spawn `omp --mode rpc` with separate stdin, stdout, and stderr streams.
-2. Wait for `ready` before sending commands.
-3. Read stdout continuously. A host callback or UI request can arrive while a command is outstanding.
-4. Send commands as compact, unchunked JSON objects followed by `\n`.
-5. Close stdin to disconnect. omp rejects pending UI/tool/URI callbacks, drains accepted commands, disposes the session, and exits with code `0`.
-
-Stdout is exclusively the JSON protocol channel. Logs and diagnostics belong on stderr; never merge stderr into the JSON parser.
-
-### Prompt completion
-
-`prompt` and `abort_and_prompt` acknowledge scheduling immediately. A normal agent run is complete only when:
-
-```text
-frame.type == "agent_end" and frame.isTerminal != false
-```
-
-`isTerminal: false` means asynchronous delivery or maintenance will resume the session. An absent field is terminal-compatible.
-
-A prompt may instead be handled locally—for example, by a slash command—and emit no `agent_end`. Detect that with either:
-
-- `response.data.agentInvoked === false`, or
-- a later `{ "type": "prompt_result", "id": …, "agentInvoked": false }`.
-
-Local commands can also emit `command_output`. `agentInvoked: true` means agent lifecycle events will identify completion. If the field is absent, continue watching events and `prompt_result`.
-
-### Sending work while a turn is active
-
-- `steer` inserts a user message into the active run.
-- `follow_up` queues a message for after the active run.
-- A second `prompt` while streaming must include `streamingBehavior: "steer"` or `"followUp"` (camel-case `followUp`).
-- Steering and follow-up queues default to `"one-at-a-time"`; their `set_*_mode` commands can switch to `"all"`.
-- Interrupt mode defaults to `"immediate"`. `"wait"` defers steering until the turn finishes.
-
-`bash` is the exception to normal command serialization: it runs concurrently so `abort_bash` can overtake it. Its response arrives when the command finishes, and may be out of order relative to other responses. Correlation by `id` is mandatory.
-
-### Cancel safely
-
-- Send `abort` to stop the active agent run. Wait for both the `abort` response and the terminal `agent_end` for the run.
-- Send `abort_and_prompt` to abort and schedule a replacement prompt. It does not provide `data.agentInvoked` or `prompt_result`; rely on lifecycle events or a same-id scheduling error.
-- Send `abort_retry` to stop an automatic retry delay.
-- Send `abort_bash` to stop the current RPC-started shell command.
-- Treat `host_tool_cancel`, `host_uri_cancel`, and UI `method: "cancel"` as cancellation of the referenced host-side operation.
-
-## Errors and recovery
-
-Command failures are ordinary response frames and usually leave the process usable:
-
-```json
-{"id":"m1","type":"response","command":"set_model","success":false,"error":"Model not found: provider/model"}
-```
-
-All failures have `type: "response"`, `success: false`, a string `command`, and a human-readable `error`. `code` is optional; `get_messages_page` currently uses `session_busy` and `stale_cursor`.
-
-Important edge cases:
-
-- Malformed JSON produces a recoverable failure with `command: "parse"` and no `id`; the next valid line is still processed.
-- An unknown command currently returns no correlation id. Do not send another command until you have validated its `type` locally.
-- A scheduled `prompt` or `abort_and_prompt` can acknowledge success and later emit a failure response with the same id if asynchronous scheduling fails.
-- An extension runtime failure is an `extension_error` event, not a command response.
-- A host that ignores `extension_ui_request`, `host_tool_call`, or `host_uri_request` can deadlock the operation that requested it. Dispatch these frames while other commands are pending.
-- EOF is a deliberate disconnect. Unexpected process exit or broken stdout is a transport failure; any unresolved requests have unknown completion state.
-
-## Transport versions and large frames
-
-Protocol v1 is active at startup. It emits one JSON object per physical line and caps that line, including its newline, at the advertised `maxFrameBytes` (currently 1 MiB). Inbound frames are always single, unchunked JSONL objects and should stay below that limit.
-
-Clients that can reassemble large outputs should negotiate v2 immediately after `ready`:
-
-```json
-{"id":"protocol-1","type":"negotiate_protocol","protocolVersion":2}
-{"id":"protocol-1","type":"response","command":"negotiate_protocol","success":true,"data":{"protocolVersion":2}}
-```
-
-The success response itself is v1. Subsequent oversized logical stdout objects become an uninterrupted sequence of `rpc_chunk` frames:
-
-```json
-{"type":"rpc_chunk","chunkId":"rpc-1","index":0,"count":2,"byteLength":1200000,"data":"BASE64_DATA"}
-```
-
-For each sequence, validate that:
-
-- `chunkId` is unchanged and non-empty;
-- `index` starts at `0` and increments with no gaps;
-- `count`, `byteLength`, and `chunkId` match on every chunk;
-- no ordinary frame interrupts the sequence;
-- decoded bytes do not exceed `maxReassembledFrameBytes` (currently 64 MiB);
-- concatenated bytes equal `byteLength`, decode as strict UTF-8, and parse as one JSON object.
-
-`data` is standard base64. Do not dispatch individual chunks as application events. A logical frame above the v2 ceiling becomes an explicit overflow frame instead.
-
-In v1, oversized responses fail with `RPC response exceeded the transport limit`; other frames may be compacted or replaced by `rpc_frame_error`. An oversized `agent_end` can omit messages already delivered through `message_end` and add `messageCount`. Never use `agent_end.messages` as the only transcript store: collect message events or page history with `get_messages_page`.
-
-## Public protocol reference
-
-A `?` below means optional. All commands accept `id?: string`. If supplied, a normal response echoes it.
-
-### Commands sent to stdin
-
-| Area | `type` and fields | Successful `data` |
-| --- | --- | --- |
-| Protocol | `negotiate_protocol` — `protocolVersion: 2` | `{ protocolVersion: 2 }` |
-| Prompt | `prompt` — `message: string`, `images?: ImageContent[]`, `streamingBehavior?: "steer" \| "followUp"` | optional `{ agentInvoked: boolean }` |
-| Prompt | `steer` — `message`, `images?` | none |
-| Prompt | `follow_up` — `message`, `images?` | none |
-| Prompt | `abort` | none |
-| Prompt | `abort_and_prompt` — `message`, `images?` | none |
-| Session | `new_session` — `parentSession?: string` | `{ cancelled: boolean }` |
-| State | `get_state` | `RpcSessionState` below |
-| State | `set_fast_mode` — `enabled: boolean` | `{ enabled: boolean, active: boolean }` |
-| State | `get_available_commands` | `{ commands: RpcAvailableSlashCommand[] }` |
-| State | `set_todos` — `phases: TodoPhase[]` | `{ todoPhases: TodoPhase[] }` |
-| Host | `set_host_tools` — `tools: RpcHostToolDefinition[]` | `{ toolNames: string[] }` |
-| Host | `set_host_uri_schemes` — `schemes: RpcHostUriSchemeDefinition[]` | `{ schemes: string[] }` |
-| Subagents | `set_subagent_subscription` — `level: "off" \| "progress" \| "events"` | `{ level }` |
-| Subagents | `get_subagents` | `{ subagents: RpcSubagentSnapshot[] }` |
-| Subagents | `get_subagent_messages` — `subagentId?: string`, `sessionFile?: string`, `fromByte?: number` | `RpcSubagentMessagesResult` |
-| Model | `set_model` — `provider: string`, `modelId: string` | selected `Model` |
-| Model | `cycle_model` | `{ model, thinkingLevel, isScoped } \| null` |
-| Model | `get_available_models` | `{ models: Model[] }` |
-| Thinking | `set_thinking_level` — `level: "inherit" \| "off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max"` | none |
-| Thinking | `cycle_thinking_level` | `{ level: "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max" } \| null` |
-| Queue | `set_steering_mode` — `mode: "all" \| "one-at-a-time"` | none |
-| Queue | `set_follow_up_mode` — same values | none |
-| Queue | `set_interrupt_mode` — `mode: "immediate" \| "wait"` | none |
-| Compaction | `compact` — `customInstructions?: string` | `CompactionResult` |
-| Compaction | `set_auto_compaction` — `enabled: boolean` | none |
-| Retry | `set_auto_retry` — `enabled: boolean` | none |
-| Retry | `abort_retry` | none |
-| Shell | `bash` — `command: string` | `BashResult` |
-| Shell | `abort_bash` | none |
-| Session | `get_session_stats` | `SessionStats` |
-| Session | `export_html` — `outputPath?: string` | `{ path: string }` |
-| Session | `switch_session` — `sessionPath: string` | `{ cancelled: boolean }` |
-| Session | `branch` — `entryId: string` | `{ text: string, cancelled: boolean }` |
-| Session | `get_branch_messages` | `{ messages: Array<{ entryId: string, text: string }> }` |
-| Session | `get_last_assistant_text` | `{ text: string \| null }` |
-| Session | `set_session_name` — `name: string` | none |
-| Session | `handoff` — `customInstructions?: string` | `{ savedPath?: string } \| null` |
-| Messages | `get_messages` | `{ messages: AgentMessage[] }` |
-| Messages | `get_messages_page` — `cursor?: string`, `limit?: number` | `{ messages, nextCursor?, totalMessages }` |
-| Login | `get_login_providers` | `{ providers: Array<{ id, name, available, authenticated }> }` |
-| Login | `login` — `providerId: string` | `{ providerId: string }` |
-
-`get_messages_page` defaults to 100 messages and accepts limits from 1 through 256. Follow the opaque `nextCursor` until absent. Paging is snapshot-based: restart from no cursor after `stale_cursor`; wait for streaming/compaction to stop after `session_busy`.
-
-### Shared input objects
-
-`ImageContent`:
-
-| Field | Type |
-| --- | --- |
-| `type` | literal `"image"` |
-| `data` | base64-encoded image bytes |
-| `mimeType` | MIME string such as `image/png` |
-| `detail?` | `"auto" \| "low" \| "high" \| "original"` |
-| `providerFile?` | `{ provider: "openai" \| "anthropic" \| "google", id?: string, uri?: string, expiresAt?: number }` |
-| `url?` | HTTPS mirror of exactly the bytes in `data` |
-
-`TodoPhase` is `{ name: string, tasks: TodoItem[] }`. A `TodoItem` is `{ content: string, status: "pending" | "in_progress" | "completed" | "abandoned" | "blocked", blocker?: string }`.
-
-`RpcHostToolDefinition` is `{ name: string, label?: string, description: string, parameters: JSONSchemaObject, hidden?: boolean, loadMode?: "essential" | "discoverable" }`. Sending `set_host_tools` replaces the previous host-tool set.
-
-`RpcHostUriSchemeDefinition` is `{ scheme: string, description?: string, writable?: boolean, immutable?: boolean }`. Supply a scheme without `://`. Names are normalized to lowercase; `security` is reserved. Sending the command replaces the previous set.
-
-### Response envelope
-
-Every command produces one of:
-
-```text
-Success: { id?, type: "response", command: string, success: true, data?: any }
-Failure: { id?, type: "response", command: string, success: false, error: string, code?: string }
-```
-
-Useful result objects have these exact fields:
-
-- `CompactionResult`: `{ summary, shortSummary?, firstKeptEntryId, tokensBefore, details?, preserveData? }`.
-- `BashResult`: `{ output, exitCode: number | undefined, cancelled, timedOut?, truncated, totalLines, totalBytes, outputLines, outputBytes, artifactId?, workingDir? }`. JSON serialization omits fields whose value is `undefined`.
-- `SessionStats`: `{ sessionFile?, sessionId, userMessages, assistantMessages, toolCalls, toolResults, totalMessages, tokens: { input, output, reasoning, cacheRead, cacheWrite, total }, premiumRequests, cost, contextUsage? }`.
-- `Model` is the model catalog object. `provider` and `id` are the stable selection keys; preserve unknown additional model metadata for forward compatibility.
-
-`RpcSessionState` contains:
-
-| Field | Type |
-| --- | --- |
-| `model?` | `Model` |
-| `thinkingLevel` | thinking-level string or omitted |
-| `isStreaming`, `isCompacting` | boolean |
-| `steeringMode`, `followUpMode` | `"all" \| "one-at-a-time"` |
-| `interruptMode` | `"immediate" \| "wait"` |
-| `sessionFile?`, `sessionId`, `sessionName?` | string |
-| `autoCompactionEnabled` | boolean |
-| `fastModeEnabled`, `fastModeActive` | boolean |
-| `tokensPerSecond` | number or `null` |
-| `messageCount`, `queuedMessageCount` | number |
-| `todoPhases` | `TodoPhase[]` |
-| `systemPrompt?` | `string[]` |
-| `dumpTools?` | array of `{ name, description, parameters, examples? }` |
-| `contextUsage?` | `{ tokens: number, contextWindow: number, percent: number }` |
-
-`RpcAvailableSlashCommand` is `{ name, source, aliases?, description?, input?: { hint? }, subcommands?: Array<{ name, description?, usage? }> }`. `source` is `"builtin"`, `"skill"`, `"extension"`, `"custom"`, `"mcp_prompt"`, or `"file"`.
-
-### Agent messages
-
-Events and history responses carry `AgentMessage` objects. Consumers should switch on `role` and preserve unknown roles because extensions can add message variants.
-
-| `role` | Core fields |
-| --- | --- |
-| `user` | `content: string \| (TextContent \| ImageContent)[]`, `timestamp`, plus optional attribution/transport metadata |
-| `developer` | same content forms and `timestamp` |
-| `assistant` | `content: ContentBlock[]`, `api`, `provider`, `model`, `usage`, `stopReason`, `timestamp`, plus optional error, timing, recovery, and provider metadata |
-| `toolResult` | `toolCallId`, `toolName`, `content`, `isError`, `timestamp`, optional `details` |
-| `bashExecution` | `command`, `output`, `exitCode?`, `cancelled`, `truncated`, `timestamp`, optional `meta`, `excludeFromContext` |
-| `pythonExecution` | `code`, `output`, `exitCode?`, `cancelled`, `truncated`, `timestamp`, optional `meta`, `excludeFromContext` |
-| `custom` | `customType`, `content`, `display`, `details?`, `timestamp` |
-| `hookMessage` | legacy shape matching `custom` |
-| `fileMention` | `files: Array<{ path, content, lineCount?, byteSize?, skippedReason?, image? }>`, `timestamp` |
-| `branchSummary` | `summary`, `fromId`, `timestamp` |
-| `compactionSummary` | `summary`, `shortSummary?`, `tokensBefore`, `tokensAfter?`, `method?`, `blocks?`, `images?`, `warning?`, `timestamp` |
-
-The common content blocks are:
-
-- `{ type: "text", text: string, textSignature?: string }`
-- `{ type: "thinking", thinking: string, thinkingSignature?: string, itemId?: string }`
-- `{ type: "redactedThinking", data: string }`
-- `ImageContent`
-- `{ type: "toolCall", id: string, name: string, arguments: object, intent?: string, …opaque replay metadata }`
-- `{ type: "fallback", from: { model: string }, to: { model: string } }`
-- `{ type: "anthropicServerTool", block: object }` for provider-native server tool replay
-
-Provider-specific assistant blocks can also appear. Ignore blocks you do not render, but retain them if you persist and replay protocol data.
-Assistant `usage` is `{ input, output, cacheRead, cacheWrite, totalTokens, contextTokens?, orchestration?, premiumRequests?, reasoningTokens?, cttl?, server?, cost: { input, output, cacheRead, cacheWrite, total } }`. `stopReason` is `"stop"`, `"length"`, `"toolUse"`, `"error"`, or `"aborted"`.
-
-## Event and notification schema
-
-### Agent lifecycle events
-
-| `type` | Fields after `type` |
-| --- | --- |
-| `agent_start` | none |
-| `agent_end` | `messages: AgentMessage[]`, `isTerminal?: boolean`, `telemetry?: object`, `coverage?: object`; transport compaction may also add `messageCount` |
-| `turn_start` | none |
-| `turn_end` | `message: AgentMessage`, `toolResults: ToolResultMessage[]` |
-| `message_start` | `message: AgentMessage` |
-| `message_update` | `message: AgentMessage`, `assistantMessageEvent: AssistantMessageEvent` |
-| `message_end` | `message: AgentMessage` |
-| `tool_execution_start` | `toolCallId`, `toolName`, `args`, `intent?` |
-| `tool_execution_update` | `toolCallId`, `toolName`, `args`, `partialResult` |
-| `tool_execution_end` | `toolCallId`, `toolName`, `result`, `isError?` |
-
-`AssistantMessageEvent` is one of:
-
-| Event `type` | Other fields |
-| --- | --- |
-| `start` | `partial: AssistantMessage` |
-| `text_start` | `contentIndex`, `partial` |
-| `text_delta` | `contentIndex`, `delta: string`, `partial` |
-| `text_end` | `contentIndex`, `content: string`, `partial` |
-| `thinking_start` | `contentIndex`, `partial` |
-| `thinking_delta` | `contentIndex`, `delta: string`, `partial` |
-| `thinking_end` | `contentIndex`, `content: string`, `partial` |
-| `image_end` | `contentIndex`, `content: ImageContent`, `partial` |
-| `toolcall_start` | `contentIndex`, `partial` |
-| `toolcall_delta` | `contentIndex`, `delta: string`, `partial` |
-| `toolcall_end` | `contentIndex`, `toolCall`, `partial` |
-| `done` | `reason: "stop" \| "length" \| "toolUse"`, `message: AssistantMessage` |
-| `error` | `reason: "aborted" \| "error"`, `error: AssistantMessage` |
-
-The spelling is `toolcall_*`, without an underscore between `tool` and `call`.
-
-### Session events
-
-| `type` | Fields after `type` |
-| --- | --- |
-| `auto_compaction_start` | `reason: "threshold" \| "overflow" \| "idle" \| "incomplete"`, `action: "context-full" \| "remote" \| "handoff" \| "shake" \| "snapcompact"` |
-| `auto_compaction_end` | `action`, `result?: CompactionResult`, `aborted`, `willRetry`, `errorMessage?`, `skipped?` |
-| `auto_retry_start` | `attempt`, `maxAttempts`, `delayMs`, `errorMessage`, `errorId?` |
-| `auto_retry_end` | `success`, `attempt`, `finalError?`, `retryErrors?` |
-| `retry_fallback_applied` | `from`, `to`, `role` |
-| `retry_fallback_succeeded` | `model`, `role` |
-| `model_changed` | none; call `get_state` if you need the new model |
-| `thinking_level_changed` | `thinkingLevel?`, `configured?`, `resolved?` |
-| `ttsr_triggered` | `rules: Rule[]` |
-| `todo_reminder` | `todos: TodoItem[]`, `attempt`, `maxAttempts` |
-| `todo_auto_clear` | none |
-| `irc_message` | `message: CustomMessage` |
-| `notice` | `level: "info" \| "warning" \| "error"`, `message`, `source?` |
-| `goal_updated` | `goal: Goal \| null`, `state?: GoalModeState` |
-
-### Other stdout frames
-
-| `type` | Fields and action |
-| --- | --- |
-| `ready` | `protocolVersion: 1`, `supportedProtocolVersions: [1,2]`, `maxFrameBytes`, `maxReassembledFrameBytes` |
-| `response` | command result envelope described above |
-| `rpc_chunk` | `chunkId`, `index`, `count`, `byteLength`, `data`; reassemble before dispatch |
-| `rpc_frame_error` | `error`, `originalType?`; a logical output could not fit the active transport |
-| `prompt_result` | `id?`, `agentInvoked: boolean`; currently emitted for local-only completion |
-| `available_commands_update` | `commands: RpcAvailableSlashCommand[]`; emitted at startup and when metadata changes |
-| `command_output` | `text: string`; output from a locally handled slash command |
-| `session_info_update` | `title?`, `sessionId`; session metadata changed |
-| `config_update` | `model?`, `thinkingLevel?`; a local command changed configuration |
-| `extension_error` | `extensionPath`, `event`, `error` |
-| `extension_ui_request` | UI sub-protocol below |
-| `host_tool_call`, `host_tool_cancel` | host-tool sub-protocol below |
-| `host_uri_request`, `host_uri_cancel` | host-URI sub-protocol below |
-| `subagent_lifecycle`, `subagent_progress`, `subagent_event` | subscription-gated subagent frames below |
-
-Unknown event types should be ignored or logged, not treated as a fatal protocol error. New optional fields and event types can be added without changing the transport version.
-
-## Extension UI sub-protocol
-
-All requests have `type: "extension_ui_request"` and an `id`. Only `select`, `confirm`, `input`, and `editor` expect a value response. Fire-and-forget presentation methods need no response.
-
-| `method` | Request fields |
-| --- | --- |
-| `select` | `title`, `options: string[]`, `optionDetails?: Array<{ description?: string }>`, `timeout?` |
-| `confirm` | `title`, `message`, `timeout?` |
-| `input` | `title`, `placeholder?`, `timeout?` |
-| `editor` | `title`, `prefill?`, `promptStyle?` |
-| `cancel` | `targetId` |
-| `notify` | `message`, `notifyType?: "info" \| "warning" \| "error"` |
-| `setStatus` | `statusKey`, `statusText?` |
-| `setWidget` | `widgetKey`, `widgetLines?: string[]`, `widgetPlacement?: "aboveEditor" \| "belowEditor"` |
-| `setTitle` | `title`; suppressed unless `PI_RPC_EMIT_TITLE=1` |
-| `set_editor_text` | `text` |
-| `open_url` | `url`, `launchUrl?`, `instructions?`; prefer `launchUrl` as the copy/open target when supplied |
-
-Reply on stdin with the same `id`:
-
-```text
-Text/select/editor: { type: "extension_ui_response", id, value: string }
-Confirmation:       { type: "extension_ui_response", id, confirmed: boolean }
-Cancel/timeout:      { type: "extension_ui_response", id, cancelled: true, timedOut?: boolean }
-```
-
-An unknown response id is ignored. When a request carries `timeout`, the host should enforce it and return the cancellation form with `timedOut: true`.
-
-OAuth `login` emits `open_url`, may emit notification frames, and can then ask for a pasted redirect or code with `input`. Providers that require interactive input before producing a URL are rejected in RPC mode; log in through interactive omp instead.
-
-## Host tools and host URIs
-
-After `set_host_tools`, omp can ask your process to execute a registered tool:
-
-```json
-{"type":"host_tool_call","id":"host-1","toolCallId":"toolu-1","toolName":"lookup_ticket","arguments":{"id":42}}
-```
-
-You may stream zero or more updates, then must complete the same id:
-
-```json
-{"type":"host_tool_update","id":"host-1","partialResult":{"content":[{"type":"text","text":"looking up ticket"}]}}
-{"type":"host_tool_result","id":"host-1","result":{"content":[{"type":"text","text":"ticket 42 is open"}]}}
-```
-
-`partialResult` and `result` are `{ content: Array<TextContent | ImageContent>, details?: any, isError?: boolean, providerMetadata?: object, useless?: boolean }`. Set top-level `isError: true` on `host_tool_result` to reject the pending call and surface the returned content as a tool error. `host_tool_cancel` is `{ type, id, targetId }`; stop the operation identified by `targetId`.
-
-After `set_host_uri_schemes`, omp routes reads and allowed writes of those schemes to your process:
-
-```text
-Read:  { type: "host_uri_request", id, operation: "read", url }
-Write: { type: "host_uri_request", id, operation: "write", url, content }
-Cancel:{ type: "host_uri_cancel", id, targetId }
-```
-
-Reply with:
-
-```text
-Success read:  { type: "host_uri_result", id, content, contentType?, notes?, immutable? }
-Success write: { type: "host_uri_result", id }
-Failure:       { type: "host_uri_result", id, isError: true, error?: string, content?: string }
-```
-
-`contentType` is `"text/markdown"`, `"application/json"`, or `"text/plain"` and defaults to plain text. Successful reads require `content`. A result-level `immutable` overrides the registered scheme for that read. The `edit` tool does not edit host URIs; register the scheme as writable to let full-replacement writes use the `write` path.
-
-## Subagent frames
-
-Forwarding defaults to `off`:
-
-- `progress` emits `subagent_lifecycle` and `subagent_progress`.
-- `events` also emits every nested `subagent_event`.
-
-`subagent_lifecycle.payload` is `{ id, agent, agentSource, description?, status: "started" | "completed" | "failed" | "aborted", sessionFile?, parentToolCallId?, index, detached? }`.
-
-`subagent_progress.payload` is `{ index, agent, agentSource, task, parentToolCallId?, assignment?, progress, sessionFile?, detached? }`. `progress` includes identity/status, recent tool/output summaries, counts, tokens, cost, duration, model selection, and optional retry state. Treat newly added progress metrics as optional.
-
-`subagent_event.payload` is `{ id, event: AgentSessionEvent }`, where `event` uses the same lifecycle schema above.
-
-`RpcSubagentSnapshot` returned by `get_subagents` is `{ id, index, agent, agentSource, description?, status, task?, assignment?, sessionFile?, lastUpdate, progress?, parentToolCallId? }`.
-
-`RpcSubagentMessagesResult` is `{ sessionFile, fromByte, nextByte, reset, entries, messages }`. Select by `subagentId` or `sessionFile`; `fromByte` enables incremental reads. If the transcript shrank beneath `fromByte`, the server restarts at byte zero and sets `reset: true`.
-
-## Host implementation checklist
-
-A robust language-neutral client should:
-
-1. Spawn one process per independently controlled session and wait for `ready`.
-2. Keep stdin writes serialized, newline-terminated, and flushed.
-3. Continuously read stdout while requests are pending; never wait for one response before servicing callbacks.
-4. Generate unique string ids and correlate responses by id, not arrival order.
-5. Track prompt acceptance separately from terminal or local-only completion.
-6. Negotiate v2 and strictly reassemble chunks when large messages are possible.
-7. Dispatch extension UI, host tool, and host URI requests without blocking the reader.
-8. Preserve unknown fields, message roles, content blocks, and event types for forward compatibility.
-9. Close stdin, then wait for process exit during orderly shutdown.