RPC protocol

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.

{"id": "req-1", "type": "prompt", "message": "Hello, world!"}

With images:

{"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:

{"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}

• "steer": Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
• "followUp": Wait until the agent finishes. Message is delivered only when agent stops.

If the agent is streaming and no streamingBehavior is specified, the command returns an error.

Extension commands: If the message is an extension command (e.g., /mycommand), it executes immediately even during streaming. Extension commands manage their own LLM interaction via pi.sendMessage().

Input expansion: Skill commands (/skill:name) and prompt templates (/template) are expanded before sending/queueing.

Response:

{"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).

{"type": "steer", "message": "Stop and do this instead"}

With images:

{"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:

{"type": "response", "command": "steer", "success": true}

See 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).

{"type": "follow_up", "message": "After you're done, also do this"}

With images:

{"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:

{"type": "response", "command": "follow_up", "success": true}

See set_follow_up_mode for controlling how follow-up messages are processed.

abort

Abort the current operation and wait for the session to become idle before responding.

{"type": "abort"}

Response:

{"type": "response", "command": "abort", "success": true}

clear_queue

Remove queued steering and follow-up messages and return their text.

{"type": "clear_queue"}

Response:

{
  "type": "response",
  "command": "clear_queue",
  "success": true,
  "data": {
    "steering": ["Change direction"],
    "followUp": ["Summarize when finished"]
  }
}

To implement interactive Esc behavior, send clear_queue before abort, then restore the returned text in the client editor. abort continues queued messages when they remain in the session.

new_session

Start a fresh session. Can be cancelled by a session_before_switch extension event handler.

{"type": "new_session"}

With optional parent session tracking:

{"type": "new_session", "parentSession": "/path/to/parent-session.jsonl"}

Response:

{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}

If an extension cancelled:

{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": true}}

State

get_state

Get current session state.

{"type": "get_state"}

Response:

{
  "type": "response",
  "command": "get_state",
  "success": true,
  "data": {
    "model": {...},
    "thinkingLevel": "medium",
    "isStreaming": false,
    "isCompacting": false,
    "steeringMode": "all",
    "followUpMode": "one-at-a-time",
    "sessionFile": "/path/to/session.jsonl",
    "sessionId": "abc123",
    "sessionName": "my-feature-work",
    "autoCompactionEnabled": true,
    "messageCount": 5,
    "pendingMessageCount": 0
  }
}

The model field is a full Model object or null. Its contextWindow is the model's token budget. The sessionName field is the display name set via set_session_name, or omitted if not set.

get_messages

Get all messages in the conversation.

{"type": "get_messages"}

Response:

{
  "type": "response",
  "command": "get_messages",
  "success": true,
  "data": {"messages": [...]}
}

Messages are AgentMessage objects (see Types).

Model

set_model

Switch to a specific model. Omit persist (or set it false) to change only the current session. Set "persist": true to also save defaultProvider, defaultModel, and the effective thinking level in settings, matching an interactive /model selection.

{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}

Persist as the startup default:

{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514", "persist": true}

Response contains the full Model object:

{
  "type": "response",
  "command": "set_model",
  "success": true,
  "data": {...}
}

cycle_model

Cycle to the next available model. Returns null when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a null or unchanged result does not. Set "persist": true to also write the cycled model as the startup default.

{"type": "cycle_model"}

Response:

{
  "type": "response",
  "command": "cycle_model",
  "success": true,
  "data": {
    "model": {...},
    "thinkingLevel": "medium",
    "isScoped": false
  }
}

The model field is a full Model object.

get_available_models

List all configured models.

{"type": "get_available_models"}

Response contains an array of full Model objects:

{
  "type": "response",
  "command": "get_available_models",
  "success": true,
  "data": {
    "models": [...]
  }
}

The subprocess protocol returns full Model objects. The exported TypeScript RpcClient.getAvailableModels() keeps its smaller backward-compatible ModelInfo shape (provider, id, contextWindow, reasoning) and adds optional compat. When present, compat exposes constrained-sampling capability claims including supportsStrictTools, supportsStrictMode, canonical supportsOpenAIGrammarTools, and Atomic's synchronized supportsGrammarTools alias. Treat absence as unknown/unsupported; do not infer enforcement from the provider name.

const models = await client.getAvailableModels();
const capabilities = models[0]?.compat;
if (capabilities?.supportsStrictTools) {
  // The selected model advertises Anthropic/Bedrock strict-tool support.
}

logout_provider

Remove a provider's stored credential in the authoritative agent process, refresh its available-model catalog, and return the remaining authentication status and new catalog. Environment variables and models.json authentication are reported but are not modified.

{"type": "logout_provider", "provider": "github-copilot"}

Response:

{
  "type": "response",
  "command": "logout_provider",
  "success": true,
  "data": {
    "provider": "github-copilot",
    "authStatus": {"configured": false},
    "models": [],
    "scopedModels": []
  }
}

models preserves the refreshed catalog order. scopedModels is optional. If authentication remains through an environment variable, authStatus.source is "environment" and authStatus.label names the variable.

Thinking

set_thinking_level

Set the reasoning/thinking level for models that support it. Omit persist (or set it false) to change only the current session. Set "persist": true to also save defaultThinkingLevel and, when a model is active, its per-model override. Interactive /thinking choices request persistence automatically.

{"type": "set_thinking_level", "level": "high"}

Persist as the startup default:

{"type": "set_thinking_level", "level": "high", "persist": true}

Levels: "off", "minimal", "low", "medium", "high", "xhigh", "max".

xhigh and max are available only when the active model's capability mapping supports them; unsupported levels are clamped by the session model controls.

Response may omit data for compatibility with older clients:

{"type": "response", "command": "set_thinking_level", "success": true}

Current engines include the effective level after capability clamping and, when a model is active, the provider/model the engine persisted against:

{"type": "response", "command": "set_thinking_level", "success": true, "data": {"level": "high", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}}

Use the acknowledgement's provider/model when recording a persisted thinking override, not whichever model is active when your callback runs. Keep newer thinking_level_changed state if an older acknowledgement arrives later. RpcClient.setThinkingLevel(level) remains a one-argument Promise<void> method.

cycle_thinking_level

Cycle through available thinking levels. Returns null data if model doesn't support thinking.

{"type": "cycle_thinking_level"}

Response:

{
  "type": "response",
  "command": "cycle_thinking_level",
  "success": true,
  "data": {"level": "high"}
}

get_available_thinking_levels

Return the thinking levels supported by the current model, in cycle order.

{"type": "get_available_thinking_levels"}

Response:

{
  "type": "response",
  "command": "get_available_thinking_levels",
  "success": true,
  "data": {"levels": ["off", "low", "medium", "high"]}
}

Queue Modes

set_steering_mode

Control how steering messages (from steer) are delivered.

{"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:

{"type": "response", "command": "set_steering_mode", "success": true}

set_follow_up_mode

Control how follow-up messages (from follow_up) are delivered.

{"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:

{"type": "response", "command": "set_follow_up_mode", "success": true}

Compaction

compact

Run verbatim line compaction with the session model. It preserves exactly the newest preserve_recent context-visible messages, default two, without aligning to user turns. Zero compacts the whole active transcript and returns firstKeptEntryId: null. The resulting durable entry uses details.strategy: "verbatim-lines"; see Compaction for behavior and settings.

{"type": "compact"}

Response:

{
  "type": "response",
  "command": "compact",
  "success": true,
  "data": {
    "compactedText": "[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.",
    "firstKeptEntryId": "m7",
    "tokensBefore": 150000,
    "promptVersion": 3,
    "parameters": {
      "compression_ratio": 0.5,
      "preserve_recent": 2,
      "query": "fix the test"
    },
    "rung": "planned",
    "stats": {
      "linesBefore": 812,
      "linesDeleted": 417,
      "linesKept": 395,
      "rangeCount": 63,
      "tokensBefore": 150000,
      "tokensAfter": 72000,
      "percentReduction": 52
    },
    "backupPath": "/path/to/session.jsonl.2026-06-06T00-00-00-000Z.compact.bak"
  }
}

firstKeptEntryId is a string when at least one ordinary message remains outside compaction and null when none does. RPC clients must accept both values.

set_auto_compaction

Enable or disable automatic compaction when context is nearly full.

{"type": "set_auto_compaction", "enabled": true}

Response:

{"type": "response", "command": "set_auto_compaction", "success": true}

Retry

set_auto_retry

Enable or disable automatic retry on transient errors (overloaded, rate limit, 5xx).

{"type": "set_auto_retry", "enabled": true}

Response:

{"type": "response", "command": "set_auto_retry", "success": true}

abort_retry

Abort an in-progress retry (cancel the delay and stop retrying).

{"type": "abort_retry"}

Response:

{"type": "response", "command": "abort_retry", "success": true}

Bash

bash

Execute a shell command and add output to conversation context.

{"type": "bash", "command": "ls -la"}

Response:

{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "total 48\ndrwxr-xr-x ...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": false
  }
}

While the command runs, Atomic emits ordered deltas correlated by the command id:

{"type":"bash_execution_update","id":"req-1","channel":"stdout","delta":"building...\n"}
{"type":"bash_execution_update","id":"req-1","channel":"stderr","delta":"warning\n"}

channel is exactly "stdout" or "stderr". Deltas preserve the observed order for each request. Concurrent bash requests may interleave globally but never share IDs.

Request ownership survives new_session, switch_session, import_session, fork, and clone while the command runs. Later deltas keep the original ID and do not contaminate the replacement session. Exactly one ordinary response is the terminal record for completion, cancellation, or error.

If output was truncated, includes fullOutputPath. Persisted bash output lives in the owner- and session-scoped temp tree (<tmpdir>/atomic-<uid>/<session-id>/), not at the temp root — see Tools for the layout, permissions, size cap, and retention:

{
  "type": "response",
  "command": "bash",
  "success": true,
  "data": {
    "output": "truncated output...",
    "exitCode": 0,
    "cancelled": false,
    "truncated": true,
    "fullOutputPath": "/tmp/atomic-501/019fdf86-cf98-7327-8a73-21365028f6ae/atomic-bash-abc123.log"
  }
}

fullOutputPath is null when the temp directory could not be created or the write was refused; treat it as absent rather than assuming a path exists.

How bash results reach the LLM:

The bash command returns a BashResult and saves output in the session where the request started, even if another session becomes active before completion. The saved BashExecutionMessage emits no event of its own.

The initiating session's next prompt includes the output as user context in 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 running bash commands. Omit requestId to retain the legacy behavior of aborting every active RPC-owned bash request, including requests that began before a session replacement, or provide the target bash command's id to cancel only that request. Targeted and legacy cancellation remain isolated across concurrent IDs. Closing RPC cancels and drains remaining owned requests before shutdown.

{"id":"cancel-1","type":"abort_bash","requestId":"req-1"}

Response:

{"id":"cancel-1","type":"response","command":"abort_bash","success":true}

Session

get_session_stats

Get token usage, cost statistics, and current context window usage.

{"type": "get_session_stats"}

Response:

{
  "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.

export_html

Export session to an HTML file.

{"type": "export_html"}

With custom path:

{"type": "export_html", "outputPath": "/tmp/session.html"}

Response:

{
  "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.

{"type": "switch_session", "sessionPath": "/path/to/session.jsonl"}

Response:

{"type": "response", "command": "switch_session", "success": true, "data": {"cancelled": false}}

If an extension cancelled the switch:

{"type": "response", "command": "switch_session", "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.

{"type": "fork", "entryId": "abc123"}

Response:

{
  "type": "response",
  "command": "fork",
  "success": true,
  "data": {"text": "The original prompt text...", "cancelled": false}
}

If an extension cancelled the fork:

{
  "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.

{"type": "clone"}

Response:

{
  "type": "response",
  "command": "clone",
  "success": true,
  "data": {"cancelled": false}
}

If an extension cancelled the clone:

{
  "type": "response",
  "command": "clone",
  "success": true,
  "data": {"cancelled": true}
}

get_fork_messages

Get user messages available for forking.

{"type": "get_fork_messages"}

Response:

{
  "type": "response",
  "command": "get_fork_messages",
  "success": true,
  "data": {
    "messages": [
      {"entryId": "abc123", "text": "First prompt..."},
      {"entryId": "def456", "text": "Second prompt..."}
    ]
  }
}

get_entries

Get all session entries in append order, excluding the session header. Unlike get_messages, this includes pre-compaction history and abandoned branches.

Entry IDs are stable in the append-only tree. Use the last entry ID you have seen as since to get only entries strictly after it, even across client restarts.

{"type": "get_entries"}

With a cursor:

{"type": "get_entries", "since": "abc123"}

Response:

{
  "type": "response",
  "command": "get_entries",
  "success": true,
  "data": {
    "entries": [
      {"type": "message", "id": "def456", "parentId": "abc123", "timestamp": "...", "message": {"role": "user", "...": "..."}}
    ],
    "leafId": "def456"
  }
}

leafId is the id of the current leaf entry (null for an empty session), so a client can tell in one round trip whether the active branch moved. If since does not match any entry id, the response is success: false.

get_tree

Get the session as a tree of entries. Each node is {entry, children, label?, labelTimestamp?}. A well-formed session has a single root; orphaned entries (broken parent chain) also appear as roots.

{"type": "get_tree"}

Response:

{
  "type": "response",
  "command": "get_tree",
  "success": true,
  "data": {
    "tree": [
      {
        "entry": {"type": "message", "id": "abc123", "parentId": null, "...": "..."},
        "children": [
          {"entry": {"type": "message", "id": "def456", "parentId": "abc123", "...": "..."}, "children": []}
        ]
      }
    ],
    "leafId": "def456"
  }
}

get_last_assistant_text

Get the text content of the last assistant message.

{"type": "get_last_assistant_text"}

Response:

{
  "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.

{"type": "set_session_name", "name": "my-feature-work"}

Response:

{
  "type": "response",
  "command": "set_session_name",
  "success": true
}

The current session name is available via get_state in the sessionName field. To set the initial name when starting RPC mode, pass --name <name> or -n <name> to the atomic --mode rpc process.

Commands

get_commands

Get available commands (extension commands, prompt templates, and skills). These can be invoked via the prompt command by prefixing with /.

{"type": "get_commands"}

Response:

{
  "type": "response",
  "command": "get_commands",
  "success": true,
  "data": {
    "commands": [
      {"name": "session-name", "description": "Set or clear session name", "source": "extension", "path": "/home/user/.atomic/agent/extensions/session.ts"},
      {"name": "fix-tests", "description": "Fix failing tests", "source": "prompt", "location": "project", "path": "/home/user/myproject/.atomic/prompts/fix-tests.md"},
      {"name": "skill:brave-search", "description": "Web search via Brave API", "source": "skill", "location": "user", "path": "/home/user/.atomic/agent/skills/brave-search/SKILL.md"}
    ]
  }
}

Each command has:

• name: Command name (invoke with /name)
• description: Human-readable description (optional for extension commands)
• source: What kind of command:
  • "extension": Registered via pi.registerCommand() in an extension
  • "prompt": Loaded from a prompt template .md file
  • "skill": Loaded from a skill directory (name is prefixed with skill:)
• location: Where it was loaded from (optional, not present for extensions):
  • "user": User-level (~/.atomic/agent/)
  • "project": Project-level (./.atomic/)
  • "path": Explicit path via CLI or settings
• path: Absolute file path to the command source (optional)

Note: Built-in TUI commands (/settings, /hotkeys, etc.) are not included. They are handled only in interactive mode and would not execute if sent via prompt.

Events

Events are streamed to stdout as JSON lines. Most events do not include an id; bash_execution_update is the deliberate exception and uses the originating bash request ID.

Event Types

Event	Description
agent_start	Agent begins processing
agent_end	Agent completes (includes all generated messages)
turn_start	New turn begins
turn_end	Turn completes (includes assistant message and tool results)
message_start	Message begins
message_update	Streaming update (text/thinking/toolcall deltas)
message_end	Message completes
tool_execution_start	Tool begins execution; includes toolCallId, toolName, and initial arguments
tool_execution_update	Tool execution progress (streaming output)
tool_execution_end	Tool completes
bash_execution_update	Correlated direct-bash stdout/stderr delta
queue_update	Pending steering/follow-up queue changed
compaction_start	Verbatim line compaction begins
compaction_end	Verbatim line compaction completes
auto_retry_start	Auto-retry begins (after transient error)
auto_retry_end	Auto-retry completes (success or final failure)
summarization_retry_scheduled	Retry scheduled for a transient compaction or branch-summary provider error
summarization_retry_attempt_start	Retried summarization request starts
summarization_retry_finished	Summarization retry loop completes
extension_error	Extension threw an error

agent_start

Emitted when the agent begins processing a prompt.

{"type": "agent_start"}

agent_end

Emitted when the agent completes. Contains all messages generated during this run.

{
  "type": "agent_end",
  "messages": [...]
}

turn_start / turn_end

A turn consists of one assistant response plus any resulting tool calls and results.

{"type": "turn_start"}

{
  "type": "turn_end",
  "message": {...},
  "toolResults": [...]
}

message_start / message_end

Emitted when a message begins and completes. The message field contains an AgentMessage.

{"type": "message_start", "message": {...}}
{"type": "message_end", "message": {...}}

message_update (Streaming)

Emitted during streaming of assistant messages. Carries the streaming delta plus the latest cumulative usage.

message_update has no cumulative message, and assistantMessageEvent has no partial. Build your message from message_start and deltas, then use message_end as the final authoritative message.

The top-level usage field carries the latest cumulative provider-reported usage; it may remain zero until completion when a provider does not report usage during streaming. When the provider reports an explicit end-of-turn signal (pi-ai's AssistantMessage.endTurn, for example OpenAI Codex end_turn), the update carries it as a top-level endTurn boolean — present only when the provider reported one.

{
  "type": "message_update",
  "usage": {
    "input": 100,
    "output": 1,
    "cacheRead": 0,
    "cacheWrite": 0,
    "totalTokens": 101,
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}
  },
  "assistantMessageEvent": {
    "type": "text_delta",
    "contentIndex": 0,
    "delta": "Hello "
  }
}

The assistantMessageEvent field contains one of these delta types:

Type	Description
start	Message generation started
text_start	Text content block started
text_delta	Text content chunk
text_end	Text content block ended
thinking_start	Thinking block started
thinking_delta	Thinking content chunk
thinking_end	Thinking block ended
toolcall_start	Tool call started
toolcall_delta	Tool call arguments chunk
toolcall_end	Tool call ended (includes full toolCall object)
done	Message complete (reason: "stop", "length", "toolUse")
error	Error occurred (reason: "aborted", "error")

Example streaming a text response:

{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}

tool_execution_start / tool_execution_update / tool_execution_end

Emitted when a tool begins, streams progress, and completes execution.

{
  "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):

{
  "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:

{
  "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.

bash_execution_update

Emitted only for direct bash and non-intercepted user_bash RPC execution. Each event is {type, id?, channel, delta} where channel is "stdout" or "stderr"; use id to keep concurrent streams separate. Tool-call bash continues to use tool_execution_update and its toolCallId.

queue_update

Emitted whenever the pending steering or follow-up queue changes.

{
  "type": "queue_update",
  "steering": ["Focus on error handling"],
  "followUp": ["After that, summarize the result"]
}

compaction_start / compaction_end

Emitted when default Verbatim Compaction runs, whether manual or automatic. The result records deletion targets and stats rather than a generated summary.

{"type": "compaction_start", "reason": "threshold"}

The reason field is "manual", "threshold", or "overflow".

{
  "type": "compaction_end",
  "reason": "threshold",
  "result": {
    "compactedText": "[User]: fix the test\n(filtered 42 lines)",
    "firstKeptEntryId": "m7",
    "tokensBefore": 150000,
    "promptVersion": 3,
    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the test"},
    "rung": "planned",
    "stats": {
      "linesBefore": 812,
      "linesDeleted": 417,
      "linesKept": 395,
      "rangeCount": 63,
      "tokensBefore": 150000,
      "tokensAfter": 72000,
      "percentReduction": 52
    }
  },
  "aborted": false,
  "willRetry": false
}

If reason was "overflow" and compaction succeeds, willRetry is true and the agent will automatically retry the prompt. Public prompt/RPC callers wait for that post-compaction continuation before the prompt is considered complete.

If compaction was aborted, result is null and aborted is true.

If compaction failed (e.g., API quota exceeded), result is null, aborted is false, and errorMessage contains the error description.

result and errorMessage are independent. A mid-turn post-tool compaction can commit a boundary and then fail the provider hard-input-limit gate, so one compaction_end may carry both a non-null result and an errorMessage. Treat the result as a committed durable boundary in that case; the error describes the follow-up request that was not sent.

If overflow recovery exhausts the same-model compact-and-retry attempt, compaction_end includes "unresolvedOverflow": true and an errorMessage. Workflow orchestration treats that signal as a context-length failure that can advance configured model fallback tiers.

There is no context_compact command; Atomic reports it as an unknown command. Use compact. Only compaction_start and compaction_end events are emitted.

auto_retry_start / auto_retry_end

Emitted when automatic retry is triggered after a transient error (overloaded, rate limit, 5xx).

{
  "type": "auto_retry_start",
  "attempt": 1,
  "maxAttempts": 3,
  "delayMs": 2000,
  "errorMessage": "529 {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}}"
}

{
  "type": "auto_retry_end",
  "success": true,
  "attempt": 2
}

On final failure (max retries exceeded):

{
  "type": "auto_retry_end",
  "success": false,
  "attempt": 3,
  "finalError": "529 overloaded_error: Overloaded"
}

summarization_retry_scheduled / summarization_retry_attempt_start / summarization_retry_finished

Emitted when compaction planning or branch summarization retries after a transient provider error. These events use the same retry settings as automatic assistant-turn retries.

{
  "type": "summarization_retry_scheduled",
  "attempt": 1,
  "maxAttempts": 3,
  "delayMs": 2000,
  "errorMessage": "terminated"
}

{
  "type": "summarization_retry_attempt_start",
  "source": "compaction",
  "reason": "threshold"
}

For branch summaries, source is "branchSummary" and no reason is present. The loop then emits:

{"type": "summarization_retry_finished"}

extension_error

Emitted when an extension throws an error.

{
  "type": "extension_error",
  "extensionPath": "/path/to/extension.ts",
  "event": "tool_call",
  "error": "Error message..."
}

Error Handling

Failed commands return a response with success: false:

{
  "type": "response",
  "command": "set_model",
  "success": false,
  "error": "Model not found: invalid/model"
}

Parse errors:

{
  "type": "response",
  "command": "parse",
  "success": false,
  "error": "Failed to parse command: Unexpected token..."
}

Types

Source files and installed definitions:

• node_modules/@bastani/pi-ai/dist/types.d.ts - Model, UserMessage, AssistantMessage, ToolResultMessage
• node_modules/@earendil-works/pi-agent-core/dist/types.d.ts - AgentMessage, AgentEvent
• src/core/messages.ts - BashExecutionMessage
• src/modes/rpc/rpc-types.ts - RPC command/response types, extension UI request/response types

Model

{
  "id": "claude-sonnet-4-20250514",
  "name": "Claude Sonnet 4",
  "api": "anthropic-messages",
  "provider": "anthropic",
  "baseUrl": "https://api.anthropic.com",
  "reasoning": true,
  "input": ["text", "image"],
  "contextWindow": 200000,
  "maxTokens": 16384,
  "cost": {
    "input": 3.0,
    "output": 15.0,
    "cacheRead": 0.3,
    "cacheWrite": 3.75
  }
}

contextWindow is the model's token budget used by Atomic's local budgeting, footer/stats, and compaction logic.

UserMessage

{
  "role": "user",
  "content": "Hello!",
  "timestamp": 1733234567890
}

The content field can be a string or an array of TextContent/ImageContent blocks.

AssistantMessage

{
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello! How can I help?"},
    {"type": "thinking", "thinking": "User is greeting me..."},
    {"type": "toolCall", "id": "call_123", "name": "bash", "arguments": {"command": "ls"}}
  ],
  "api": "anthropic-messages",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "input": 100,
    "output": 50,
    "cacheRead": 0,
    "cacheWrite": 0,
    "cost": {"input": 0.0003, "output": 0.00075, "cacheRead": 0, "cacheWrite": 0, "total": 0.00105}
  },
  "stopReason": "stop",
  "timestamp": 1733234567890
}

Stop reasons: "stop", "length", "toolUse", "error", "aborted". A streaming message carries "pending" until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it. On the wire the pending reason appears on the message_start message — message_update frames carry no message at all — and message_end carries the terminal reason. A provider that reports an explicit end-of-turn signal (pi-ai's AssistantMessage.endTurn, for example OpenAI Codex end_turn) sets endTurn: true on the assistant message; message_update frames echo it as a top-level boolean only when the provider reported one.

ToolResultMessage

{
  "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):

{
  "role": "bashExecution",
  "command": "ls -la",
  "output": "total 48\ndrwxr-xr-x ...",
  "exitCode": 0,
  "cancelled": false,
  "truncated": false,
  "fullOutputPath": null,
  "timestamp": 1733234567890
}

Attachment

{
  "id": "img1",
  "type": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 102400,
  "content": "base64-encoded-data...",
  "extractedText": null,
  "preview": null
}