@bastani/atomic 0.9.18 → 0.9.19-alpha.10

package/docs/reference.md

@@ -0,0 +1,52 @@
+---
+title: Reference
+sidebarTitle: "Reference index"
+description: "Exact contracts: CLI, settings, environment variables, keybindings, tools, session format, provider, model, compaction, extension, SDK, RPC, and TUI references."
+---
+
+# Reference
+
+Reference pages state exact contracts. They use stable command, flag, setting, type, event, method, and tool names as headings, and they do not carry a tutorial narrative. If you want to learn a capability rather than look one up, start at [Guides](/guides) or [Build with Atomic](/build).
+
+## Everyday contracts
+
+- [CLI reference](/reference/cli) — every command, flag, argument, and environment variable.
+- [Settings](/settings) — every settings field, with defaults and constraints.
+- [Environment variables](/environment-variables) — Atomic/Pi aliases, provider credentials, and bash session metadata.
+- [Keybindings](/keybindings) — default shortcuts and custom keybinding actions.
+- [Built-in tools](/tools) — the tools Atomic ships, and the [edit tool](/tools/edit) in detail.
+
+## Domain contracts
+
+- [Provider reference](/providers/reference) — stop reasons and credential resolution order.
+- [Model configuration reference](/models/reference) — provider and model fields, overrides, variants, and API compatibility.
+- [Compaction reference](/compaction/reference) — parameters, persistence, hooks, formats, settings, and historical formats.
+- [Extension API reference](/extensions/api-reference) — `ExtensionContext`, `ExtensionCommandContext`, and `ExtensionAPI` methods.
+- [Extension events](/extensions/events) — every event and its payload.
+- [SDK API reference](/sdk/reference) — options, loaders, return values, run modes, and exports.
+- [RPC protocol](/rpc/protocol) — commands, events, types, and errors.
+- [TUI API reference](/tui/reference) — component, focusable, input, and rendering contracts.
+- [Session format](/session-format) — the JSONL session file format, entry types, and `SessionManager` API.
+- [Theme reference](/themes/reference) — theme file format, color tokens, and color values.
+- [Skill reference](/skills/reference) — `SKILL.md` frontmatter and validation.
+- [Subagent reference](/subagents/reference) — fallback models and reasoning levels.
+- [Intercom reference](/intercom/reference) — the `intercom` tool contract and settings.
+- [Package reference](/packages/reference) — filtering, scope, and deduplication.
+- [Provider API reference](/custom-provider/api-reference) — provider config and model definition contracts.
+- [Workflow API reference](/workflows/api-reference) — workflow, stage, and context contracts.
+
+## Reference
+
+- [Session format](/session-format) - JSONL session file format, entry types, and SessionManager API.
+
+## Platform setup
+
+- [Windows](/windows)
+- [Termux on Android](/termux)
+- [tmux](/tmux)
+- [Terminal setup](/terminal-setup)
+- [Shell aliases](/shell-aliases)
+
+## Development
+
+- [Development](/development) - local setup, project structure, and debugging.

package/docs/rpc/examples.md

@@ -0,0 +1,64 @@
+---
+title: RPC client examples
+description: Additional RPC client implementations.
+---
+
+# RPC client examples
+
+## Example: Interactive Client (Node.js)
+
+See [`test/rpc-example.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) for a typed client implementation.
+
+For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/rpc-demo.ts) extension.
+
+```javascript
+const { spawn } = require("child_process");
+const { StringDecoder } = require("string_decoder");
+
+const agent = spawn("atomic", ["--mode", "rpc", "--no-session"]);
+
+function attachJsonlReader(stream, onLine) {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+
+    stream.on("data", (chunk) => {
+        buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
+
+        while (true) {
+            const newlineIndex = buffer.indexOf("\n");
+            if (newlineIndex === -1) break;
+
+            let line = buffer.slice(0, newlineIndex);
+            buffer = buffer.slice(newlineIndex + 1);
+            if (line.endsWith("\r")) line = line.slice(0, -1);
+            onLine(line);
+        }
+    });
+
+    stream.on("end", () => {
+        buffer += decoder.end();
+        if (buffer.length > 0) {
+            onLine(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
+        }
+    });
+}
+
+attachJsonlReader(agent.stdout, (line) => {
+    const event = JSON.parse(line);
+
+    if (event.type === "message_update") {
+        const { assistantMessageEvent } = event;
+        if (assistantMessageEvent.type === "text_delta") {
+            process.stdout.write(assistantMessageEvent.delta);
+        }
+    }
+});
+
+// Send prompt
+agent.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");
+
+// Abort on CTRL+C
+process.on("SIGINT", () => {
+    agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n");
+});
+```

package/docs/rpc/extension-ui.md

@@ -0,0 +1,198 @@
+---
+title: RPC extension UI protocol
+description: Drive extension-rendered UI over the RPC transport.
+---
+
+# RPC extension UI protocol
+
+## Extension UI Protocol
+
+Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()`, etc. In RPC mode, these are translated into a request/response sub-protocol on top of the base command/event flow.
+
+There are two categories of extension UI methods:
+
+- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
+- **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
+
+If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
+
+Some `ExtensionUIContext` methods are not supported or degraded in RPC mode because they require direct TUI access:
+- `custom()` returns `undefined`
+- `setWorkingMessage()`, `setWorkingIndicator()`, `setFooter()`, `setHeader()`, `setEditorComponent()` are no-ops
+- `getEditorText()` returns `""`
+- `setToolsExpanded()` and `getToolsExpanded()` maintain context-local expansion state; `getChatRenderSettings().toolOutputExpanded` reports the same value. A same-value `setToolsExpanded()` call is a no-op and does not request a custom-UI render. This state is not sent through the client extension-UI protocol.
+- `pasteToEditor()` delegates to `setEditorText()` (no paste/collapse handling)
+- `getAllThemes()` returns `[]`
+- `getTheme()` returns `undefined`
+- `setTheme()` returns `{ success: false, error: "..." }`
+
+Note: `ctx.mode` is `"rpc"` and `ctx.hasUI` is `true` in RPC mode because the dialog and fire-and-forget methods are functional via the extension UI sub-protocol. Use `ctx.mode === "tui"` to guard TUI-specific features like `custom()` that require a real terminal.
+
+### 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": "atomic - 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}
+```