@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/docs/security.md

@@ -0,0 +1,139 @@
+# Security
+
+Volt is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
+
+## Project Trust
+
+Project trust controls whether volt loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
+
+Volt considers a project to have resources that require trust when it finds any of these from the current working directory:
+
+- `.volt/settings.json`
+- `.mcp.json` or `.volt/mcp.json`
+- `.volt/extensions`, `.volt/skills`, `.volt/prompts`, or `.volt/themes`
+- `.volt/SYSTEM.md` or `.volt/APPEND_SYSTEM.md`
+- project `.agents/skills` in the current directory or an ancestor directory
+
+A bare `.volt` directory does not count as a project resource that requires trust.
+
+When an interactive session starts in a project with resources that require trust and no saved decision for the current directory or a parent directory, volt follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.volt/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
+
+Trusting a project allows volt to load project resources that require trust, including:
+
+- `.volt/settings.json`
+- project MCP server config in `.mcp.json` or `.volt/mcp.json`
+- `.volt` resources such as extensions, skills, prompt templates, themes, and system prompt files
+- missing project packages configured through project settings
+- project-local extensions and project package-managed extensions
+
+Declining trust skips protected resources. `AGENTS.md` and `CLAUDE.md` context files are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, volt only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+## No Built-in Sandbox
+
+Volt does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the volt process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
+
+This is intentional. Volt is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
+
+Project trust is only an input-loading guard. It prevents a repository from silently changing volt's settings, MCP servers, or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by volt.
+
+## Standalone Release Integrity
+
+Prebuilt Volt executables are Node.js 22.23.1 Single Executable Applications.
+Release builds verify a pinned official Node runtime archive, bundle Volt's
+JavaScript, and generate an exact esbuild metafile plus a checksum-linked npm
+license manifest. Each archive includes Volt's license, the consolidated Node
+license and third-party notices, and the copied license files recorded by that
+manifest. Verify the downloaded archive against the release `SHA256SUMS` before
+running it.
+
+Standalone builds intentionally exclude the native Iroh adapter and the
+source-repository Doom overlay example. The official Linux runtime requires
+glibc 2.28 or newer and does not support Alpine/musl. Windows beta executables
+are not Authenticode-signed, so Windows may show an unknown-publisher warning;
+the published SHA-256 checksum is the release authenticity check. macOS
+executables are ad-hoc signed after SEA injection, not Developer ID notarized.
+See [Standalone Binary Capabilities](../BINARY-CAPABILITIES.md) and
+[Third-Party Notices](../THIRD-PARTY-NOTICES.md).
+
+## MCP Servers
+
+Native MCP support can spawn local stdio server commands or connect to configured HTTP/SSE endpoints. User MCP config lives in `~/.volt/agent/mcp.json` and shared `~/.config/mcp/mcp.json`; project `.mcp.json` and `.volt/mcp.json` are loaded only after project trust. Project definitions with the same server id replace, rather than inherit, user-scope definitions so project endpoints cannot reuse user auth/env config by id collision.
+
+MCP server metadata and output are untrusted. Volt exposes MCP through one `mcp` gateway tool, uses risk classification only as display/audit metadata, redacts obvious secrets in audit arguments/errors, and stores audit records under `~/.volt/agent/mcp/audit.jsonl`. Runtime availability is controlled by the top-level `mcp` tool, server include/exclude filters, project trust, auth, and transport/remote-safety rules. Large outputs may be cached under `~/.volt/agent/mcp/output/` and are scoped to the creating session/workspace when Volt constructs the default MCP manager.
+
+Avoid putting long-lived secrets in project MCP config. Auth headers and OAuth-protected remote MCP servers are rejected over non-HTTPS URLs except loopback HTTP. OAuth authorization/token/device/registration endpoints must use HTTPS; browser auth uses PKCE S256 and a loopback callback, and device auth exposes only the verification URL and user code (never the OAuth device code). OAuth tokens are stored host-side in `~/.volt/agent/mcp-auth.json` with owner-only permissions and are never sent to the model or mobile client.
+
+Stdio server environments start from the MCP SDK default safe environment plus explicit `envAllowlist` and configured `env` templates.
+
+## Running Untrusted or Unmonitored Work
+
+For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run volt in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
+
+Common patterns are documented in [Containerization](containerization.md):
+
+- run the whole `volt` process inside OpenShell or Docker
+- run host volt while routing built-in tool execution into a Gondolin micro-VM
+- mount only the workspace paths the agent should access
+- avoid mounting host `~/.volt/agent` unless the container should access host sessions, settings, and credentials
+- pass the minimum required API keys or use short-lived credentials
+- restrict network access when the task does not need it
+- review diffs and outputs before copying results back to trusted systems
+
+If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
+
+## Remote Access over Iroh (Preview)
+
+Remote access is served by the background daemon (`voltd`, see [Background daemon](daemon.md)) and is opt-in. Treat a paired remote client as a user who can operate Volt inside the exposed workspace with the tools granted by the host — pairing a phone grants it desktop-equivalent power over any conversation a desktop TUI shares with it.
+
+Supported preview safety model:
+
+- Nothing listens until the host user starts the daemon (`volt daemon start` or `remote.background: true`). The daemon listens only on its local unix control socket (mode `0600`) and the Iroh endpoint.
+- Workspaces are registered locally by the desktop user with saved names; clients cannot request arbitrary host paths.
+- Registering a workspace is a local desktop action. Remote clients cannot create, rename, delete files, browse host paths, or path-map host workspaces from the app. A reviewed remote unregister request may remove an empty known workspace name from host state only; it does not delete files. Persisted child worktrees make unregister fail with `workspace_has_worktrees`, preserving their records and checkouts until the user explicitly removes each worktree. Unknown/orphan worktree directories are never unregister cleanup targets.
+- The default headless agent tool grant includes the built-in coding tools `read,bash,edit,write,grep,find,ls,subagent` plus active tools registered by loaded extensions. A custom `remote.allowTools` list is strict and applies ONLY to daemon-owned headless runtimes; extension tools must be named explicitly there. The `subagent` tool only starts built-in or discovered named definitions, and child tools are clamped by the remote session's active tool grant.
+- **Tool policy asymmetry (explicit decision).** When a desktop TUI owns the conversation lease, phone prompts execute with the TUI session's FULL local tool set — the phone is the same paired user driving the same conversation, and splitting tool policy mid-conversation creates confusing, falsely-reassuring states. This supersedes `remote.allowTools` for co-attached conversations. Corollary: pairing a phone grants it desktop-equivalent power over any TUI-open conversation.
+- Pairing tickets are short-lived, one-time credentials. Persisted state stores secret hashes and non-secret metadata, not raw pairing secrets.
+- Pairing through `volt remote pair` talks to the running daemon; offline ticket generation from persisted state is not supported.
+- Daemon startup never creates an active pairing ticket. Add phones explicitly with `volt remote pair`.
+- Paired clients are persisted until revoked with `volt remote revoke <node-id>`.
+- After pairing, saved-host reconnect uses the persisted client node ID and a secret-free client saved-host record. Ordinary app reconnect, temporary network loss, or daemon restart should not require scanning another QR (the daemon owns a persistent Iroh identity).
+- Pairing is workstation-scoped for the daemon's state file. A paired phone can reconnect to any registered workspace name, including workspaces registered after pairing, without another QR scan. The app receives and selects names and host feature strings only, never host-local paths.
+- Integrated hosts advertise `multi_streams.v1` and `conversation_streams.v1`. Mobile conversation streams bind at handshake time to one authorized workspace/session target, and the host-observed Iroh client node ID is authoritative for authorization, runtime ownership, revocation, audit, and Live Activity routing.
+- Same-client duplicates for one workspace/session on one live Iroh connection are rejected with `duplicate_conversation_connection`. The first conversation stream on a new same-client connection can replace a stale active stream for the same workspace/session and reattach to the retained runtime. Different sessions in the same registered workspace may run concurrently.
+- Distinct paired devices normally co-attach to one shared conversation runtime (or to a TUI-owned conversation over the daemon's byte relay). `conversation_in_use` is reserved for the narrow case where that existing daemon runtime permits tools outside the attaching client's persisted grant; the client cannot safely drive the broader runtime. Audit records (`~/.volt/agent/daemon/audit.jsonl`) cover pairing, lease transfers, and relay lifecycle so "what did the phone do while I was away" is reviewable after the fact.
+- Mobile conversation streams cannot be retargeted after handshake. Command-level workspace/session fields are assertions only and mismatches fail with `session_mismatch`. Direct `new_session`, `switch_session_by_id`, and raw `get_messages` are rejected on mobile conversation streams.
+- Workspace discovery streams accept only remote-safe `list_sessions` and do not create or update runtime state. Workspace management streams accept only authorized `unregister_workspace`.
+- Hosts that do not advertise `conversation_streams.v1` are incompatible with the mobile pinned-agent model. The app should keep the saved host and show an update/integrated-host-required state instead of asking for a QR scan or using old mutation commands.
+- Registering another workspace does not grant more built-in tools. For daemon-owned runtimes, the effective tool policy is the intersection of the client's persisted `allowedTools` grant, any workspace ceiling, and the daemon's `remote.allowTools` ceiling; missing ceilings add no restriction and an explicit empty daemon ceiling denies all tools. The client grant remains the maximum authority across every registered workspace until the client is revoked and paired again with a different grant. When every active policy layer has default-grant semantics, active extension tools in the selected workspace are also exposed.
+- Revocation removes future access from persisted state and asks a live host to close matching active streams, connections, integrated runtimes, and stream-bound Live Activity registrations when one is reachable. A revoked phone is blocked from every registered workspace in that state file.
+- A revoked phone node ID cannot reconnect or re-pair with only a generic new QR. The desktop host must approve that node with `volt remote approve-repair <node-id>`, then issue a fresh active pairing ticket.
+- In the default integrated runtime, Iroh stream close is detach, not cancellation. Closing one conversation stream does not close or abort other active conversation streams for the same phone. Active work can continue on the host until it finishes or an authorized client sends `abort` on the selected bound stream.
+- Detached integrated runtimes can be reattached only by the same authoritative Iroh client node ID, workspace, and session, and idle detached runtimes expire by the host retention policy.
+- `volt remote status` and `volt remote clients` report the daemon's workspaces, clients, leases, and redacted metadata without printing secrets or secret hashes.
+- State and audit JSONL are stored under `~/.volt/agent/daemon/` (`state.json` mode `0600` — it contains the Iroh secret key — and `audit.jsonl`).
+
+Unsafe remote tools are powerful. Granting `bash`, `edit`, or `write` lets the remote session modify files or run shell commands on the host. Extension tools run code installed on the host and may do the same; expose them only when those extensions, the client device, and the network path are trusted.
+
+Remote sessions do not bypass project trust. Project-local settings, extensions, skills, prompt templates, themes, system prompts, and package-managed resources follow the same project trust rules as local Volt. A saved trust decision for the workspace is honored; otherwise the daemon runs those resources untrusted. Save trust from a desktop Volt session in that workspace.
+
+The daemon requires a Node.js npm package install or source checkout with optional `@number0/iroh` available for the platform. Standalone Node SEA builds reject `volt daemon` because the native Iroh adapter is intentionally not bundled. If startup reports that the optional native adapter is unavailable, reinstall with optional dependencies enabled for the current platform.
+
+Daemon exit, crash, or explicit shutdown stops in-memory work; remote access does not provide durable job recovery beyond persisted session state.
+
+Push notification delivery is mediated by the managed Volt relay by default. The mobile app registers its FCM token with the relay, then sends the desktop host only an opaque relay target id plus a target-scoped delivery credential. Volt host state stores that relay credential and optional token hash, but not the raw FCM registration token. Custom relays can be selected with `VOLT_PUSH_RELAY_URL`; if a custom relay uses shared bearer auth, pass it with `VOLT_PUSH_RELAY_AUTH_TOKEN`. Push registration keeps working after a TUI takes over a conversation: relayed registrations are forwarded to the daemon, which preserves the register-push-target-before-live-activity ordering per client.
+
+Live Activity delivery is stream-bound. When an ActivityKit push token is available, the app sends it to the host inside `register_push_target.args.liveActivity` with the activity ID, token environment, and lowercase SHA-256 hash. The later `register_live_activity` command sends workspace name, session ID, activity ID, platform, token environment, and the same hash without repeating the raw token. The host resolves that hash against the existing delivery channel and drops matching registrations on explicit unregister, selected-stream abort success, replacement, revocation, workspace unregister or authorization removal, and retained-runtime disposal.
+
+The daemon uses the default Iroh relay mode so saved-host reconnects can survive restarts. Use `volt remote pair` to create pairing tickets.
+
+Client UX should treat offline, authorization, workspace, and conversation failures differently. `host_unreachable` keeps the saved host and retries later. `host_identity_mismatch`, `saved_host_invalid`, `client_unknown`, and `client_revoked` require explicit user action such as Pair Again or Forget Host. `workspace_unavailable`, `workspace_unregistered`, `workspace_has_worktrees`, `workspace_authorization_removed`, `workspace_forbidden`, `session_unavailable`, `duplicate_conversation_connection`, and `conversation_streams_unsupported` are host capability, workspace, or conversation-selection problems, not reasons to discard the saved host by default. `workspace_has_worktrees` requires explicit worktree review/removal before retrying unregister. `lease_transferred` and `session_rekeyed_reconnect` closures are expected handoffs the app reconnects through silently.
+
+See [Using Volt](usage.md#remote-access-over-iroh-preview) for copy-pastable commands and [Iroh remote protocol v1](iroh-remote-protocol.md) for the external client contract.
+
+## Reporting Security Issues
+
+To report a security issue, follow the repository [Security Policy](../../../SECURITY.md). Do not open a public issue for security-sensitive reports.
+
+Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how volt grants access that the local user did not already have.

package/docs/session-format.md

@@ -0,0 +1,412 @@
+# Session File Format
+
+Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with a `type` field. Session entries form a tree structure via `id`/`parentId` fields, enabling in-place branching without creating new files.
+
+## File Location
+
+```
+~/.volt/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+```
+
+Where `<path>` is the working directory with `/` replaced by `-`.
+
+## Deleting Sessions
+
+Sessions can be removed by deleting their `.jsonl` files under `~/.volt/agent/sessions/`.
+
+Volt also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, volt uses the `trash` CLI to avoid permanent deletion.
+
+## Session Version
+
+Sessions have a version field in the header:
+
+- **Version 1**: Linear entry sequence (legacy, auto-migrated on load)
+- **Version 2**: Tree structure with `id`/`parentId` linking
+- **Version 3**: Renamed `hookMessage` role to `custom` (extensions unification)
+
+Existing sessions are automatically migrated to the current version (v3) when loaded.
+
+## Source Files
+
+Source files:
+- [`packages/coding-agent/src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/coding-agent/src/core/messages.ts`](../src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
+- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - AgentMessage union type
+
+For TypeScript definitions in your project, inspect `node_modules/@hansjm10/volt-coding-agent/dist/` and `node_modules/@hansjm10/volt-ai/dist/`.
+
+## Message Types
+
+Session entries contain `AgentMessage` objects. Understanding these types is essential for parsing sessions and writing extensions.
+
+### Content Blocks
+
+Messages contain arrays of typed content blocks:
+
+```typescript
+interface TextContent {
+  type: "text";
+  text: string;
+}
+
+interface ImageContent {
+  type: "image";
+  data: string;      // base64 encoded
+  mimeType: string;  // e.g., "image/jpeg", "image/png"
+}
+
+interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+}
+
+interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+}
+```
+
+### Base Message Types (from volt-ai)
+
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;  // Unix ms
+}
+
+interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  usage: Usage;
+  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+  errorMessage?: string;
+  timestamp: number;
+}
+
+interface ToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: any;      // Tool-specific metadata
+  isError: boolean;
+  timestamp: number;
+}
+
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+```
+
+### Extended Message Types (from volt-coding-agent)
+
+```typescript
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  excludeFromContext?: boolean;  // true for !! prefix commands
+  timestamp: number;
+}
+
+interface CustomMessage {
+  role: "custom";
+  customType: string;            // Extension identifier
+  content: string | (TextContent | ImageContent)[];
+  display: boolean;              // Show in TUI
+  details?: any;                 // Extension-specific metadata
+  timestamp: number;
+}
+
+interface BranchSummaryMessage {
+  role: "branchSummary";
+  summary: string;
+  fromId: string;                // Entry we branched from
+  timestamp: number;
+}
+
+interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+```
+
+### AgentMessage Union
+
+```typescript
+type AgentMessage =
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CustomMessage
+  | BranchSummaryMessage
+  | CompactionSummaryMessage;
+```
+
+## Entry Base
+
+All entries (except `SessionHeader`) extend `SessionEntryBase`:
+
+```typescript
+interface SessionEntryBase {
+  type: string;
+  id: string;           // 8-char hex ID
+  parentId: string | null;  // Parent entry ID (null for first entry)
+  timestamp: string;    // ISO timestamp
+}
+```
+
+## Entry Types
+
+### SessionHeader
+
+First line of the file. Metadata only, not part of the tree (no `id`/`parentId`).
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
+```
+
+For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ parentSession })`):
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
+```
+
+### SessionMessageEntry
+
+A message in the conversation. The `message` field contains an `AgentMessage`.
+
+```json
+{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}
+{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}}
+{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2024-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"call_123","toolName":"bash","content":[{"type":"text","text":"output"}],"isError":false}}
+```
+
+### ModelChangeEntry
+
+Emitted when the user switches models mid-session.
+
+```json
+{"type":"model_change","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:05:00.000Z","provider":"openai","modelId":"gpt-4o"}
+```
+
+### ThinkingLevelChangeEntry
+
+Emitted when the user changes the thinking/reasoning level.
+
+```json
+{"type":"thinking_level_change","id":"e5f6g7h8","parentId":"d4e5f6g7","timestamp":"2024-12-03T14:06:00.000Z","thinkingLevel":"high"}
+```
+
+### CompactionEntry
+
+Created when context is compacted. Stores a summary of earlier messages.
+
+```json
+{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
+```
+
+Optional fields:
+- `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if volt-generated (legacy field name)
+
+### BranchSummaryEntry
+
+Created when switching branches via `/tree` with an LLM generated summary of the left branch up to the common ancestor. Captures context from the abandoned path.
+
+```json
+{"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:15:00.000Z","fromId":"f6g7h8i9","summary":"Branch explored approach A..."}
+```
+
+Optional fields:
+- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if volt-generated (legacy field name)
+
+### CustomEntry
+
+Extension state persistence. Does NOT participate in LLM context.
+
+```json
+{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
+```
+
+Use `customType` to identify your extension's entries on reload.
+
+### CustomMessageEntry
+
+Extension-injected messages that DO participate in LLM context.
+
+```json
+{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-extension","content":"Injected context...","display":true}
+```
+
+Fields:
+- `content`: String or `(TextContent | ImageContent)[]` (same as UserMessage)
+- `display`: `true` = show in TUI with distinct styling, `false` = hidden
+- `details`: Optional extension-specific metadata (not sent to LLM)
+
+### LabelEntry
+
+User-defined bookmark/marker on an entry.
+
+```json
+{"type":"label","id":"j0k1l2m3","parentId":"i9j0k1l2","timestamp":"2024-12-03T14:30:00.000Z","targetId":"a1b2c3d4","label":"checkpoint-1"}
+```
+
+Set `label` to `undefined` to clear a label.
+
+### SessionInfoEntry
+
+Session metadata (e.g., user-defined display name). Set via `/name`, `--name` / `-n`, or `volt.setSessionName()` in extensions.
+
+```json
+{"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
+```
+
+The session name is displayed in the session selector (`/resume`) instead of the first message when set.
+
+## Tree Structure
+
+Entries form a tree:
+- First entry has `parentId: null`
+- Each subsequent entry points to its parent via `parentId`
+- Branching creates new children from an earlier entry
+- The "leaf" is the current position in the tree
+
+```
+[user msg] ─── [assistant] ─── [user msg] ─── [assistant] ─┬─ [user msg] ← current leaf
+                                                            │
+                                                            └─ [branch_summary] ─── [user msg] ← alternate branch
+```
+
+## Context Building
+
+`buildSessionContext()` walks from the current leaf to the root, producing the message list for the LLM:
+
+1. Collects all entries on the path
+2. Extracts current model and thinking level settings
+3. If a `CompactionEntry` is on the path:
+   - Emits the summary first
+   - Then messages from `firstKeptEntryId` to compaction
+   - Then messages after compaction
+4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
+
+## Parsing Example
+
+```typescript
+import { readFileSync } from "fs";
+
+const lines = readFileSync("session.jsonl", "utf8").trim().split("\n");
+
+for (const line of lines) {
+  const entry = JSON.parse(line);
+
+  switch (entry.type) {
+    case "session":
+      console.log(`Session v${entry.version ?? 1}: ${entry.id}`);
+      break;
+    case "message":
+      console.log(`[${entry.id}] ${entry.message.role}: ${JSON.stringify(entry.message.content)}`);
+      break;
+    case "compaction":
+      console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
+      break;
+    case "branch_summary":
+      console.log(`[${entry.id}] Branch from ${entry.fromId}`);
+      break;
+    case "custom":
+      console.log(`[${entry.id}] Custom (${entry.customType}): ${JSON.stringify(entry.data)}`);
+      break;
+    case "custom_message":
+      console.log(`[${entry.id}] Extension message (${entry.customType}): ${entry.content}`);
+      break;
+    case "label":
+      console.log(`[${entry.id}] Label "${entry.label}" on ${entry.targetId}`);
+      break;
+    case "model_change":
+      console.log(`[${entry.id}] Model: ${entry.provider}/${entry.modelId}`);
+      break;
+    case "thinking_level_change":
+      console.log(`[${entry.id}] Thinking: ${entry.thinkingLevel}`);
+      break;
+  }
+}
+```
+
+## SessionManager API
+
+Key methods for working with sessions programmatically.
+
+### Static Creation Methods
+- `SessionManager.create(cwd, sessionDir?)` - New session
+- `SessionManager.open(path, sessionDir?)` - Open existing session file
+- `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
+- `SessionManager.inMemory(cwd?)` - No file persistence
+- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
+
+### Static Listing Methods
+- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
+- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
+
+### Instance Methods - Session Management
+- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `setSessionFile(path)` - Switch to a different session file
+- `createBranchedSession(leafId)` - Extract branch to new session file
+
+### Instance Methods - Appending (all return entry ID)
+- `appendMessage(message)` - Add message
+- `appendThinkingLevelChange(level)` - Record thinking change
+- `appendModelChange(provider, modelId)` - Record model change
+- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
+- `appendCustomEntry(customType, data?)` - Extension state (not in context)
+- `appendSessionInfo(name)` - Set session display name
+- `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
+- `appendLabelChange(targetId, label)` - Set/clear label
+
+### Instance Methods - Tree Navigation
+- `getLeafId()` - Current position
+- `getLeafEntry()` - Get current leaf entry
+- `getEntry(id)` - Get entry by ID
+- `getBranch(fromId?)` - Walk from entry to root
+- `getTree()` - Get full tree structure
+- `getChildren(parentId)` - Get direct children
+- `getLabel(id)` - Get label for entry
+- `branch(entryId)` - Move leaf to earlier entry
+- `resetLeaf()` - Reset leaf to null (before any entries)
+- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
+
+### Instance Methods - Context & Info
+- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
+- `getEntries()` - All entries (excluding header)
+- `getHeader()` - Session header metadata
+- `getSessionName()` - Get display name from latest session_info entry
+- `getCwd()` - Working directory
+- `getSessionDir()` - Session storage directory
+- `getSessionId()` - Session UUID
+- `getSessionFile()` - Session file path (undefined for in-memory)
+- `isPersisted()` - Whether session is saved to disk