apex-code 0.5.0 → 0.5.2

package/docs/rpc-extension-ui.md

@@ -0,0 +1,200 @@
+# RPC Extension UI
+
+Extensions can request user interaction through `ctx.ui`. In RPC mode, supported calls become a request/response subprotocol alongside normal [RPC commands](rpc-commands.md) and [session events](json.md).
+
+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.
+
+## Limitations
+
+Some `ExtensionUIContext` methods are not supported or degraded in RPC mode because they require direct terminal UI access:
+
+- `custom()` returns `undefined`.
+- `onTerminalInput()` returns a no-op unsubscribe function.
+- `setWorkingMessage()`, `setWorkingVisible()`, `setWorkingIndicator()`, `setHiddenThinkingLabel()`, `setFooter()`, `setHeader()`, `addAutocompleteProvider()`, `setEditorComponent()`, and `setToolsExpanded()` are no-ops.
+- `getEditorText()` returns `""` and `getEditorComponent()` returns `undefined`.
+- `getToolsExpanded()` returns `false`.
+- `pasteToEditor()` delegates to `setEditorText()` without terminal paste handling.
+- `getAllThemes()` returns `[]`, and `getTheme()` returns `undefined`.
+- `setTheme()` returns `{ success: false, error: "Theme switching not supported in RPC mode" }`.
+
+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.
+
+## Requests from Apex Code
+
+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": "Apex Code - 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"
+}
+```
+
+## Responses to Apex Code
+
+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}
+```
+
+## Example
+
+See the checked [RPC extension UI client](../examples/rpc-extension-ui.ts) and its [demo extension](../examples/extensions/rpc-demo.ts).
+
+The exported request and response unions are defined in [`rpc-types.ts`](https://github.com/Fchery87/apex-code/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts). See [Extensions](extensions.md#ui-and-modes) for mode-independent extension guidance.

package/docs/rpc.md

@@ -1,38 +1,38 @@
 # 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.
+RPC mode runs Pi as a long-lived subprocess controlled through JSON records on stdin and stdout. Use it for language-independent integrations, process isolation, IDEs, and custom user interfaces.
 
 **Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `apex-code` instead of spawning a subprocess. See [`src/core/agent-session.ts`](../src/core/agent-session.ts) for the API. For a subprocess-based TypeScript client, see [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts).
 
-## Starting RPC Mode
+| Interface | Process boundary | Control model | Best fit |
+|---|---|---|---|
+| [SDK](sdk.md) | In process | Direct TypeScript methods and events | Node.js or Bun hosts that want complete API access |
+| RPC | Child process | JSONL commands, responses, and events | Other languages, isolated processes, IDEs, or custom clients |
+
+## Start RPC mode
 
 ```bash
 apex-code --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
+Normal CLI options still select the working folder, model, tools, resources, and session behavior. Common choices include `--provider`, `--model`, `--name`, `--no-session`, and `--session-dir`. See [Command Line](cli.md) for the complete, version-specific interface; `apex-code --help` is authoritative for the installed version.
 
-## Protocol Overview
+RPC mode rejects `@file` prompt arguments. Send prompts through the [`prompt`](rpc-commands.md#prompt) command instead.
 
-- **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
+## Protocol records
 
-All commands support an optional `id` field for request/response correlation. If provided, the corresponding response will include the same `id`. `bash_execution_update` events also include the `id` of their originating `bash` command.
+The protocol has four record families:
 
-### Framing
+| Direction | Record | Purpose |
+|---|---|---|
+| stdin | Command | Ask Pi to prompt, inspect state, change configuration, or manage the session |
+| stdout | `response` | Report whether one command succeeded and return any command data |
+| stdout | Session event | Stream run, message, tool, queue, compaction, and retry activity |
+| Both | Extension UI record | Forward supported extension interactions between Pi and the client |
 
-RPC mode uses strict JSONL semantics with LF (`\n`) as the only record delimiter.
+See [RPC Commands](rpc-commands.md), [JSON Event Stream](json.md), and [RPC Extension UI](rpc-extension-ui.md) for the canonical record definitions.
 
-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
+### Correlate commands and responses
 
 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.
 
@@ -123,7 +123,7 @@ See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up mess
 
 #### abort
 
-Abort the current agent operation.
+Abort the current operation and wait for the session to become idle before responding.
 
 ```json
 {"type": "abort"}
@@ -1362,257 +1362,155 @@ Responses are sent for dialog methods only (`select`, `confirm`, `input`, `edito
 #### Confirmation response (confirm)
 
 ```json
-{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}
+{"id":"req-1","type":"get_state"}
+{"id":"req-1","type":"response","command":"get_state","success":true,"data":{"...":"..."}}
 ```
 
-#### Cancellation response (any dialog)
+Use unique IDs whenever more than one command can be outstanding. Command handling is asynchronous, so clients should correlate by ID rather than response order.
 
-Dismiss any dialog method. The extension receives `undefined` (for select/input/editor) or `false` (for confirm).
+Session events generally have no command ID because they describe session activity. `bash_execution_update` is the exception: when the originating [`bash`](rpc-commands.md#bash) command has an ID, its output events repeat that ID.
 
-```json
-{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}
-```
+An `extension_ui_response` uses the ID supplied by its `extension_ui_request`. It does not produce a normal command response.
 
-## Error Handling
+## Framing
 
-Failed commands return a response with `success: false`:
+RPC uses strict JSONL framing. Write one complete JSON object per record and terminate it with LF (`\n`). Read stdout as a byte or UTF-8 stream and split records only on LF. Strip an optional preceding carriage return to accept CRLF input.
 
-```json
-{
-  "type": "response",
-  "command": "set_model",
-  "success": false,
-  "error": "Model not found: invalid/model"
-}
-```
+Do not use a generic line reader that treats Unicode line or paragraph separators as record boundaries. In particular, Node.js `readline` also splits on `U+2028` and `U+2029`, which are valid inside JSON strings.
 
-Parse errors:
+Read stdout continuously. Pi honors stdout backpressure, but a client that stops reading can stall the process. Honor stdin backpressure when writing commands. Stdout is reserved for protocol records; diagnostics and application logging go to stderr.
 
-```json
-{
-  "type": "response",
-  "command": "parse",
-  "success": false,
-  "error": "Failed to parse command: Unexpected token..."
-}
-```
+## Run lifecycle
 
-## 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/modes/json-event.ts`](../src/modes/json-event.ts) - `JsonAgentSessionEvent`
-- [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
-
-### Model
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean model work completed:
 
 ```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
-  }
-}
+{"id":"req-2","type":"prompt","message":"Review this repository"}
+{"id":"req-2","type":"response","command":"prompt","success":true}
 ```
 
-### UserMessage
+Continue consuming [events](json.md) after that response. `agent_end` marks the end of one low-level agent run, but retries, overflow recovery, compaction, steering, or follow-up work can still follow. Wait for `agent_settled` when the client needs to know Pi will not continue automatically.
 
-```json
-{
-  "role": "user",
-  "content": "Hello!",
-  "timestamp": 1733234567890,
-  "attachments": []
-}
-```
+Subscribe before sending a prompt to avoid missing a fast completion. `RpcClient.promptAndWait()` does this internally. If using separate `RpcClient` calls, install the event listener before `prompt()` and call `waitForIdle()` only while a run is active.
 
-The `content` field can be a string or an array of `TextContent`/`ImageContent` blocks.
+## Errors
 
-### AssistantMessage
+A failed command returns one response with `success: false`:
 
 ```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
-}
+{"id":"req-3","type":"response","command":"set_model","success":false,"error":"Model not found: invalid/model"}
 ```
 
-Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`
-
-### ToolResultMessage
+Malformed JSON produces a parse response without a request ID:
 
 ```json
-{
-  "role": "toolResult",
-  "toolCallId": "call_123",
-  "toolName": "bash",
-  "content": [{"type": "text", "text": "total 48\ndrwxr-xr-x ..."}],
-  "usage": {
-    "input": 100,
-    "output": 50,
-    "cacheRead": 0,
-    "cacheWrite": 0,
-    "totalTokens": 150,
-    "cost": {"input": 0.0003, "output": 0.00075, "cacheRead": 0, "cacheWrite": 0, "total": 0.00105}
-  },
-  "isError": false,
-  "timestamp": 1733234567890
-}
+{"type":"response","command":"parse","success":false,"error":"Failed to parse command: Unexpected token..."}
 ```
 
-`usage` is optional and reports nested LLM work performed by the tool. When present, it contributes to session token and cost totals.
+A success response only covers command handling. Provider failures and aborts after a prompt is accepted appear in the message and event stream.
 
-### BashExecutionMessage
+Clients must also handle child-process startup failures, unexpected exits, stderr diagnostics, cancellation, and their own deadlines. Do not parse stderr as protocol data.
 
-Created by the `bash` RPC command (not by LLM tool calls):
+## Shutdown
 
-```json
-{
-  "role": "bashExecution",
-  "command": "ls -la",
-  "output": "total 48\ndrwxr-xr-x ...",
-  "exitCode": 0,
-  "cancelled": false,
-  "truncated": false,
-  "fullOutputPath": null,
-  "timestamp": 1733234567890
-}
-```
+Close the child's stdin to request an orderly shutdown. Pi disposes the active runtime before exiting. Clients should still handle process signals and unexpected exits.
 
-### Attachment
+An extension can also request shutdown through its extension context. Pi completes shutdown after the current command or after the active run emits `agent_settled`.
 
-```json
-{
-  "id": "img1",
-  "type": "image",
-  "fileName": "photo.jpg",
-  "mimeType": "image/jpeg",
-  "size": 102400,
-  "content": "base64-encoded-data...",
-  "extractedText": null,
-  "preview": null
-}
-```
+## Minimal client
 
-## Example: Basic Client (Python)
+This Python example uses a binary pipe reader, which splits on LF without treating Unicode separators as protocol boundaries:
 
 ```python
-import subprocess
 import json
+import subprocess
 
 proc = subprocess.Popen(
     ["apex-code", "--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_end":
+assert process.stdin is not None
+assert process.stdout is not None
+
+command = {"id": "prompt-1", "type": "prompt", "message": "Hello"}
+process.stdin.write(json.dumps(command).encode("utf-8") + b"\n")
+process.stdin.flush()
+
+while line := process.stdout.readline():
+    record = json.loads(line)
+    if record.get("type") == "message_update":
+        update = record["assistantMessageEvent"]
+        if update["type"] == "text_delta":
+            print(update["delta"], end="", flush=True)
+    elif record.get("type") == "agent_settled":
         print()
         break
+
+process.stdin.close()
+process.wait()
 ```
 
-## Example: Interactive Client (Node.js)
+For maintained TypeScript clients, use the checked [RPC client example](../examples/rpc-client.ts). It requires a built Pi CLI because the repository example points to `dist/cli.js`.
 
-See [`test/rpc-example.ts`](../test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts) for a typed client implementation.
+## Reference
 
-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.
+- [RPC Commands](rpc-commands.md): every stdin command and response
+- [JSON Event Stream](json.md): shared stdout session events and streaming reconstruction
+- [RPC Extension UI](rpc-extension-ui.md): dialogs, notifications, responses, and limitations
+- [Message Types](message-types.md): messages and content blocks used by responses and events
+- [Session File Format](session-format.md): entries returned by session commands
+- [`rpc-types.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts): exported TypeScript protocol definitions
+- [`RpcClient`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts): subprocess client implementation
 
-```javascript
-const { spawn } = require("child_process");
-const { StringDecoder } = require("string_decoder");
+## Moved reference anchors
 
 const agent = spawn("apex-code", ["--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");
-});
-```
+<a id="prompt"></a>
+<a id="steer"></a>
+<a id="follow_up"></a>
+<a id="abort"></a>
+<a id="clear_queue"></a>
+<a id="new_session"></a>
+<a id="get_state"></a>
+<a id="get_messages"></a>
+<a id="set_model"></a>
+<a id="cycle_model"></a>
+<a id="get_available_models"></a>
+<a id="set_thinking_level"></a>
+<a id="cycle_thinking_level"></a>
+<a id="get_available_thinking_levels"></a>
+<a id="set_steering_mode"></a>
+<a id="set_follow_up_mode"></a>
+<a id="compact"></a>
+<a id="set_auto_compaction"></a>
+<a id="set_auto_retry"></a>
+<a id="abort_retry"></a>
+<a id="bash"></a>
+<a id="abort_bash"></a>
+<a id="get_session_stats"></a>
+<a id="export_html"></a>
+<a id="switch_session"></a>
+<a id="fork"></a>
+<a id="clone"></a>
+<a id="get_fork_messages"></a>
+<a id="get_entries"></a>
+<a id="get_tree"></a>
+<a id="get_last_assistant_text"></a>
+<a id="set_session_name"></a>
+<a id="get_commands"></a>
+
+Command details moved to [RPC Commands](rpc-commands.md).
+
+<a id="message_update-streaming"></a>
+<a id="bash_execution_update"></a>
+<a id="compaction_start--compaction_end"></a>
+<a id="summarization_retry_scheduled--summarization_retry_attempt_start--summarization_retry_finished"></a>
+
+Event details moved to [JSON Event Stream](json.md).
+
+<a id="extension-ui-protocol"></a>
+
+Extension interaction details moved to [RPC Extension UI](rpc-extension-ui.md).