apex-code 0.4.0 → 0.5.1

package/docs/how-pi-works.md

@@ -0,0 +1,49 @@
+# How Apex Code Works
+
+Apex Code coordinates model requests, tool execution, context assembly, and session storage. A session is Apex Code's record of a conversation, including messages, tool calls and results, model changes, compactions, and other events.
+
+Messages and events in a session form a tree. Each path through that tree is a branch. The branch ending at the current entry is the active branch and supplies the history for the next model request.
+
+## Agent loop
+
+A submitted message is added to the active branch. Apex Code builds a model request from the system prompt, active branch, available tools, and model settings, then sends it through the selected provider.
+
+The provider streams an assistant response, which can contain text and tool calls. Apex Code records the response, executes each tool call, and records the results. That completes one turn. If tool results or queued messages require another model request, Apex Code starts another turn. Otherwise, the run ends.
+
+Steering messages enter after the current assistant turn. Follow-up messages enter after the agent has finished its pending work. Aborting stops the current run and returns queued messages to the editor.
+
+## Context
+
+The active branch supplies conversation history. Apex Code converts its session entries into model-compatible user, assistant, and tool-result messages.
+
+Apex Code builds the system prompt from its base instructions and discovered context files. The request also carries tool definitions and skill descriptions.
+
+Full skill instructions are loaded on demand. Extensions can add instructions or transform context.
+
+Prompt templates expand editor input before it becomes a user message. Selected files, images, pasted text, and shell output can become message content.
+
+## Sessions
+
+Persistent sessions are JSONL files. Each tree entry has an ID and refers to its parent. The current entry identifies the active branch.
+
+Continuing from an earlier entry creates another branch in the same file. Forking and cloning copy selected history into a new session file.
+
+Model context is reconstructed from the active branch. Compaction inserts a summary entry that replaces older messages in subsequent model requests. The original entries remain in the session tree.
+
+## Interfaces
+
+Interactive mode renders session and agent events in the terminal. Print mode runs a prompt and writes the final response. JSON mode writes agent events as JSONL.
+
+RPC mode accepts JSONL commands on stdin and writes responses and events to stdout. The TypeScript SDK creates and controls agent sessions in process.
+
+All interfaces use the same agent and session mechanisms.
+
+## Extensions and resources
+
+Extensions are TypeScript modules loaded into the Apex Code process. Their factory functions register tools, commands, shortcuts, providers, event handlers, renderers, and terminal UI.
+
+Skills provide on-demand instructions and supporting files. Prompt templates provide reusable message text. Themes provide terminal colors. Apex Code packages distribute these resources through npm or git.
+
+## Trust and permissions
+
+Apex Code resolves project trust before loading project settings and resources. After the trust decision and project-resource loading, Apex Code loads context files. Enabled tools use the operating-system permissions of the Apex Code process. Extensions execute inside that process.

package/docs/index.md

@@ -2,7 +2,7 @@
 
 Apex Code is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and Apex Code packages.
 
-## Quick start
+Use Apex Code for software development, research notes, writing projects, data files, or hobby work. You can use Apex Code as is, prompt it to adapt itself to your workflow, or build other applications powered by Apex Code using the SDK.
 
 Install Apex Code with npm, pnpm, Yarn, or Bun — all resolve it from the same npm registry:
 
@@ -14,7 +14,7 @@ npm install -g --ignore-scripts apex-code
 
 To uninstall, use the package manager that installed it: `npm uninstall -g apex-code`, `pnpm remove -g apex-code`, `yarn global remove apex-code`, or `bun uninstall -g apex-code`.
 
-Then run it in a project directory:
+## Find reference and setup information
 
 ```bash
 apex-code
@@ -22,7 +22,7 @@ apex-code
 
 Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting Apex Code.
 
-For the full first-run flow, see [Quickstart](quickstart.md).
+## Work safely
 
 ## Start here
 

package/docs/json.md

@@ -1,4 +1,6 @@
-# JSON Event Stream Mode
+# JSON Event Stream
+
+JSON mode emits structured progress for one invocation:
 
 ```bash
 apex-code --mode json "Your prompt"
@@ -6,7 +8,7 @@ apex-code --mode json "Your prompt"
 
 Outputs all session events as JSON lines to stdout. Useful for integrating Apex Code into other tools or custom UIs.
 
-## Event Types
+This page is the canonical reference for events shared by JSON and RPC mode. Message values use the [shared message types](message-types.md).
 
 Wire events use `JsonAgentSessionEvent`. It matches
 [`AgentSessionEvent`](https://github.com/Fchery87/apex-code/blob/main/packages/coding-agent/src/core/agent-session.ts)
@@ -53,7 +55,7 @@ type AgentEvent =
 
 ## Message Types
 
-Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts#L134):
+Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi/blob/main/packages/ai/src/types.ts#L134):
 - `UserMessage` (line 134)
 - `AssistantMessage` (line 140)
 - `ToolResultMessage` (line 152)
@@ -93,6 +95,44 @@ fields. `message_end` contains the final authoritative message.
 
 ## Example
 
+Print completed messages from a one-shot run:
+
 ```bash
 apex-code --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
 ```
+
+## Result envelope and exit codes
+
+A `--mode json` run that reaches a normal terminal outcome ends with a `result` envelope.
+It is written by print mode rather than emitted by the session, so it is not an
+`AgentSessionEvent` and does not appear in `--mode text`. A run killed by `SIGTERM` or
+`SIGHUP` exits from the signal handler before the envelope is written, so a consumer
+treats a missing envelope as an incomplete run rather than as a success.
+
+```json
+{"type":"result","status":"completed"}
+```
+
+`status` is the run's terminal outcome, using the same vocabulary as the agent loop's
+`AgentStopReason`:
+
+| `status` | Meaning | Exit code |
+| --- | --- | --- |
+| `completed` | The run finished normally. | `0` |
+| `error` | The run failed, for example a provider error. | `1` |
+| `aborted` | The run was cancelled. | `1` |
+| `budget-exhausted` | A `runBudget` limit stopped the run. | `1` |
+
+Exit codes are `0` for `completed` and `1` for every other status. A caller that needs to
+distinguish the causes reads `status` rather than the exit code, so new statuses can be
+added without changing what an existing script sees. Signals are unchanged: `SIGTERM` exits
+`143` and `SIGHUP` exits `129`.
+
+Before this envelope existed, a failed `--mode json` run exited `0`, because the exit-code
+decision was reachable only from `--mode text`. Scripts written against that behavior treated
+every run as a success.
+
+```bash
+apex-code --mode json --permission-mode plan --print "Summarize the repository" \
+  | jq -r 'select(.type == "result") | .status'
+```

package/docs/keybindings.md

@@ -1,16 +1,35 @@
-# Keybindings
+# Keybindings Reference
 
 All keyboard shortcuts can be customized via `~/.apex-code/agent/keybindings.json`. Each action can be bound to one or more keys.
 
 The config file uses the same namespaced keybinding ids that Apex Code uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
 
-Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
+## Assign keybindings
 
 After editing `keybindings.json`, run `/reload` in Apex Code to apply the changes without restarting the session.
 
-## Key Format
+Map each action identifier to one key or a list of keys:
 
-`modifier+key` where modifiers are `ctrl`, `shift`, `alt`, `super` (combinable) and keys are:
+```json
+{
+  "app.session.new": "ctrl+shift+n",
+  "app.session.tree": ["ctrl+shift+t", "alt+shift+t"]
+}
+```
+
+A configured value replaces the default for that action. Use an empty list to disable an action's keybindings:
+
+```json
+{
+  "tui.altScreen.pageUp": []
+}
+```
+
+After editing the file, run `/reload` to apply the changes to the active session.
+
+## Key syntax
+
+Write a key as `modifier+key`. Modifiers are `ctrl`, `shift`, `alt`, and `super`. You can combine modifiers. Valid keys are:
 
 - **Letters:** `a-z`
 - **Digits:** `0-9`
@@ -18,20 +37,22 @@ After editing `keybindings.json`, run `/reload` in Apex Code to apply the change
 - **Function:** `f1`-`f12`
 - **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
 
-Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, `ctrl+1`, etc.
+Examples: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, and `ctrl+1`.
 
 `super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
 
-## All Actions
+## Actions
 
-### TUI Editor Cursor Movement
+### Terminal UI
+
+#### Cursor movement
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.editor.cursorUp` | `up` | Move cursor up, browsing older history at the top |
 | `tui.editor.cursorDown` | `down` | Move cursor down, browsing newer history at the bottom |
-| `tui.editor.historyPrevious` | *(none)* | Select the previous prompt history entry |
-| `tui.editor.historyNext` | *(none)* | Select the next prompt history entry |
+| `tui.editor.historyPrevious` | None | Select the previous prompt history entry |
+| `tui.editor.historyNext` | None | Select the next prompt history entry |
 | `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
 | `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
 | `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
@@ -43,39 +64,29 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+
 | `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
 | `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
 
-The dedicated history actions always change history entries, regardless of the cursor position in a multiline prompt. Explicit history bindings take precedence over application actions while the main editor is focused, so binding `tui.editor.historyPrevious` to `ctrl+p` overrides model cycling in that context without changing `Ctrl+P` in selectors.
+The dedicated history actions browse prompt history regardless of cursor position and take precedence over application actions using the same key.
 
-### TUI Editor Deletion
+#### Text editing
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
 | `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
 | `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
 | `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
 | `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
 | `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
-
-### TUI Input
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
-| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
-| `tui.input.submit` | `enter` | Submit input |
-| `tui.input.tab` | `tab` | Tab / autocomplete |
-
-### TUI Kill Ring
-
-| Keybinding id | Default | Description |
-|--------|---------|-------------|
 | `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
 | `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
 | `tui.editor.undo` | `ctrl+-` (`ctrl+z` on Windows; `alt+z` on WSL) | Undo last edit |
 
-### TUI Clipboard and Selection
+#### Input and selection
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
+| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab or autocomplete |
 | `tui.input.copy` | `ctrl+c` | Copy selection |
 | `tui.select.up` | `up` | Move selection up |
 | `tui.select.down` | `down` | Move selection down |
@@ -84,29 +95,18 @@ The dedicated history actions always change history entries, regardless of the c
 | `tui.select.confirm` | `enter` | Confirm selection |
 | `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
 
-### TUI Fullscreen Viewport
-
-These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content. See [Terminal setup](terminal-setup.md) for terminal-specific mouse and trackpad behavior.
+#### Fullscreen
 
-Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
-
-| Key | Default mode | Fullscreen mode |
-|-----|--------------|-----------------|
-| `home`, `end` | Editor | Transcript |
-| `ctrl+home`, `ctrl+end` | Editor | Editor |
-| `pageUp`, `pageDown` | Editor | Transcript |
-| `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
-
-This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for half-page steps, or bind `tui.altScreen.lineUp` and `tui.altScreen.lineDown` for single-line steps. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
+In fullscreen mode, these actions control the transcript and take precedence over editor actions using the same key.
 
 | Keybinding id | Default | Description |
-|--------|---------|-------------|
+|---|---|---|
 | `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
 | `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
-| `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
-| `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
-| `tui.altScreen.lineUp` | *(none)* | Scroll the transcript up by one line |
-| `tui.altScreen.lineDown` | *(none)* | Scroll the transcript down by one line |
+| `tui.altScreen.halfPageUp` | None | Scroll the transcript up by half a page |
+| `tui.altScreen.halfPageDown` | None | Scroll the transcript down by half a page |
+| `tui.altScreen.lineUp` | None | Scroll the transcript up by one line |
+| `tui.altScreen.lineDown` | None | Scroll the transcript down by one line |
 | `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` only on Windows and WSL) | Jump to the previous marked message |
 | `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` only on Windows and WSL) | Jump to the next marked message |
 | `tui.altScreen.search` | `ctrl+shift+f` (`ctrl+f` on Windows and WSL) | Search the rendered transcript |
@@ -123,18 +123,20 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.interrupt` | `escape` | Cancel / abort |
 | `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
-| `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
+| `app.suspend` | `ctrl+z` (None on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
 | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows and WSL) | Paste image or text from clipboard |
 
+On native Windows, `app.suspend` has no default because Windows terminals do not support Unix job control. If you assign it manually, Pi shows a status message instead of suspending. WSL uses the normal `ctrl+z` and `fg` behavior.
+
 ### Sessions
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `app.session.new` | *(none)* | Start a new session (`/new`) |
-| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
-| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
-| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
+| `app.session.new` | None | Start a new session (`/new`) |
+| `app.session.tree` | None | Open session tree navigator (`/tree`) |
+| `app.session.fork` | None | Fork current session (`/fork`) |
+| `app.session.resume` | None | Open session resume picker (`/resume`) |
 | `app.session.togglePath` | `ctrl+p` | Toggle path display |
 | `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
 | `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
@@ -149,15 +151,17 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.model.select` | `ctrl+l` | Open model selector |
 | `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
 | `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
+| `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
 | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
 | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
 
 ### Display and Message Queue
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
-| `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; otherwise copy the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| `app.tools.expand` | `ctrl+o` | Cycle conversation detail: overview (everything collapsed), details (diffs and thinking if enabled in settings), all (full tool output and thinking) |
+| `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; in fullscreen mode, copy the active selection when `fullscreenCopyOnSelect` is `false`; otherwise copy the last assistant message |
 | `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
 | `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |
 
@@ -183,7 +187,6 @@ Used inside the scoped models selector (opened via `/scoped-models`).
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
-| `app.models.save` | `ctrl+s` | Save current model selection to settings |
 | `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
 | `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
 | `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |

package/docs/llama-cpp.md

@@ -1,4 +1,4 @@
-# llama.cpp
+# Local Models with llama.cpp
 
 Apex Code supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
 
@@ -96,6 +96,6 @@ curl http://127.0.0.1:8080/models
 ```
 
 - **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
-- **Model missing from `/model`:** Load it with `/llama` first.
+- **Model missing from `/model` with `--no-models-autoload`:** Load it with `/llama` first.
 - **Load fails or uses too much memory:** Lower `-c` or unload another model.
 - **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.

package/docs/message-types.md

@@ -0,0 +1,261 @@
+# Message Types
+
+Apex Code uses `AgentMessage` values in SDK state, lifecycle events, RPC responses, and persisted session message entries. This page defines those shared messages and their content blocks.
+
+Message timestamps are Unix timestamps in milliseconds. They are different from the ISO 8601 timestamps on [session entries](session-format.md#entry-base).
+
+Source definitions:
+
+- [`packages/ai/src/types.ts`](https://github.com/Fchery87/apex-code/blob/main/packages/ai/src/types.ts) defines provider-facing messages and content blocks.
+- [`packages/agent/src/types.ts`](https://github.com/Fchery87/apex-code/blob/main/packages/agent/src/types.ts) defines the extensible `AgentMessage` union.
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/Fchery87/apex-code/blob/main/packages/coding-agent/src/core/messages.ts) adds coding-agent message roles.
+
+## Content blocks
+
+### TextContent
+
+```typescript
+interface TextContent {
+  type: "text";
+  text: string;
+  textSignature?: string;
+}
+```
+
+`textSignature` contains provider-specific message metadata. Treat it as opaque.
+
+### ImageContent
+
+```typescript
+interface ImageContent {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+```
+
+`data` is base64-encoded image data. `mimeType` identifies its media type, such as `image/png` or `image/jpeg`.
+
+### ThinkingContent
+
+```typescript
+interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+  thinkingSignature?: string;
+  redacted?: boolean;
+}
+```
+
+Thinking signatures contain provider-specific replay data. Treat them as opaque. A redacted block can have no visible thinking text while retaining an encrypted payload in `thinkingSignature`.
+
+### ToolCall
+
+```typescript
+interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+  thoughtSignature?: string;
+  namespace?: string;
+}
+```
+
+`thoughtSignature` is provider-specific. `namespace` identifies an OpenAI Responses namespace for dynamically loaded or namespaced tools.
+
+## Usage
+
+Assistant messages always contain usage. Tool results can contain usage when the tool performed nested model work.
+
+```typescript
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cacheWrite1h?: number;
+  reasoning?: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+```
+
+When present, `reasoning` is already included in `output`; do not add it again. `cacheWrite1h` is the subset of `cacheWrite` written with one-hour retention.
+
+## Base messages
+
+### SystemMessage
+
+```typescript
+interface SystemMessage {
+  role: "system";
+  content: string | TextContent[];
+  sections?: Record<string, string | null>;
+  toolsAdded?: Tool[];
+  toolsRemoved?: ToolReference[];
+  replace?: boolean;
+  timestamp: number;
+}
+```
+
+The leading system message declares the initial prompt and tools. Later system messages can append instructions, replace or remove named prompt sections, and add or remove tools. Replaying them in order yields the current state. A message with `replace: true` discards the earlier state and establishes a complete new baseline.
+
+### UserMessage
+
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;
+}
+```
+
+### AssistantMessage
+
+```typescript
+interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  responseModel?: string;
+  responseId?: string;
+  providerThinkingLevel?: string;
+  diagnostics?: AssistantMessageDiagnostic[];
+  usage: Usage;
+  stopReason: "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
+  deferred?: DeferredHandle;
+  errorMessage?: string;
+  rawStopReason?: string;
+  endTurn?: boolean;
+  timestamp: number;
+}
+```
+
+`responseModel` records a concrete provider response model when it differs from the requested model. `responseId`, `providerThinkingLevel`, `diagnostics`, and `rawStopReason` preserve provider or runtime details.
+
+`"pending"` is used for a partial assistant message while it streams. The completed message in `message_end` has a terminal stop reason, and Apex Code does not persist `"pending"` assistant messages in session JSONL.
+
+A `"deferred"` response has a `DeferredHandle` with the provider data needed to retrieve it:
+
+```typescript
+interface DeferredHandle {
+  provider: string;
+  modelId: string;
+  api: string;
+  id: string;
+  expiresAt?: number;
+  pollAfterMs?: number;
+  data?: JsonValue;
+}
+```
+
+### ToolResultMessage
+
+```typescript
+interface ToolResultMessage<TDetails = any> {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: TDetails;
+  usage?: Usage;
+  isError: boolean;
+  timestamp: number;
+}
+```
+
+`details` is tool-specific. Optional `usage` reports nested model work performed by the tool and contributes to full-session statistics, but it is not part of the main model-call usage.
+
+## Coding-agent messages
+
+The coding-agent package extends `AgentMessage` with four roles.
+
+### BashExecutionMessage
+
+Created by direct shell commands, including the RPC [`bash`](rpc-commands.md#bash) command. It is not an LLM tool result.
+
+```typescript
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  excludeFromContext?: boolean;
+  timestamp: number;
+}
+```
+
+Unless `excludeFromContext` is true, Apex Code converts this message to user-role text before the next model request.
+
+### CustomMessage
+
+Created when an extension sends a context message.
+
+```typescript
+interface CustomMessage<T = unknown> {
+  role: "custom";
+  customType: string;
+  content: string | (TextContent | ImageContent)[];
+  display: boolean;
+  details?: T;
+  timestamp: number;
+}
+```
+
+Apex Code converts its content to a user message for model requests. `display` controls terminal rendering; `details` is not sent to the model.
+
+### BranchSummaryMessage
+
+```typescript
+interface BranchSummaryMessage {
+  role: "branchSummary";
+  summary: string;
+  fromId: string | null;
+  timestamp: number;
+}
+```
+
+Apex Code creates this context message from a persisted `branch_summary` entry.
+
+### CompactionSummaryMessage
+
+```typescript
+interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+```
+
+Apex Code creates this context message from a persisted `compaction` entry.
+
+## AgentMessage union
+
+In the coding agent, the union is equivalent to:
+
+```typescript
+type AgentMessage =
+  | SystemMessage
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CustomMessage
+  | BranchSummaryMessage
+  | CompactionSummaryMessage;
+```
+
+At the lower-level agent package, `AgentMessage` is `Message | CustomAgentMessages[keyof CustomAgentMessages]`. Applications can add roles through TypeScript declaration merging, so consumers should tolerate unknown custom roles when they accept messages from an augmented host.