zidane 5.2.1 → 5.3.0

package/dist/types-IcokUOyC.js.map

@@ -1 +1 @@
-{"version":3,"file":"types-IcokUOyC.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/**\n * Shared types for the agent system.\n */\n\nimport type { ToolDef } from './tools/types'\nimport { Buffer } from 'node:buffer'\n\n// ---------------------------------------------------------------------------\n// Thinking / Reasoning\n// ---------------------------------------------------------------------------\n\n/**\n * Thinking / extended-reasoning configuration.\n *\n * - `'off'` — no thinking.\n * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to\n *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`\n *   with a budget; OpenAI `reasoning_effort`).\n * - `'adaptive'` — let the model decide per-turn whether and how much to think.\n *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to\n *   no reasoning when this value is supplied.\n */\nexport type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive'\n\n// ---------------------------------------------------------------------------\n// MCP server configuration\n// ---------------------------------------------------------------------------\n\n/**\n * Slim shape of an upstream MCP tool descriptor — what `client.listTools()`\n * returns per entry. Exposed publicly so hosts can persist the schemas\n * between runs and feed them back via {@link McpServerConfig.cachedTools}\n * to skip the `tools/list` round-trip on subsequent bootstraps.\n */\nexport interface McpToolSchema {\n  name: string\n  description?: string | null\n  inputSchema?: unknown\n}\n\nexport interface McpServerConfig {\n  /** Display name (used for tool namespacing) */\n  name: string\n  /** Transport type */\n  transport: 'stdio' | 'sse' | 'streamable-http'\n  /** For stdio: command to run */\n  command?: string\n  /** For stdio: command arguments */\n  args?: string[]\n  /**\n   * For stdio: environment variables to pass to the server process.\n   *\n   * Merged on top of the MCP SDK's default inherited environment — a safety\n   * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,\n   * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from\n   * the child process. Set {@link McpServerConfig.strictEnv} to `true` to\n   * pass `env` verbatim with no inherited defaults.\n   */\n  env?: Record<string, string>\n  /**\n   * When true, {@link McpServerConfig.env} is passed verbatim to the spawned\n   * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)\n   * is NOT merged in. Most consumers should leave this off; the default merge\n   * prevents `spawn ENOENT` when a stdio server declares an `env` without\n   * restating `PATH`.\n   */\n  strictEnv?: boolean\n  /** For sse/streamable-http: server URL */\n  url?: string\n  /** Optional headers for HTTP transports */\n  headers?: Record<string, string>\n  /**\n   * OAuth 2.1 authentication (sse / streamable-http only).\n   *\n   * - `'oauth'` — enables the SDK's OAuth flow with RFC 9728 protected-resource\n   *   metadata discovery, RFC 8414 / OIDC authorization-server metadata, RFC 7591\n   *   dynamic client registration, PKCE, and refresh-token rotation. Tokens persist\n   *   between runs via the host's credential store.\n   * - `undefined` (default) — no OAuth. The host may still auto-promote a server\n   *   to OAuth on `UnauthorizedError` IF no static `Authorization` header is set\n   *   (the headers check stops us from second-guessing user-managed bearer tokens).\n   *\n   * Recognized aliases at parse time: Cursor's `authMethod: 'mcpOAuth'` maps to\n   * `auth: 'oauth'` so `~/.cursor/mcp.json` pastes work unchanged.\n   */\n  auth?: 'oauth'\n  /**\n   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).\n   *\n   * Zidane connects MCP servers lazily on the first `run()`. Without a\n   * bootstrap timeout, a slow or hung server can delay the first provider call\n   * for an arbitrarily long time even when that MCP server is never used.\n   *\n   * Default: `10000`.\n   */\n  bootstrapTimeout?: number\n  /** Timeout in milliseconds for MCP tool calls (default: 30000) */\n  toolTimeout?: number\n  /**\n   * Allow-list of tool names to expose. Names match the upstream tool name\n   * (NOT the namespaced `mcp_{server}_{tool}` form). Tools not in the list are\n   * dropped before registration — the model never sees them in its catalog and\n   * the wire cost of advertising them is avoided.\n   *\n   * Mutually exclusive with {@link McpServerConfig.disabledTools} — passing both\n   * throws at bootstrap time.\n   *\n   * Composes with {@link McpServerConfig.toolFilter}: allow-list applies first,\n   * then the predicate. Composes with the `mcp:tools:filter` hook: config-side\n   * filters apply first, then the hook can further narrow the list.\n   */\n  enabledTools?: string[]\n  /**\n   * Deny-list of tool names. Tools matching are dropped before registration.\n   * Same matching semantics as {@link McpServerConfig.enabledTools}.\n   */\n  disabledTools?: string[]\n  /**\n   * Custom predicate run on each upstream tool. Return `true` to keep, `false`\n   * to drop. Receives the raw `listTools()` payload — useful for filtering by\n   * description, schema shape, or other metadata that an allow/deny list can't\n   * express.\n   *\n   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.\n   */\n  toolFilter?: (tool: { name: string, description?: string | null, inputSchema?: unknown }) => boolean\n  /**\n   * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,\n   * this server's tools follow this disclosure mode regardless of the\n   * agent-wide default. Useful when one big MCP server (200+ tools) should\n   * stay lazy while smaller servers stay eager.\n   *\n   * Default: inherits from `behavior.toolDisclosure`.\n   */\n  disclosure?: 'eager' | 'lazy'\n  /**\n   * Pre-cached tool schemas to advertise without issuing `tools/list` at\n   * bootstrap. The connection is still established (the SDK's `connect()`\n   * is needed for `tools/call`) — only the discovery round-trip is\n   * skipped. Schemas are trusted as-is; the host owns invalidation\n   * (typical cache key: `(server identity, server version)`). If the\n   * server later returns `MethodNotFound` for a cached tool, the host\n   * should drop the entry from its cache so the next bootstrap re-lists.\n   *\n   * Compatible with every transport, every auth mode, and with\n   * {@link McpServerConfig.lazyConnect}. Composes with the existing\n   * `enabledTools` / `disabledTools` / `toolFilter` filters — those run\n   * over the cached schemas exactly as they would over `listTools()`\n   * output.\n   */\n  cachedTools?: McpToolSchema[]\n  /**\n   * Defer the `client.connect(transport)` call until the first\n   * `tools/call` reaches this server. Bootstrap registers the server's\n   * tools using {@link McpServerConfig.cachedTools} without touching\n   * the network, taking MCP setup off the critical path of\n   * `agent.run()`. The first invocation pays the connect cost\n   * (~200-500ms typically); every subsequent call reuses the live\n   * client.\n   *\n   * Requires {@link McpServerConfig.cachedTools} — without schemas in\n   * hand there is nothing to advertise to the model, so deferring the\n   * connection has no purpose. Bootstrap rejects the config otherwise.\n   *\n   * **Incompatible with `auth: 'oauth'`**: the OAuth handshake (token\n   * refresh / RFC 9728 metadata discovery) can fail in ways that today\n   * fire `mcp:auth:required` at bootstrap so the host can surface a\n   * login affordance *before* the model commits to calling a tool.\n   * Deferring that to first call means an auth failure surfaces mid-run\n   * as a tool-result error, which the model can't recover from without\n   * a fresh prompt. Bootstrap rejects the combination so the error is\n   * loud and proximate to the misconfiguration. Use OAuth servers\n   * without `lazyConnect` (with `cachedTools` alone, if you want to\n   * skip the `tools/list` round-trip).\n   *\n   * On connect failure (network error, transport refused), the cached\n   * promise is dropped so the next `tools/call` retries. The model\n   * sees the failure as a normal tool error. Subsequent calls remain\n   * eligible to succeed once the upstream is reachable again.\n   */\n  lazyConnect?: boolean\n}\n\n// ---------------------------------------------------------------------------\n// Tool execution\n// ---------------------------------------------------------------------------\n\nexport type ToolExecutionMode = 'sequential' | 'parallel'\n\nexport interface AgentBehavior {\n  /** Tool execution mode (default: 'sequential') */\n  toolExecution?: ToolExecutionMode\n  /**\n   * Max agent loop iterations.\n   *\n   * Default: unlimited (Infinity). The loop runs until the model signals\n   * completion (no tool calls / `end_turn`), the abort signal fires, or this\n   * cap is hit. Set a finite value as a safety net for runaway loops.\n   */\n  maxTurns?: number\n  /** Max tokens per LLM response (default: 16384) */\n  maxTokens?: number\n  /** Thinking token budget — overrides the level-based default when set */\n  thinkingBudget?: number\n  /** JSON Schema for structured output enforcement */\n  schema?: Record<string, unknown>\n  /**\n   * Enable provider prompt caching. When on (default), the provider marks the\n   * system prompt, tools, and the last stable message with cache breakpoints so\n   * the shared prefix is served from cache across turns.\n   *\n   * - Anthropic: `cache_control: { type: 'ephemeral' }` on the last `system`\n   *   content part, the last tool, and the last message content part.\n   * - OpenAI-compatible / OpenRouter: same shape — honored by Anthropic-backed\n   *   OpenRouter routes and by Gemini; ignored (no-op) by providers that cache\n   *   automatically (OpenAI, DeepSeek, Grok, Groq, Moonshot).\n   *\n   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.\n   *\n   * Default: `true`.\n   */\n  cache?: boolean\n  /**\n   * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`\n   * across a turn's tool results exceeds this value, the loop injects a\n   * synthetic user message instructing the model to summarize before calling\n   * more tools, and fires the `budget:exceeded` hook.\n   *\n   * Measured **post-`tool:transform`** so consumer truncation counts toward the\n   * budget. Off by default (undefined / `0` disables the check). A reasonable\n   * starting value for OSS-model integrations is `32768`.\n   */\n  toolOutputBudget?: number\n  /**\n   * Deduplicate identical re-reads of the same file in `read_file`. When the\n   * model re-reads a file with the same slice and the bytes haven't changed\n   * since the last read in this session, the tool returns a short stub\n   * instead of re-emitting the full content. Pairs with the read-before-edit\n   * guard in `edit` / `multi_edit`.\n   *\n   * Requires a session (set via `createSession()`); without one, the flag is\n   * a no-op since per-session state has nowhere to live.\n   *\n   * Default: `true`.\n   */\n  dedupReads?: boolean\n  /**\n   * Taper the thinking budget over the course of a run. Late turns are\n   * usually checkpoint / cleanup work where reasoning rarely pays for\n   * itself; early turns benefit most. Two forms:\n   *\n   * - **Struct** — geometric decay starting after `afterTurn`, multiplying by\n   *   `factor` each subsequent turn, clamped to `floor`. Example\n   *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:\n   *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.\n   * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;\n   *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).\n   *\n   * No-op when `thinkingBudget` is unset. Honored by every provider that\n   * respects `thinkingBudget` (anthropic explicit-budget `enabled` path,\n   * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).\n   *\n   * Default: `undefined` (no decay).\n   */\n  thinkingDecay?: { afterTurn: number, factor: number, floor: number } | ((runTurn: number, baseBudget: number) => number)\n  /**\n   * Per-tool soft call budget for this run. Keyed by **canonical** tool name.\n   * On the first call after the run-cumulative dispatched count for that tool\n   * reaches `max`, the framework fires `onExceed`:\n   *\n   * - `'steer'` (default) — let the call execute, but emit a synthetic user\n   *   message after the turn that nudges the model away from re-calling the\n   *   tool. Reuses the existing post-turn steer pathway used by\n   *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.\n   * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a\n   *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with\n   *   `mode: 'block'`.\n   * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the\n   *   steering / refusal text and chooses the mode dynamically.\n   *\n   * Counts include both real dispatches and dedup substitutes (Z19 hits).\n   * Excludes calls already blocked by an earlier gate (skill allow-list,\n   * consumer hook). Tool dispatched by spawned subagents has its own per-run\n   * counter — child counts never charge the parent.\n   *\n   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).\n   *\n   * Atomic in parallel mode: the middleware tracks its own per-tool\n   * approval counter, incremented synchronously at gate-time. A\n   * 4-call parallel batch against `max: 2` will let the first 2 through\n   * and refuse the rest, even though the loop's `runToolCounts` only\n   * propagates between calls (not within a single batch's gate fan-out).\n   *\n   * Default: `undefined` (no budget enforcement).\n   */\n  toolBudgets?: Record<string, {\n    max: number\n    onExceed?: 'steer' | 'block' | ((ctx: {\n      tool: string\n      count: number\n      max: number\n    }) => { mode: 'steer' | 'block', message: string })\n  }>\n  /**\n   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**\n   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.\n   *\n   * **Hasher contract** — three return values, three meanings:\n   *\n   * | Return                  | Meaning                                                                |\n   * |-------------------------|------------------------------------------------------------------------|\n   * | a non-empty string      | Cache key for this call. Equal keys (most-recent-only, this session)   |\n   * |                         | replay the prior recorded result without re-dispatching the tool.      |\n   * | `undefined`             | **Skip dedup for this call.** The tool runs normally; nothing recorded.|\n   * | `''` / non-string       | Treated identically to `undefined` (defensive: no dedup, no error).    |\n   *\n   * The `undefined` opt-out is the way to say *\"this specific call is not\n   * cacheable\"* (timestamps in input, randomness baked in, debug flags). It\n   * is **not** the same as `JSON.stringify(input)` — that would dedup against\n   * the verbatim input. Pick one explicitly:\n   *\n   * ```ts\n   * // Always cache by full input — every identical re-call dedups.\n   * dedupTools: { my_pure_tool: input => JSON.stringify(input) }\n   *\n   * // Cache by a normalized subset; non-cacheable shapes opt out.\n   * dedupTools: {\n   *   execute_sql: (input) => {\n   *     const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined\n   *     if (!q || q.includes('now()') || q.includes('random()')) return undefined\n   *     return q\n   *   },\n   * }\n   * ```\n   *\n   * On a hit, the previously-recorded result is replayed as the tool_result\n   * without dispatching the tool. The substitution flows through `tool:gate`\n   * `result` (Z20), so `tool:after` and `tool:transform` still fire.\n   *\n   * Requires a session (`createSession()`); without one, the map is a silent\n   * no-op since per-session state has nowhere to live. Tools with side\n   * effects or non-deterministic outputs (network, time, randomness) MUST\n   * NOT be listed — there is no safety net beyond the consumer's hasher.\n   *\n   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).\n   * Parallel mode (`toolExecution: 'parallel'`, the default) sees calls in\n   * the SAME assistant turn race against each other — none can dedup against\n   * a sibling that started in the same batch. Sequential mode honors order\n   * within a turn.\n   *\n   * **Cache policy**: only the most recent `(hash, result)` per tool is\n   * retained. Interleaved patterns (input A, input B, input A) miss on the\n   * second A because B overwrote it. Sufficient for the common spam-the-\n   * same-call loop; consumers needing a richer cache should hook\n   * `tool:gate` directly.\n   *\n   * Default: `undefined` (no per-tool dedup).\n   */\n  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>\n  /**\n   * Require `read_file` before `edit` / `multi_edit` on the same path, and\n   * reject edits when the file has changed on disk since the last read in\n   * this session. Eliminates the silent-corruption failure mode where a\n   * model \"remembers\" stale content and applies a substring edit against\n   * bytes that have moved.\n   *\n   * Requires a session. Off by default; turn it on for stricter eval-grade\n   * runs where silent edit corruption would invalidate the result.\n   *\n   * Default: `false`.\n   */\n  requireReadBeforeEdit?: boolean\n  /**\n   * Client-side context compaction strategy. Use this for non-Anthropic\n   * providers (OSS via cerebras / openai-compat / openrouter) that don't\n   * have a server-side equivalent. Anthropic users should prefer the\n   * server-side `context-management-2025-06-27` beta — see\n   * `AnthropicParams.contextManagement`.\n   *\n   * - `'off'` (default) — no client-side compaction.\n   * - `'tail'` — when total tool-output bytes in the persisted history\n   *   exceed `compactThreshold`, replace older `tool_result` outputs with a\n   *   short stub, keeping the newest `compactKeepTurns` turns intact. The\n   *   compaction is applied to the wire-level message list only; the\n   *   underlying session turns are not modified.\n   *\n   * Default: `'off'`.\n   */\n  compactStrategy?: 'off' | 'tail'\n  /**\n   * Soft byte threshold that triggers tail compaction when\n   * `compactStrategy === 'tail'`. Counts the post-`context:transform` bytes\n   * of `tool_result` outputs across all messages. Default: `131_072` (128\n   * KiB). Ignored when compaction is off.\n   */\n  compactThreshold?: number\n  /**\n   * Number of trailing turns to leave untouched during tail compaction. The\n   * most-recent `compactKeepTurns` user/assistant messages are not eligible\n   * for elision so the model keeps the freshest tool context. Default: `4`.\n   */\n  compactKeepTurns?: number\n  /**\n   * Prefix every line of `read_file` output with its 1-indexed line number\n   * followed by a tab (`<N>\\t<content>`) — the compact `cat -n`-style\n   * format Claude Code emits. The `edit` tool strips the prefix from\n   * `old_string` / `new_string` so the model can paste back a numbered\n   * chunk verbatim without breaking the match.\n   *\n   * Set `false` to opt out — useful for callers piping `read_file` into\n   * downstream parsers that don't recognize the prefix. Per-call\n   * `read_file({ lineNumbers: false })` overrides this default.\n   *\n   * Default: `true`.\n   */\n  readLineNumbers?: boolean\n  /**\n   * Replace older `read_file` `tool_result` blocks with a short stub when\n   * a successful `edit` / `multi_edit` / `write_file` later in the same\n   * run modified the same path. The replacement is applied to the\n   * wire-level message list only — persisted session turns keep the\n   * original content.\n   *\n   * Eliminates the common waste pattern where the model carries the\n   * pre-edit file body forward across many turns \"in case it needs it\".\n   * Pairs cleanly with `compactStrategy: 'tail'`: stale reads shrink\n   * first, then the byte-threshold compaction fires if anything's left.\n   *\n   * Detection is conservative — only triggers when the corresponding\n   * tool_result confirms success (`Edited …`, `Created …`, `Updated …`).\n   * Failed edits and `No change needed` write_file calls do NOT\n   * invalidate prior reads.\n   *\n   * Default: `false`.\n   */\n  elideStaleReads?: boolean\n  /**\n   * Tool disclosure strategy. Controls whether the model sees every tool's\n   * full `inputSchema` in its tool list every turn (\"eager\") or whether MCP\n   * tools are advertised as a name+description catalog in the system prompt\n   * and only get full schemas after being surfaced via the `tool_search`\n   * native tool (\"lazy\" / progressive disclosure).\n   *\n   * Native tools (those passed to `createAgent({ tools })`) and skill tools\n   * are always eager — they are core to the agent and cheap. Only MCP tools\n   * are eligible for lazy disclosure.\n   *\n   * When `'lazy'`, the agent:\n   * - Appends a `<searchable_tools>` section to the system prompt listing\n   *   every MCP tool by `name` + `description` only (no `inputSchema`).\n   * - Auto-injects a `tool_search` native tool (opt out via\n   *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on\n   *   demand. Surfaced tools persist for the rest of the run.\n   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked\n   *   tools at the end so the prefix-cache breakpoint advances cleanly.\n   *\n   * Trade-off: every `tool_search` invocation expands the tool list and\n   * invalidates the tool-list cache breakpoint for one turn. With many\n   * MCP servers, the savings on cold turns (fewer schemas in context) are\n   * substantial; with one tiny MCP server, the overhead may not pay back.\n   *\n   * Default: `'eager'`.\n   */\n  toolDisclosure?: 'eager' | 'lazy'\n  /**\n   * Fine-grained config for the `tool_search` tool auto-injected when\n   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.\n   *\n   * - `tool: false` — opt out of the auto-injection entirely. Use when the\n   *   host wants to ship a custom discovery tool. Note that the catalog\n   *   text drops the call-to-action prose in this case so the model isn't\n   *   pointed at a non-existent tool.\n   * - `limit` — default cap on results returned per `tool_search` call when\n   *   the model omits the parameter. Default: `20`.\n   *\n   * Note on host-defined `tool_search`: a tool the host registers under the\n   * name `tool_search` (or under any alias whose canonical is `tool_search`)\n   * will shadow the auto-injected one — the catalog text will point at the\n   * host's wire name, but driving the unlock flow requires either using\n   * `createToolSearchTool({ catalog, unlocked })` from `tools/tool-search`\n   * (which internally mutates the unlock set) or fully opting out via\n   * `toolSearch.tool: false` and treating discovery as a host-side concern.\n   * A bare host tool that doesn't touch the unlock set will not advance the\n   * lazy disclosure state and the hard gate will keep refusing lazy calls.\n   *\n   * Default: `undefined` (auto-inject with the default limit).\n   */\n  toolSearch?: {\n    tool?: false\n    limit?: number\n  }\n  /**\n   * Persist large `tool_result` outputs to disk and replace the in-message\n   * content with a `<persisted-output>` stub (preview + filesystem path).\n   * When the post-`tool:transform` byte size of a tool's result exceeds\n   * this threshold, the framework writes the full payload to\n   * `<persistDir>/<callId>.txt` and substitutes a fixed-format stub so the\n   * model sees a 2 KiB preview plus the path it can `read_file`.\n   *\n   * The substitution happens at emit time (just after `tool:transform` runs)\n   * and the stub flows into `session.turns` directly — so every subsequent\n   * turn re-emits the same bytes, keeping the prompt-cache prefix stable.\n   *\n   * Set `0` / `undefined` to disable. Built-in chat profiles default to\n   * `8192`. Tools listed in {@link AgentBehavior.persistExcludeTools} bypass\n   * regardless of size — typically because their output is intentionally\n   * short or persisting would be circular (e.g. `read_file`).\n   *\n   * Requires {@link AgentBehavior.persistDir} to be set; without a target\n   * directory the framework silently skips persistence (no throw, no\n   * substitution) since there's nowhere to write the blob.\n   *\n   * Default: `undefined` (off).\n   */\n  persistThreshold?: number\n  /**\n   * Canonical tool names to exclude from disk persistence regardless of\n   * output size. The framework bypasses persistence for any tool whose\n   * canonical name appears in this list — useful for tools whose results\n   * are intentionally part of the prompt (`skills_use`), short envelopes\n   * (`tool_search`, `present_plan`, `ask_user`), or where persistence\n   * would be circular (`read_file`, whose pagination already serves the\n   * same use case).\n   *\n   * Default: `undefined` (no exclusions). The chat-layer built-in profiles\n   * set their own list — see `src/chat/agents.ts`.\n   */\n  persistExcludeTools?: readonly string[]\n  /**\n   * Directory under which persisted tool-result blobs land. Each call's\n   * payload is written to `<persistDir>/<callId>.txt` (one file per\n   * `tool_use` id, atomic via write-then-rename).\n   *\n   * The chat layer resolves this to `<userDir>/tool-results/<sessionId>/`\n   * at session activation; SDK consumers pass an absolute path. Required\n   * when {@link AgentBehavior.persistThreshold} is non-zero — when unset\n   * the framework treats persistence as disabled.\n   *\n   * Default: `undefined`.\n   */\n  persistDir?: string\n}\n\n// ---------------------------------------------------------------------------\n// Prompt parts (multimodal input)\n// ---------------------------------------------------------------------------\n\n/**\n * One block of a multimodal user prompt.\n *\n * `agent.run({ prompt })` accepts either a plain string (treated as a single\n * text part) or an array of these parts for multimodal inputs.\n *\n * `document` parts are routed per provider: PDF-style mime types are sent as\n * native document blocks when the provider supports them; text documents are\n * inlined as text with an attachment header. Providers that cannot handle an\n * image or document throw early.\n */\nexport type PromptPart\n  = | PromptTextPart\n    | PromptImagePart\n    | PromptDocumentPart\n\nexport interface PromptTextPart {\n  type: 'text'\n  text: string\n}\n\nexport interface PromptImagePart {\n  type: 'image'\n  /** IANA media type (e.g. `image/png`, `image/jpeg`) */\n  mediaType: string\n  /** Base64-encoded payload */\n  data: string\n  /** Optional display name */\n  name?: string\n}\n\nexport interface PromptDocumentPart {\n  type: 'document'\n  /** IANA media type (e.g. `application/pdf`, `text/plain`) */\n  mediaType: string\n  /** Either a base64-encoded payload (`encoding: 'base64'`) or raw text (`encoding: 'text'`) */\n  data: string\n  encoding: 'base64' | 'text'\n  /** Optional display name used in attachment headers */\n  name?: string\n}\n\n// ---------------------------------------------------------------------------\n// Canonical message format (used throughout the agent system)\n// ---------------------------------------------------------------------------\n\n/**\n * A single block of structured tool-result content.\n *\n * MCP servers can return a mix of text, image, resource, and audio blocks. Tools\n * return `string` for the common text-only case or `ToolResultContent[]` when they\n * need to preserve non-text content (e.g. screenshots from a browser MCP).\n *\n * Providers that support native multi-part tool results (Anthropic, OpenAI Codex via\n * pi-ai) route image blocks into their wire format verbatim; OpenAI-compat providers\n * route them via a companion-user-message fallback when the underlying model/endpoint\n * does not accept images inside tool-role messages.\n */\nexport type ToolResultContent\n  = | ToolResultTextContent\n    | ToolResultImageContent\n\nexport interface ToolResultTextContent {\n  type: 'text'\n  text: string\n}\n\nexport interface ToolResultImageContent {\n  type: 'image'\n  /** IANA media type (e.g. `image/png`, `image/jpeg`) */\n  mediaType: string\n  /** Base64-encoded payload */\n  data: string\n}\n\n/**\n * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single\n * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.\n *\n * Use at UI boundaries where a string is required; providers that understand\n * structured content should route the array through without flattening.\n */\nexport function toolResultToText(content: string | ToolResultContent[]): string {\n  if (typeof content === 'string')\n    return content\n  return content\n    .map((block) => {\n      if (block.type === 'text')\n        return block.text\n      return `[image: ${block.mediaType} — ${block.data.length} b64 bytes]`\n    })\n    .join('\\n')\n}\n\n/**\n * Approximate **wire payload size** of a tool output, in bytes.\n *\n * - Plain text: UTF-8 byte length.\n * - Structured content: text blocks contribute their UTF-8 byte length; image\n *   blocks contribute their **base64 character length** — a proxy for the\n *   serialized request-body footprint, NOT for tokens. Vision encoders\n *   tokenize decoded pixels (geometry-dependent; e.g. Anthropic ≈ `w·h/750`,\n *   OpenAI ≈ 85 + 170/tile), which has no meaningful relationship to base64\n *   length.\n *\n * Used by the agent loop to populate `outputBytes` on `tool:after`,\n * `tool:transform`, `mcp:tool:after`, and `mcp:tool:transform` hooks so\n * consumers can size-budget tool output without re-counting bytes themselves.\n * Suitable for byte-budget heuristics (`toolOutputBudget`, tail compaction);\n * NOT a substitute for provider-side context-window accounting — defer to\n * server-side context management (e.g. Anthropic's `context-management-*`\n * beta) when token accuracy matters.\n */\nexport function toolOutputByteLength(content: string | ToolResultContent[]): number {\n  if (typeof content === 'string')\n    return Buffer.byteLength(content)\n  let total = 0\n  for (const block of content) {\n    if (block.type === 'text')\n      total += Buffer.byteLength(block.text)\n    else\n      total += block.data.length\n  }\n  return total\n}\n\nexport type SessionContentBlock\n  = | { type: 'text', text: string }\n    | { type: 'image', mediaType: string, data: string }\n    | { type: 'tool_call', id: string, name: string, input: Record<string, unknown> }\n    | {\n      type: 'tool_result'\n      callId: string\n      /**\n       * Tool output — either a plain string (text-only, the common case) or a structured\n       * array of content blocks (text + image for multimodal tools such as screenshots).\n       */\n      output: string | ToolResultContent[]\n      isError?: boolean\n    }\n    | {\n      type: 'thinking'\n      text: string\n      signature?: string\n      /**\n       * Provider that minted `signature`. Signatures are provider-bound (Anthropic\n       * HMAC vs. OpenAI `encrypted_content`) and are dropped on cross-provider\n       * hops to avoid 400s. Unset means legacy/unknown — forwarded as-is.\n       */\n      signatureProducer?: 'anthropic' | 'openai'\n    }\n    | { type: 'redacted_thinking', data: string }\n    | {\n      /**\n       * Opaque round-trip envelope for reasoning state minted by an OpenAI-compat\n       * gateway (currently OpenRouter). The gateway expects its own\n       * `reasoning_details` array echoed back verbatim on the next turn so the\n       * upstream model can resume an extended-reasoning chain across tool calls.\n       *\n       * Stored opaquely because the items are provider-bound (Anthropic HMAC\n       * signatures, OpenAI `encrypted_content`, model-specific summary formats\n       * — all flowing through the gateway's normalized envelope).\n       */\n      type: 'provider_reasoning'\n      producer: 'openrouter'\n      details: unknown[]\n      /**\n       * Model id that produced the details. Reasoning is bound to a specific\n       * upstream route — a model switch on the next turn invalidates the\n       * embedded signatures, so the sender drops the block on mismatch.\n       */\n      model?: string\n    }\n    | {\n      /**\n       * Compaction marker. Inserted by `compactConversation()` to replace a\n       * prefix of turns with an LLM-generated summary.\n       *\n       * The marker lives in `session.turns` and renders in the transcript —\n       * the user can still scroll back to see the original turns. From the\n       * agent loop's wire-level perspective, every turn whose id appears in\n       * `replacesTurnIds` is dropped, and this block's `summary` text is\n       * sent to the model as a single user message in their place.\n       *\n       * The marker turn carries `role: 'user'` so it sits naturally at a\n       * conversational boundary. Only the latest `compact-summary` block in\n       * the session is honored — earlier markers are subsumed by later\n       * ones (their `replacesTurnIds` are a strict prefix).\n       */\n      type: 'compact-summary'\n      /** Turn ids the summary replaces, in chronological order. */\n      replacesTurnIds: readonly string[]\n      /** The summary text sent to the model in place of the elided turns. */\n      summary: string\n      /** Model id used to produce the summary. */\n      model: string\n      /** Token usage from the summary call. */\n      usage: TurnUsage\n      /** Unix-ms when compaction completed. */\n      compactedAt: number\n    }\n\nexport interface SessionMessage {\n  role: 'user' | 'assistant'\n  content: SessionContentBlock[]\n}\n\nexport interface SessionTurn {\n  /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */\n  id: string\n  /** Run that produced this turn (e.g. 'run_1') */\n  runId?: string\n  role: 'user' | 'assistant' | 'system'\n  content: SessionContentBlock[]\n  /** Token usage — only present on assistant turns */\n  usage?: TurnUsage\n  /** Unix timestamp (Date.now()) when the turn was created */\n  createdAt: number\n}\n\n// ---------------------------------------------------------------------------\n// Agent run options\n// ---------------------------------------------------------------------------\n\n/**\n * Per-run hook registrations. Each entry can be a single handler or an array of handlers.\n * Keys are `AgentHooks` event names (loose-typed here to avoid a circular import; agent.ts\n * narrows it to the strongly-typed map).\n */\nexport type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>\n\nexport interface AgentRunOptions {\n  model?: string\n  /**\n   * User prompt. Optional when resuming a session with existing turns.\n   *\n   * Accepts either a plain string (single text part) or an array of `PromptPart`s for\n   * multimodal inputs (text, images, documents). See {@link PromptPart}.\n   */\n  prompt?: string | PromptPart[]\n  system?: string\n  thinking?: ThinkingLevel\n  /** Abort signal — when triggered, the agent stops after the current turn */\n  signal?: AbortSignal\n  /** Behavior overrides for this run (overrides agent defaults) */\n  behavior?: AgentBehavior\n  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */\n  tools?: Record<string, ToolDef>\n  /**\n   * Per-run hook registrations. Each hook is attached before the run starts and\n   * detached in a finally block so handlers never leak across runs.\n   *\n   * Accepts either a single handler or an array (all handlers register).\n   */\n  hooks?: RunHookMap\n  /**\n   * Parent run id. Populated automatically by the `spawn` tool when the child\n   * shares the parent's session; recorded on the resulting `SessionRun` so the\n   * parent↔child run tree can be reconstructed from a persisted session.\n   */\n  parentRunId?: string\n  /**\n   * Zero-based subagent depth. 0 = top-level `agent.run()`, 1 = first-level\n   * child spawned by a parent agent, and so on. Used by the spawn tool to\n   * enforce `maxDepth` and to stamp `child:*` forwarded hook payloads.\n   */\n  depth?: number\n}\n\n// ---------------------------------------------------------------------------\n// Agent stats\n// ---------------------------------------------------------------------------\n\n/**\n * Reason the provider gave for stopping the turn.\n *\n * - `'stop'` — natural turn end (`end_turn` / `stop_sequence`).\n * - `'tool-calls'` — model emitted tool_use blocks.\n * - `'length'` — `max_tokens` reached, or (Anthropic 4.6+) the response bumped\n *   against the model's context window mid-stream\n *   (`model_context_window_exceeded`). The partial response is preserved; the\n *   loop emits this reason so consumers can prune/retry.\n * - `'content-filter'` — model refused.\n * - `'pause'` — Anthropic `pause_turn`: a server-side mid-turn pause for very\n *   long thinking. The loop continues with a synthetic \"Please continue.\"\n *   user message rather than terminating; consumers see the pause via this\n *   finish reason on the prior assistant turn.\n * - `'error'` — provider classified the turn as failed.\n * - `'other'` — unknown / unmapped.\n */\nexport type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'pause' | 'error' | 'other'\n\nexport interface TurnUsage {\n  input: number\n  output: number\n  /** Tokens written to cache (Anthropic) */\n  cacheCreation?: number\n  /** Tokens read from cache (Anthropic) */\n  cacheRead?: number\n  /** Thinking/reasoning tokens used */\n  thinking?: number\n  /**\n   * Cost in USD for this turn. Provider-reported when available\n   * (OpenRouter, OpenAI via pi-ai); otherwise estimated from `modelId` ×\n   * pi-ai's bundled price registry by `fillEstimatedCost` in\n   * `src/providers/cost.ts`. Absent only when neither path could resolve\n   * a price (unknown / unbundled model).\n   */\n  cost?: number\n  /**\n   * Why the model stopped this turn. Providers normalize native stop reasons to this union.\n   * Absent when the provider did not surface a reason (e.g. mock turns).\n   */\n  finishReason?: TurnFinishReason\n  /**\n   * The model ID the provider ultimately used. May differ from the requested model when the\n   * provider remaps aliases. Absent for providers that do not echo a model ID.\n   */\n  modelId?: string\n}\n\nexport interface AgentStats {\n  /**\n   * Cumulative input tokens across the parent agent loop **and** every\n   * recursively-spawned sub-agent. Use this for billing / token-ledger\n   * consumption.\n   */\n  totalIn: number\n  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */\n  totalOut: number\n  /**\n   * Cumulative cache-read tokens across the parent agent loop and every\n   * recursively-spawned sub-agent. Surfaced at the top level (rather than\n   * only per-`TurnUsage`) because Anthropic prices cache reads at a separate\n   * line-item rate from regular input — billing-correct cost computation\n   * needs this number directly. Always `0` for providers that don't report\n   * cache usage.\n   */\n  totalCacheRead: number\n  /**\n   * Cumulative cache-creation tokens across the parent agent loop and every\n   * recursively-spawned sub-agent. Same rationale as\n   * {@link AgentStats.totalCacheRead} — separate Anthropic billing rate.\n   * Always `0` for providers that don't report cache usage.\n   */\n  totalCacheCreation: number\n  /**\n   * Number of parent agent-loop turns. Children's turn counts live under\n   * `children[].stats.turns` and are NOT folded in here — a single \"turns\"\n   * number for the whole tree would conflate two different measures\n   * (parent-loop iterations vs. tree-wide tool-call rounds).\n   *\n   * Tree-wide turn count: `flattenTurns(stats).length`.\n   */\n  turns: number\n  /**\n   * Wall-clock duration of the top-level `agent.run()` call, in milliseconds.\n   * Children run during parent tool calls so this naturally subsumes child\n   * wall time — sequential children inflate it, parallel children compress\n   * into the parent's window.\n   */\n  elapsed: number\n  /**\n   * Per-turn usage breakdown for the **parent loop only**. Children's per-turn\n   * usages live under `children[].stats.turnUsage`. Use {@link flattenTurns}\n   * to walk the full tree.\n   */\n  turnUsage?: TurnUsage[]\n  /**\n   * Cumulative cost in USD — parent loop plus every recursively-spawned\n   * sub-agent. Sums per-turn `TurnUsage.cost` reported by the provider.\n   * Absent when neither parent nor any descendant reported a non-zero cost.\n   */\n  cost?: number\n  /** Stats from child agents spawned during this run, in completion order. Recursive. */\n  children?: ChildRunStats[]\n  /** Structured output from schema enforcement (only present when behavior.schema is set) */\n  output?: Record<string, unknown>\n  /**\n   * Milliseconds from the start of `agent.run()` to the first observable signal from the\n   * provider (first `stream:text`, `stream:thinking`, or `tool:before` event).\n   *\n   * Absent when the run produced no observable signals (e.g. aborted before any stream event).\n   */\n  timeTillFirstTokenMs?: number\n}\n\nexport interface ChildRunStats {\n  id: string\n  task: string\n  /**\n   * The child agent's full {@link AgentStats}. Cumulative for that child's\n   * own subtree (child loop + its grandchildren). Do **not** sum\n   * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level\n   * totals — `agent.run()`'s return value is the canonical cumulative root.\n   */\n  stats: AgentStats\n  /**\n   * Subagent depth when this child ran. 1 = direct child of the top-level\n   * agent, 2 = grandchild, etc. Useful for telemetry that wants to group\n   * runs by depth.\n   */\n  depth?: number\n  /**\n   * Terminal state of the child run. `'completed'` is the default. Exposed so\n   * a parent reading `stats.children` can distinguish aborted/timed-out\n   * children without re-parsing the returned string.\n   */\n  status?: 'completed' | 'aborted' | 'timeout' | 'error'\n  /**\n   * Final structured output when the child was run with `behavior.schema`.\n   * Mirrors `AgentStats.output` but is surfaced here so the parent can read\n   * it without peeking at the nested `stats` bag.\n   */\n  output?: Record<string, unknown>\n}\n\n// ---------------------------------------------------------------------------\n// Hook context types\n// ---------------------------------------------------------------------------\n\n/**\n * Base context for tool execution hooks.\n *\n * `name` is the canonical tool identity — the spec name registered on the agent (or the\n * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.\n *\n * `displayName` is the outward-facing name — the alias surfaced to the LLM when\n * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.\n * UI/telemetry adapters should emit `displayName`.\n *\n * Canonical vs. alias matters on session resume: `session.turns` persists canonical\n * names only, so renaming an alias cannot desync history.\n */\nexport interface ToolHookContext {\n  turnId: string\n  callId: string\n  /** Canonical tool name (spec name). Stable across alias-map changes. */\n  name: string\n  /** Aliased (wire) name — equal to `name` when no alias is defined. */\n  displayName: string\n  input: Record<string, unknown>\n}\n\n/**\n * Base context for MCP tool hooks.\n *\n * `tool` is the native tool name on the MCP server. `server` is the configured server\n * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.\n *\n * `displayName` equals the canonical namespaced name unless the agent has aliased\n * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the\n * alias that the LLM sees.\n */\nexport interface McpToolHookContext {\n  turnId: string\n  callId: string\n  server: string\n  tool: string\n  /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */\n  displayName: string\n  input: Record<string, unknown>\n}\n\n/** Base context for session hooks */\nexport interface SessionHookContext {\n  sessionId: string\n}\n\n/** Base context for spawn hooks */\nexport interface SpawnHookContext {\n  id: string\n  task: string\n  /**\n   * Subagent depth for the spawn. 1 = direct child of the top-level agent.\n   * Present on spawn:before/complete/error. Absent for grandchild spawns that\n   * bubble through `child:*` events (which carry their own `depth`).\n   */\n  depth?: number\n}\n\n/** Context for stream hooks */\nexport interface StreamHookContext {\n  turnId: string\n}\n\n/** Context for OAuth refresh hooks */\nexport interface OAuthRefreshHookContext {\n  provider: string\n  providerId: string\n  source: 'params' | 'file'\n  previousCredentials: Record<string, unknown> & { access: string, refresh: string, expires: number }\n  credentials: Record<string, unknown> & { access: string, refresh: string, expires: number }\n}\n\nexport type SessionEndStatus = 'completed' | 'aborted' | 'error'\n"],"mappings":";;;;;;;;;AAqnBA,SAAgB,iBAAiB,SAA+C;CAC9E,IAAI,OAAO,YAAY,UACrB,OAAO;CACT,OAAO,QACJ,KAAK,UAAU;EACd,IAAI,MAAM,SAAS,QACjB,OAAO,MAAM;EACf,OAAO,WAAW,MAAM,UAAU,KAAK,MAAM,KAAK,OAAO;GACzD,CACD,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;AAsBf,SAAgB,qBAAqB,SAA+C;CAClF,IAAI,OAAO,YAAY,UACrB,OAAO,OAAO,WAAW,QAAQ;CACnC,IAAI,QAAQ;CACZ,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,SAAS,QACjB,SAAS,OAAO,WAAW,MAAM,KAAK;MAEtC,SAAS,MAAM,KAAK;CAExB,OAAO"}
+{"version":3,"file":"types-IcokUOyC.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/**\n * Shared types for the agent system.\n */\n\nimport type { ToolDef } from './tools/types'\nimport { Buffer } from 'node:buffer'\n\n// ---------------------------------------------------------------------------\n// Thinking / Reasoning\n// ---------------------------------------------------------------------------\n\n/**\n * Thinking / extended-reasoning configuration.\n *\n * - `'off'` — no thinking.\n * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to\n *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`\n *   with a budget; OpenAI `reasoning_effort`).\n * - `'adaptive'` — let the model decide per-turn whether and how much to think.\n *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to\n *   no reasoning when this value is supplied.\n */\nexport type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive'\n\n// ---------------------------------------------------------------------------\n// MCP server configuration\n// ---------------------------------------------------------------------------\n\n/**\n * Slim shape of an upstream MCP tool descriptor — what `client.listTools()`\n * returns per entry. Exposed publicly so hosts can persist the schemas\n * between runs and feed them back via {@link McpServerConfig.cachedTools}\n * to skip the `tools/list` round-trip on subsequent bootstraps.\n */\nexport interface McpToolSchema {\n  name: string\n  description?: string | null\n  inputSchema?: unknown\n}\n\nexport interface McpServerConfig {\n  /** Display name (used for tool namespacing) */\n  name: string\n  /** Transport type */\n  transport: 'stdio' | 'sse' | 'streamable-http'\n  /** For stdio: command to run */\n  command?: string\n  /** For stdio: command arguments */\n  args?: string[]\n  /**\n   * For stdio: environment variables to pass to the server process.\n   *\n   * Merged on top of the MCP SDK's default inherited environment — a safety\n   * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,\n   * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from\n   * the child process. Set {@link McpServerConfig.strictEnv} to `true` to\n   * pass `env` verbatim with no inherited defaults.\n   */\n  env?: Record<string, string>\n  /**\n   * When true, {@link McpServerConfig.env} is passed verbatim to the spawned\n   * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)\n   * is NOT merged in. Most consumers should leave this off; the default merge\n   * prevents `spawn ENOENT` when a stdio server declares an `env` without\n   * restating `PATH`.\n   */\n  strictEnv?: boolean\n  /** For sse/streamable-http: server URL */\n  url?: string\n  /** Optional headers for HTTP transports */\n  headers?: Record<string, string>\n  /**\n   * OAuth 2.1 authentication (sse / streamable-http only).\n   *\n   * - `'oauth'` — enables the SDK's OAuth flow with RFC 9728 protected-resource\n   *   metadata discovery, RFC 8414 / OIDC authorization-server metadata, RFC 7591\n   *   dynamic client registration, PKCE, and refresh-token rotation. Tokens persist\n   *   between runs via the host's credential store.\n   * - `undefined` (default) — no OAuth. The host may still auto-promote a server\n   *   to OAuth on `UnauthorizedError` IF no static `Authorization` header is set\n   *   (the headers check stops us from second-guessing user-managed bearer tokens).\n   *\n   * Recognized aliases at parse time: Cursor's `authMethod: 'mcpOAuth'` maps to\n   * `auth: 'oauth'` so `~/.cursor/mcp.json` pastes work unchanged.\n   */\n  auth?: 'oauth'\n  /**\n   * Timeout in milliseconds for MCP server bootstrap (connect + tool discovery).\n   *\n   * Zidane connects MCP servers lazily on the first `run()`. Without a\n   * bootstrap timeout, a slow or hung server can delay the first provider call\n   * for an arbitrarily long time even when that MCP server is never used.\n   *\n   * Default: `10000`.\n   */\n  bootstrapTimeout?: number\n  /** Timeout in milliseconds for MCP tool calls (default: 30000) */\n  toolTimeout?: number\n  /**\n   * Allow-list of tool names to expose. Names match the upstream tool name\n   * (NOT the namespaced `mcp_{server}_{tool}` form). Tools not in the list are\n   * dropped before registration — the model never sees them in its catalog and\n   * the wire cost of advertising them is avoided.\n   *\n   * Mutually exclusive with {@link McpServerConfig.disabledTools} — passing both\n   * throws at bootstrap time.\n   *\n   * Composes with {@link McpServerConfig.toolFilter}: allow-list applies first,\n   * then the predicate. Composes with the `mcp:tools:filter` hook: config-side\n   * filters apply first, then the hook can further narrow the list.\n   */\n  enabledTools?: string[]\n  /**\n   * Deny-list of tool names. Tools matching are dropped before registration.\n   * Same matching semantics as {@link McpServerConfig.enabledTools}.\n   */\n  disabledTools?: string[]\n  /**\n   * Custom predicate run on each upstream tool. Return `true` to keep, `false`\n   * to drop. Receives the raw `listTools()` payload — useful for filtering by\n   * description, schema shape, or other metadata that an allow/deny list can't\n   * express.\n   *\n   * Runs after the allow/deny filter but before the `mcp:tools:filter` hook.\n   */\n  toolFilter?: (tool: { name: string, description?: string | null, inputSchema?: unknown }) => boolean\n  /**\n   * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,\n   * this server's tools follow this disclosure mode regardless of the\n   * agent-wide default. Useful when one big MCP server (200+ tools) should\n   * stay lazy while smaller servers stay eager.\n   *\n   * Default: inherits from `behavior.toolDisclosure`.\n   */\n  disclosure?: 'eager' | 'lazy'\n  /**\n   * Pre-cached tool schemas to advertise without issuing `tools/list` at\n   * bootstrap. The connection is still established (the SDK's `connect()`\n   * is needed for `tools/call`) — only the discovery round-trip is\n   * skipped. Schemas are trusted as-is; the host owns invalidation\n   * (typical cache key: `(server identity, server version)`). If the\n   * server later returns `MethodNotFound` for a cached tool, the host\n   * should drop the entry from its cache so the next bootstrap re-lists.\n   *\n   * Compatible with every transport, every auth mode, and with\n   * {@link McpServerConfig.lazyConnect}. Composes with the existing\n   * `enabledTools` / `disabledTools` / `toolFilter` filters — those run\n   * over the cached schemas exactly as they would over `listTools()`\n   * output.\n   */\n  cachedTools?: McpToolSchema[]\n  /**\n   * Defer the `client.connect(transport)` call until the first\n   * `tools/call` reaches this server. Bootstrap registers the server's\n   * tools using {@link McpServerConfig.cachedTools} without touching\n   * the network, taking MCP setup off the critical path of\n   * `agent.run()`. The first invocation pays the connect cost\n   * (~200-500ms typically); every subsequent call reuses the live\n   * client.\n   *\n   * Requires {@link McpServerConfig.cachedTools} — without schemas in\n   * hand there is nothing to advertise to the model, so deferring the\n   * connection has no purpose. Bootstrap rejects the config otherwise.\n   *\n   * **Incompatible with `auth: 'oauth'`**: the OAuth handshake (token\n   * refresh / RFC 9728 metadata discovery) can fail in ways that today\n   * fire `mcp:auth:required` at bootstrap so the host can surface a\n   * login affordance *before* the model commits to calling a tool.\n   * Deferring that to first call means an auth failure surfaces mid-run\n   * as a tool-result error, which the model can't recover from without\n   * a fresh prompt. Bootstrap rejects the combination so the error is\n   * loud and proximate to the misconfiguration. Use OAuth servers\n   * without `lazyConnect` (with `cachedTools` alone, if you want to\n   * skip the `tools/list` round-trip).\n   *\n   * On connect failure (network error, transport refused), the cached\n   * promise is dropped so the next `tools/call` retries. The model\n   * sees the failure as a normal tool error. Subsequent calls remain\n   * eligible to succeed once the upstream is reachable again.\n   */\n  lazyConnect?: boolean\n}\n\n// ---------------------------------------------------------------------------\n// Tool execution\n// ---------------------------------------------------------------------------\n\nexport type ToolExecutionMode = 'sequential' | 'parallel'\n\nexport interface AgentBehavior {\n  /** Tool execution mode (default: 'sequential') */\n  toolExecution?: ToolExecutionMode\n  /**\n   * Max agent loop iterations.\n   *\n   * Default: unlimited (Infinity). The loop runs until the model signals\n   * completion (no tool calls / `end_turn`), the abort signal fires, or this\n   * cap is hit. Set a finite value as a safety net for runaway loops.\n   */\n  maxTurns?: number\n  /** Max tokens per LLM response (default: 16384) */\n  maxTokens?: number\n  /** Thinking token budget — overrides the level-based default when set */\n  thinkingBudget?: number\n  /** JSON Schema for structured output enforcement */\n  schema?: Record<string, unknown>\n  /**\n   * Enable provider prompt caching. When on (default), the provider marks the\n   * system prompt, tools, and the last stable message with cache breakpoints so\n   * the shared prefix is served from cache across turns.\n   *\n   * - Anthropic: `cache_control: { type: 'ephemeral' }` on the last `system`\n   *   content part, the last tool, and the last message content part.\n   * - OpenAI-compatible / OpenRouter: same shape — honored by Anthropic-backed\n   *   OpenRouter routes and by Gemini; ignored (no-op) by providers that cache\n   *   automatically (OpenAI, DeepSeek, Grok, Groq, Moonshot).\n   *\n   * Usage is surfaced via `TurnUsage.cacheRead` / `TurnUsage.cacheCreation`.\n   *\n   * Default: `true`.\n   */\n  cache?: boolean\n  /**\n   * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`\n   * across a turn's tool results exceeds this value, the loop injects a\n   * synthetic user message instructing the model to summarize before calling\n   * more tools, and fires the `budget:exceeded` hook.\n   *\n   * Measured **post-`tool:transform`** so consumer truncation counts toward the\n   * budget. Off by default (undefined / `0` disables the check). A reasonable\n   * starting value for OSS-model integrations is `32768`.\n   */\n  toolOutputBudget?: number\n  /**\n   * Deduplicate identical re-reads of the same file in `read_file`. When the\n   * model re-reads a file with the same slice and the bytes haven't changed\n   * since the last read in this session, the tool returns a short stub\n   * instead of re-emitting the full content. Pairs with the read-before-edit\n   * guard in `edit` / `multi_edit`.\n   *\n   * Requires a session (set via `createSession()`); without one, the flag is\n   * a no-op since per-session state has nowhere to live.\n   *\n   * Default: `true`.\n   */\n  dedupReads?: boolean\n  /**\n   * Taper the thinking budget over the course of a run. Late turns are\n   * usually checkpoint / cleanup work where reasoning rarely pays for\n   * itself; early turns benefit most. Two forms:\n   *\n   * - **Struct** — geometric decay starting after `afterTurn`, multiplying by\n   *   `factor` each subsequent turn, clamped to `floor`. Example\n   *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:\n   *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.\n   * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;\n   *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).\n   *\n   * No-op when `thinkingBudget` is unset. Honored by every provider that\n   * respects `thinkingBudget` (anthropic explicit-budget `enabled` path,\n   * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).\n   *\n   * Default: `undefined` (no decay).\n   */\n  thinkingDecay?: { afterTurn: number, factor: number, floor: number } | ((runTurn: number, baseBudget: number) => number)\n  /**\n   * Per-tool soft call budget for this run. Keyed by **canonical** tool name.\n   * On the first call after the run-cumulative dispatched count for that tool\n   * reaches `max`, the framework fires `onExceed`:\n   *\n   * - `'steer'` (default) — let the call execute, but emit a synthetic user\n   *   message after the turn that nudges the model away from re-calling the\n   *   tool. Reuses the existing post-turn steer pathway used by\n   *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.\n   * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a\n   *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with\n   *   `mode: 'block'`.\n   * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the\n   *   steering / refusal text and chooses the mode dynamically.\n   *\n   * Counts include both real dispatches and dedup substitutes (Z19 hits).\n   * Excludes calls already blocked by an earlier gate (skill allow-list,\n   * consumer hook). Tool dispatched by spawned subagents has its own per-run\n   * counter — child counts never charge the parent.\n   *\n   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).\n   *\n   * Atomic in parallel mode: the middleware tracks its own per-tool\n   * approval counter, incremented synchronously at gate-time. A\n   * 4-call parallel batch against `max: 2` will let the first 2 through\n   * and refuse the rest, even though the loop's `runToolCounts` only\n   * propagates between calls (not within a single batch's gate fan-out).\n   *\n   * Default: `undefined` (no budget enforcement).\n   */\n  toolBudgets?: Record<string, {\n    max: number\n    onExceed?: 'steer' | 'block' | ((ctx: {\n      tool: string\n      count: number\n      max: number\n    }) => { mode: 'steer' | 'block', message: string })\n  }>\n  /**\n   * Generic per-tool argument deduplication. Keyed by the tool's **canonical**\n   * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.\n   *\n   * **Hasher contract** — three return values, three meanings:\n   *\n   * | Return                  | Meaning                                                                |\n   * |-------------------------|------------------------------------------------------------------------|\n   * | a non-empty string      | Cache key for this call. Equal keys (most-recent-only, this session)   |\n   * |                         | replay the prior recorded result without re-dispatching the tool.      |\n   * | `undefined`             | **Skip dedup for this call.** The tool runs normally; nothing recorded.|\n   * | `''` / non-string       | Treated identically to `undefined` (defensive: no dedup, no error).    |\n   *\n   * The `undefined` opt-out is the way to say *\"this specific call is not\n   * cacheable\"* (timestamps in input, randomness baked in, debug flags). It\n   * is **not** the same as `JSON.stringify(input)` — that would dedup against\n   * the verbatim input. Pick one explicitly:\n   *\n   * ```ts\n   * // Always cache by full input — every identical re-call dedups.\n   * dedupTools: { todowrite: input => JSON.stringify(input) }\n   *\n   * // Cache by a normalized subset; non-cacheable shapes opt out.\n   * dedupTools: {\n   *   execute_sql: (input) => {\n   *     const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined\n   *     if (!q || q.includes('now()') || q.includes('random()')) return undefined\n   *     return q\n   *   },\n   * }\n   * ```\n   *\n   * On a hit, the previously-recorded result is replayed as the tool_result\n   * without dispatching the tool. The substitution flows through `tool:gate`\n   * `result` (Z20), so `tool:after` and `tool:transform` still fire.\n   *\n   * Requires a session (`createSession()`); without one, the map is a silent\n   * no-op since per-session state has nowhere to live. Tools with side\n   * effects or non-deterministic outputs (network, time, randomness) MUST\n   * NOT be listed — there is no safety net beyond the consumer's hasher.\n   *\n   * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).\n   * Parallel mode (`toolExecution: 'parallel'`, the default) sees calls in\n   * the SAME assistant turn race against each other — none can dedup against\n   * a sibling that started in the same batch. Sequential mode honors order\n   * within a turn.\n   *\n   * **Cache policy**: only the most recent `(hash, result)` per tool is\n   * retained. Interleaved patterns (input A, input B, input A) miss on the\n   * second A because B overwrote it. Sufficient for the common spam-the-\n   * same-call loop; consumers needing a richer cache should hook\n   * `tool:gate` directly.\n   *\n   * Default: `undefined` (no per-tool dedup).\n   */\n  dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>\n  /**\n   * Require `read_file` before `edit` / `multi_edit` on the same path, and\n   * reject edits when the file has changed on disk since the last read in\n   * this session. Eliminates the silent-corruption failure mode where a\n   * model \"remembers\" stale content and applies a substring edit against\n   * bytes that have moved.\n   *\n   * Requires a session. Off by default; turn it on for stricter eval-grade\n   * runs where silent edit corruption would invalidate the result.\n   *\n   * Default: `false`.\n   */\n  requireReadBeforeEdit?: boolean\n  /**\n   * Client-side context compaction strategy. Use this for non-Anthropic\n   * providers (OSS via cerebras / openai-compat / openrouter) that don't\n   * have a server-side equivalent. Anthropic users should prefer the\n   * server-side `context-management-2025-06-27` beta — see\n   * `AnthropicParams.contextManagement`.\n   *\n   * - `'off'` (default) — no client-side compaction.\n   * - `'tail'` — when total tool-output bytes in the persisted history\n   *   exceed `compactThreshold`, replace older `tool_result` outputs with a\n   *   short stub, keeping the newest `compactKeepTurns` turns intact. The\n   *   compaction is applied to the wire-level message list only; the\n   *   underlying session turns are not modified.\n   *\n   * Default: `'off'`.\n   */\n  compactStrategy?: 'off' | 'tail'\n  /**\n   * Soft byte threshold that triggers tail compaction when\n   * `compactStrategy === 'tail'`. Counts the post-`context:transform` bytes\n   * of `tool_result` outputs across all messages. Default: `131_072` (128\n   * KiB). Ignored when compaction is off.\n   */\n  compactThreshold?: number\n  /**\n   * Number of trailing turns to leave untouched during tail compaction. The\n   * most-recent `compactKeepTurns` user/assistant messages are not eligible\n   * for elision so the model keeps the freshest tool context. Default: `4`.\n   */\n  compactKeepTurns?: number\n  /**\n   * Prefix every line of `read_file` output with its 1-indexed line number\n   * followed by a tab (`<N>\\t<content>`) — the compact `cat -n`-style\n   * format Claude Code emits. The `edit` tool strips the prefix from\n   * `old_string` / `new_string` so the model can paste back a numbered\n   * chunk verbatim without breaking the match.\n   *\n   * Set `false` to opt out — useful for callers piping `read_file` into\n   * downstream parsers that don't recognize the prefix. Per-call\n   * `read_file({ lineNumbers: false })` overrides this default.\n   *\n   * Default: `true`.\n   */\n  readLineNumbers?: boolean\n  /**\n   * Replace older `read_file` `tool_result` blocks with a short stub when\n   * a successful `edit` / `multi_edit` / `write_file` later in the same\n   * run modified the same path. The replacement is applied to the\n   * wire-level message list only — persisted session turns keep the\n   * original content.\n   *\n   * Eliminates the common waste pattern where the model carries the\n   * pre-edit file body forward across many turns \"in case it needs it\".\n   * Pairs cleanly with `compactStrategy: 'tail'`: stale reads shrink\n   * first, then the byte-threshold compaction fires if anything's left.\n   *\n   * Detection is conservative — only triggers when the corresponding\n   * tool_result confirms success (`Edited …`, `Created …`, `Updated …`).\n   * Failed edits and `No change needed` write_file calls do NOT\n   * invalidate prior reads.\n   *\n   * Default: `false`.\n   */\n  elideStaleReads?: boolean\n  /**\n   * Tool disclosure strategy. Controls whether the model sees every tool's\n   * full `inputSchema` in its tool list every turn (\"eager\") or whether MCP\n   * tools are advertised as a name+description catalog in the system prompt\n   * and only get full schemas after being surfaced via the `tool_search`\n   * native tool (\"lazy\" / progressive disclosure).\n   *\n   * Native tools (those passed to `createAgent({ tools })`) and skill tools\n   * are always eager — they are core to the agent and cheap. Only MCP tools\n   * are eligible for lazy disclosure.\n   *\n   * When `'lazy'`, the agent:\n   * - Appends a `<searchable_tools>` section to the system prompt listing\n   *   every MCP tool by `name` + `description` only (no `inputSchema`).\n   * - Auto-injects a `tool_search` native tool (opt out via\n   *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on\n   *   demand. Surfaced tools persist for the rest of the run.\n   * - Rebuilds the wire-level tool list each turn, appending newly-unlocked\n   *   tools at the end so the prefix-cache breakpoint advances cleanly.\n   *\n   * Trade-off: every `tool_search` invocation expands the tool list and\n   * invalidates the tool-list cache breakpoint for one turn. With many\n   * MCP servers, the savings on cold turns (fewer schemas in context) are\n   * substantial; with one tiny MCP server, the overhead may not pay back.\n   *\n   * Default: `'eager'`.\n   */\n  toolDisclosure?: 'eager' | 'lazy'\n  /**\n   * Fine-grained config for the `tool_search` tool auto-injected when\n   * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.\n   *\n   * - `tool: false` — opt out of the auto-injection entirely. Use when the\n   *   host wants to ship a custom discovery tool. Note that the catalog\n   *   text drops the call-to-action prose in this case so the model isn't\n   *   pointed at a non-existent tool.\n   * - `limit` — default cap on results returned per `tool_search` call when\n   *   the model omits the parameter. Default: `20`.\n   *\n   * Note on host-defined `tool_search`: a tool the host registers under the\n   * name `tool_search` (or under any alias whose canonical is `tool_search`)\n   * will shadow the auto-injected one — the catalog text will point at the\n   * host's wire name, but driving the unlock flow requires either using\n   * `createToolSearchTool({ catalog, unlocked })` from `tools/tool-search`\n   * (which internally mutates the unlock set) or fully opting out via\n   * `toolSearch.tool: false` and treating discovery as a host-side concern.\n   * A bare host tool that doesn't touch the unlock set will not advance the\n   * lazy disclosure state and the hard gate will keep refusing lazy calls.\n   *\n   * Default: `undefined` (auto-inject with the default limit).\n   */\n  toolSearch?: {\n    tool?: false\n    limit?: number\n  }\n  /**\n   * Persist large `tool_result` outputs to disk and replace the in-message\n   * content with a `<persisted-output>` stub (preview + filesystem path).\n   * When the post-`tool:transform` byte size of a tool's result exceeds\n   * this threshold, the framework writes the full payload to\n   * `<persistDir>/<callId>.txt` and substitutes a fixed-format stub so the\n   * model sees a 2 KiB preview plus the path it can `read_file`.\n   *\n   * The substitution happens at emit time (just after `tool:transform` runs)\n   * and the stub flows into `session.turns` directly — so every subsequent\n   * turn re-emits the same bytes, keeping the prompt-cache prefix stable.\n   *\n   * Set `0` / `undefined` to disable. Built-in chat profiles default to\n   * `8192`. Tools listed in {@link AgentBehavior.persistExcludeTools} bypass\n   * regardless of size — typically because their output is intentionally\n   * short or persisting would be circular (e.g. `read_file`).\n   *\n   * Requires {@link AgentBehavior.persistDir} to be set; without a target\n   * directory the framework silently skips persistence (no throw, no\n   * substitution) since there's nowhere to write the blob.\n   *\n   * Default: `undefined` (off).\n   */\n  persistThreshold?: number\n  /**\n   * Canonical tool names to exclude from disk persistence regardless of\n   * output size. The framework bypasses persistence for any tool whose\n   * canonical name appears in this list — useful for tools whose results\n   * are intentionally part of the prompt (`skills_use`), short envelopes\n   * (`tool_search`, `present_plan`, `ask_user`), or where persistence\n   * would be circular (`read_file`, whose pagination already serves the\n   * same use case).\n   *\n   * Default: `undefined` (no exclusions). The chat-layer built-in profiles\n   * set their own list — see `src/chat/agents.ts`.\n   */\n  persistExcludeTools?: readonly string[]\n  /**\n   * Directory under which persisted tool-result blobs land. Each call's\n   * payload is written to `<persistDir>/<callId>.txt` (one file per\n   * `tool_use` id, atomic via write-then-rename).\n   *\n   * The chat layer resolves this to `<userDir>/tool-results/<sessionId>/`\n   * at session activation; SDK consumers pass an absolute path. Required\n   * when {@link AgentBehavior.persistThreshold} is non-zero — when unset\n   * the framework treats persistence as disabled.\n   *\n   * Default: `undefined`.\n   */\n  persistDir?: string\n}\n\n// ---------------------------------------------------------------------------\n// Prompt parts (multimodal input)\n// ---------------------------------------------------------------------------\n\n/**\n * One block of a multimodal user prompt.\n *\n * `agent.run({ prompt })` accepts either a plain string (treated as a single\n * text part) or an array of these parts for multimodal inputs.\n *\n * `document` parts are routed per provider: PDF-style mime types are sent as\n * native document blocks when the provider supports them; text documents are\n * inlined as text with an attachment header. Providers that cannot handle an\n * image or document throw early.\n */\nexport type PromptPart\n  = | PromptTextPart\n    | PromptImagePart\n    | PromptDocumentPart\n\nexport interface PromptTextPart {\n  type: 'text'\n  text: string\n}\n\nexport interface PromptImagePart {\n  type: 'image'\n  /** IANA media type (e.g. `image/png`, `image/jpeg`) */\n  mediaType: string\n  /** Base64-encoded payload */\n  data: string\n  /** Optional display name */\n  name?: string\n}\n\nexport interface PromptDocumentPart {\n  type: 'document'\n  /** IANA media type (e.g. `application/pdf`, `text/plain`) */\n  mediaType: string\n  /** Either a base64-encoded payload (`encoding: 'base64'`) or raw text (`encoding: 'text'`) */\n  data: string\n  encoding: 'base64' | 'text'\n  /** Optional display name used in attachment headers */\n  name?: string\n}\n\n// ---------------------------------------------------------------------------\n// Canonical message format (used throughout the agent system)\n// ---------------------------------------------------------------------------\n\n/**\n * A single block of structured tool-result content.\n *\n * MCP servers can return a mix of text, image, resource, and audio blocks. Tools\n * return `string` for the common text-only case or `ToolResultContent[]` when they\n * need to preserve non-text content (e.g. screenshots from a browser MCP).\n *\n * Providers that support native multi-part tool results (Anthropic, OpenAI Codex via\n * pi-ai) route image blocks into their wire format verbatim; OpenAI-compat providers\n * route them via a companion-user-message fallback when the underlying model/endpoint\n * does not accept images inside tool-role messages.\n */\nexport type ToolResultContent\n  = | ToolResultTextContent\n    | ToolResultImageContent\n\nexport interface ToolResultTextContent {\n  type: 'text'\n  text: string\n}\n\nexport interface ToolResultImageContent {\n  type: 'image'\n  /** IANA media type (e.g. `image/png`, `image/jpeg`) */\n  mediaType: string\n  /** Base64-encoded payload */\n  data: string\n}\n\n/**\n * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single\n * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.\n *\n * Use at UI boundaries where a string is required; providers that understand\n * structured content should route the array through without flattening.\n */\nexport function toolResultToText(content: string | ToolResultContent[]): string {\n  if (typeof content === 'string')\n    return content\n  return content\n    .map((block) => {\n      if (block.type === 'text')\n        return block.text\n      return `[image: ${block.mediaType} — ${block.data.length} b64 bytes]`\n    })\n    .join('\\n')\n}\n\n/**\n * Approximate **wire payload size** of a tool output, in bytes.\n *\n * - Plain text: UTF-8 byte length.\n * - Structured content: text blocks contribute their UTF-8 byte length; image\n *   blocks contribute their **base64 character length** — a proxy for the\n *   serialized request-body footprint, NOT for tokens. Vision encoders\n *   tokenize decoded pixels (geometry-dependent; e.g. Anthropic ≈ `w·h/750`,\n *   OpenAI ≈ 85 + 170/tile), which has no meaningful relationship to base64\n *   length.\n *\n * Used by the agent loop to populate `outputBytes` on `tool:after`,\n * `tool:transform`, `mcp:tool:after`, and `mcp:tool:transform` hooks so\n * consumers can size-budget tool output without re-counting bytes themselves.\n * Suitable for byte-budget heuristics (`toolOutputBudget`, tail compaction);\n * NOT a substitute for provider-side context-window accounting — defer to\n * server-side context management (e.g. Anthropic's `context-management-*`\n * beta) when token accuracy matters.\n */\nexport function toolOutputByteLength(content: string | ToolResultContent[]): number {\n  if (typeof content === 'string')\n    return Buffer.byteLength(content)\n  let total = 0\n  for (const block of content) {\n    if (block.type === 'text')\n      total += Buffer.byteLength(block.text)\n    else\n      total += block.data.length\n  }\n  return total\n}\n\nexport type SessionContentBlock\n  = | { type: 'text', text: string }\n    | { type: 'image', mediaType: string, data: string }\n    | { type: 'tool_call', id: string, name: string, input: Record<string, unknown> }\n    | {\n      type: 'tool_result'\n      callId: string\n      /**\n       * Tool output — either a plain string (text-only, the common case) or a structured\n       * array of content blocks (text + image for multimodal tools such as screenshots).\n       */\n      output: string | ToolResultContent[]\n      isError?: boolean\n    }\n    | {\n      type: 'thinking'\n      text: string\n      signature?: string\n      /**\n       * Provider that minted `signature`. Signatures are provider-bound (Anthropic\n       * HMAC vs. OpenAI `encrypted_content`) and are dropped on cross-provider\n       * hops to avoid 400s. Unset means legacy/unknown — forwarded as-is.\n       */\n      signatureProducer?: 'anthropic' | 'openai'\n    }\n    | { type: 'redacted_thinking', data: string }\n    | {\n      /**\n       * Opaque round-trip envelope for reasoning state minted by an OpenAI-compat\n       * gateway (currently OpenRouter). The gateway expects its own\n       * `reasoning_details` array echoed back verbatim on the next turn so the\n       * upstream model can resume an extended-reasoning chain across tool calls.\n       *\n       * Stored opaquely because the items are provider-bound (Anthropic HMAC\n       * signatures, OpenAI `encrypted_content`, model-specific summary formats\n       * — all flowing through the gateway's normalized envelope).\n       */\n      type: 'provider_reasoning'\n      producer: 'openrouter'\n      details: unknown[]\n      /**\n       * Model id that produced the details. Reasoning is bound to a specific\n       * upstream route — a model switch on the next turn invalidates the\n       * embedded signatures, so the sender drops the block on mismatch.\n       */\n      model?: string\n    }\n    | {\n      /**\n       * Compaction marker. Inserted by `compactConversation()` to replace a\n       * prefix of turns with an LLM-generated summary.\n       *\n       * The marker lives in `session.turns` and renders in the transcript —\n       * the user can still scroll back to see the original turns. From the\n       * agent loop's wire-level perspective, every turn whose id appears in\n       * `replacesTurnIds` is dropped, and this block's `summary` text is\n       * sent to the model as a single user message in their place.\n       *\n       * The marker turn carries `role: 'user'` so it sits naturally at a\n       * conversational boundary. Only the latest `compact-summary` block in\n       * the session is honored — earlier markers are subsumed by later\n       * ones (their `replacesTurnIds` are a strict prefix).\n       */\n      type: 'compact-summary'\n      /** Turn ids the summary replaces, in chronological order. */\n      replacesTurnIds: readonly string[]\n      /** The summary text sent to the model in place of the elided turns. */\n      summary: string\n      /** Model id used to produce the summary. */\n      model: string\n      /** Token usage from the summary call. */\n      usage: TurnUsage\n      /** Unix-ms when compaction completed. */\n      compactedAt: number\n    }\n\nexport interface SessionMessage {\n  role: 'user' | 'assistant'\n  content: SessionContentBlock[]\n}\n\nexport interface SessionTurn {\n  /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */\n  id: string\n  /** Run that produced this turn (e.g. 'run_1') */\n  runId?: string\n  role: 'user' | 'assistant' | 'system'\n  content: SessionContentBlock[]\n  /** Token usage — only present on assistant turns */\n  usage?: TurnUsage\n  /** Unix timestamp (Date.now()) when the turn was created */\n  createdAt: number\n}\n\n// ---------------------------------------------------------------------------\n// Agent run options\n// ---------------------------------------------------------------------------\n\n/**\n * Per-run hook registrations. Each entry can be a single handler or an array of handlers.\n * Keys are `AgentHooks` event names (loose-typed here to avoid a circular import; agent.ts\n * narrows it to the strongly-typed map).\n */\nexport type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>\n\nexport interface AgentRunOptions {\n  model?: string\n  /**\n   * User prompt. Optional when resuming a session with existing turns.\n   *\n   * Accepts either a plain string (single text part) or an array of `PromptPart`s for\n   * multimodal inputs (text, images, documents). See {@link PromptPart}.\n   */\n  prompt?: string | PromptPart[]\n  system?: string\n  thinking?: ThinkingLevel\n  /** Abort signal — when triggered, the agent stops after the current turn */\n  signal?: AbortSignal\n  /** Behavior overrides for this run (overrides agent defaults) */\n  behavior?: AgentBehavior\n  /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */\n  tools?: Record<string, ToolDef>\n  /**\n   * Per-run hook registrations. Each hook is attached before the run starts and\n   * detached in a finally block so handlers never leak across runs.\n   *\n   * Accepts either a single handler or an array (all handlers register).\n   */\n  hooks?: RunHookMap\n  /**\n   * Parent run id. Populated automatically by the `spawn` tool when the child\n   * shares the parent's session; recorded on the resulting `SessionRun` so the\n   * parent↔child run tree can be reconstructed from a persisted session.\n   */\n  parentRunId?: string\n  /**\n   * Zero-based subagent depth. 0 = top-level `agent.run()`, 1 = first-level\n   * child spawned by a parent agent, and so on. Used by the spawn tool to\n   * enforce `maxDepth` and to stamp `child:*` forwarded hook payloads.\n   */\n  depth?: number\n}\n\n// ---------------------------------------------------------------------------\n// Agent stats\n// ---------------------------------------------------------------------------\n\n/**\n * Reason the provider gave for stopping the turn.\n *\n * - `'stop'` — natural turn end (`end_turn` / `stop_sequence`).\n * - `'tool-calls'` — model emitted tool_use blocks.\n * - `'length'` — `max_tokens` reached, or (Anthropic 4.6+) the response bumped\n *   against the model's context window mid-stream\n *   (`model_context_window_exceeded`). The partial response is preserved; the\n *   loop emits this reason so consumers can prune/retry.\n * - `'content-filter'` — model refused.\n * - `'pause'` — Anthropic `pause_turn`: a server-side mid-turn pause for very\n *   long thinking. The loop continues with a synthetic \"Please continue.\"\n *   user message rather than terminating; consumers see the pause via this\n *   finish reason on the prior assistant turn.\n * - `'error'` — provider classified the turn as failed.\n * - `'other'` — unknown / unmapped.\n */\nexport type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'pause' | 'error' | 'other'\n\nexport interface TurnUsage {\n  input: number\n  output: number\n  /** Tokens written to cache (Anthropic) */\n  cacheCreation?: number\n  /** Tokens read from cache (Anthropic) */\n  cacheRead?: number\n  /** Thinking/reasoning tokens used */\n  thinking?: number\n  /**\n   * Cost in USD for this turn. Provider-reported when available\n   * (OpenRouter, OpenAI via pi-ai); otherwise estimated from `modelId` ×\n   * pi-ai's bundled price registry by `fillEstimatedCost` in\n   * `src/providers/cost.ts`. Absent only when neither path could resolve\n   * a price (unknown / unbundled model).\n   */\n  cost?: number\n  /**\n   * Why the model stopped this turn. Providers normalize native stop reasons to this union.\n   * Absent when the provider did not surface a reason (e.g. mock turns).\n   */\n  finishReason?: TurnFinishReason\n  /**\n   * The model ID the provider ultimately used. May differ from the requested model when the\n   * provider remaps aliases. Absent for providers that do not echo a model ID.\n   */\n  modelId?: string\n}\n\nexport interface AgentStats {\n  /**\n   * Cumulative input tokens across the parent agent loop **and** every\n   * recursively-spawned sub-agent. Use this for billing / token-ledger\n   * consumption.\n   */\n  totalIn: number\n  /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */\n  totalOut: number\n  /**\n   * Cumulative cache-read tokens across the parent agent loop and every\n   * recursively-spawned sub-agent. Surfaced at the top level (rather than\n   * only per-`TurnUsage`) because Anthropic prices cache reads at a separate\n   * line-item rate from regular input — billing-correct cost computation\n   * needs this number directly. Always `0` for providers that don't report\n   * cache usage.\n   */\n  totalCacheRead: number\n  /**\n   * Cumulative cache-creation tokens across the parent agent loop and every\n   * recursively-spawned sub-agent. Same rationale as\n   * {@link AgentStats.totalCacheRead} — separate Anthropic billing rate.\n   * Always `0` for providers that don't report cache usage.\n   */\n  totalCacheCreation: number\n  /**\n   * Number of parent agent-loop turns. Children's turn counts live under\n   * `children[].stats.turns` and are NOT folded in here — a single \"turns\"\n   * number for the whole tree would conflate two different measures\n   * (parent-loop iterations vs. tree-wide tool-call rounds).\n   *\n   * Tree-wide turn count: `flattenTurns(stats).length`.\n   */\n  turns: number\n  /**\n   * Wall-clock duration of the top-level `agent.run()` call, in milliseconds.\n   * Children run during parent tool calls so this naturally subsumes child\n   * wall time — sequential children inflate it, parallel children compress\n   * into the parent's window.\n   */\n  elapsed: number\n  /**\n   * Per-turn usage breakdown for the **parent loop only**. Children's per-turn\n   * usages live under `children[].stats.turnUsage`. Use {@link flattenTurns}\n   * to walk the full tree.\n   */\n  turnUsage?: TurnUsage[]\n  /**\n   * Cumulative cost in USD — parent loop plus every recursively-spawned\n   * sub-agent. Sums per-turn `TurnUsage.cost` reported by the provider.\n   * Absent when neither parent nor any descendant reported a non-zero cost.\n   */\n  cost?: number\n  /** Stats from child agents spawned during this run, in completion order. Recursive. */\n  children?: ChildRunStats[]\n  /** Structured output from schema enforcement (only present when behavior.schema is set) */\n  output?: Record<string, unknown>\n  /**\n   * Milliseconds from the start of `agent.run()` to the first observable signal from the\n   * provider (first `stream:text`, `stream:thinking`, or `tool:before` event).\n   *\n   * Absent when the run produced no observable signals (e.g. aborted before any stream event).\n   */\n  timeTillFirstTokenMs?: number\n}\n\nexport interface ChildRunStats {\n  id: string\n  task: string\n  /**\n   * The child agent's full {@link AgentStats}. Cumulative for that child's\n   * own subtree (child loop + its grandchildren). Do **not** sum\n   * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level\n   * totals — `agent.run()`'s return value is the canonical cumulative root.\n   */\n  stats: AgentStats\n  /**\n   * Subagent depth when this child ran. 1 = direct child of the top-level\n   * agent, 2 = grandchild, etc. Useful for telemetry that wants to group\n   * runs by depth.\n   */\n  depth?: number\n  /**\n   * Terminal state of the child run. `'completed'` is the default. Exposed so\n   * a parent reading `stats.children` can distinguish aborted/timed-out\n   * children without re-parsing the returned string.\n   */\n  status?: 'completed' | 'aborted' | 'timeout' | 'error'\n  /**\n   * Final structured output when the child was run with `behavior.schema`.\n   * Mirrors `AgentStats.output` but is surfaced here so the parent can read\n   * it without peeking at the nested `stats` bag.\n   */\n  output?: Record<string, unknown>\n}\n\n// ---------------------------------------------------------------------------\n// Hook context types\n// ---------------------------------------------------------------------------\n\n/**\n * Base context for tool execution hooks.\n *\n * `name` is the canonical tool identity — the spec name registered on the agent (or the\n * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.\n *\n * `displayName` is the outward-facing name — the alias surfaced to the LLM when\n * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.\n * UI/telemetry adapters should emit `displayName`.\n *\n * Canonical vs. alias matters on session resume: `session.turns` persists canonical\n * names only, so renaming an alias cannot desync history.\n */\nexport interface ToolHookContext {\n  turnId: string\n  callId: string\n  /** Canonical tool name (spec name). Stable across alias-map changes. */\n  name: string\n  /** Aliased (wire) name — equal to `name` when no alias is defined. */\n  displayName: string\n  input: Record<string, unknown>\n}\n\n/**\n * Base context for MCP tool hooks.\n *\n * `tool` is the native tool name on the MCP server. `server` is the configured server\n * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.\n *\n * `displayName` equals the canonical namespaced name unless the agent has aliased\n * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the\n * alias that the LLM sees.\n */\nexport interface McpToolHookContext {\n  turnId: string\n  callId: string\n  server: string\n  tool: string\n  /** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */\n  displayName: string\n  input: Record<string, unknown>\n}\n\n/** Base context for session hooks */\nexport interface SessionHookContext {\n  sessionId: string\n}\n\n/** Base context for spawn hooks */\nexport interface SpawnHookContext {\n  id: string\n  task: string\n  /**\n   * Subagent depth for the spawn. 1 = direct child of the top-level agent.\n   * Present on spawn:before/complete/error. Absent for grandchild spawns that\n   * bubble through `child:*` events (which carry their own `depth`).\n   */\n  depth?: number\n}\n\n/** Context for stream hooks */\nexport interface StreamHookContext {\n  turnId: string\n}\n\n/** Context for OAuth refresh hooks */\nexport interface OAuthRefreshHookContext {\n  provider: string\n  providerId: string\n  source: 'params' | 'file'\n  previousCredentials: Record<string, unknown> & { access: string, refresh: string, expires: number }\n  credentials: Record<string, unknown> & { access: string, refresh: string, expires: number }\n}\n\nexport type SessionEndStatus = 'completed' | 'aborted' | 'error'\n"],"mappings":";;;;;;;;;AAqnBA,SAAgB,iBAAiB,SAA+C;CAC9E,IAAI,OAAO,YAAY,UACrB,OAAO;CACT,OAAO,QACJ,KAAK,UAAU;EACd,IAAI,MAAM,SAAS,QACjB,OAAO,MAAM;EACf,OAAO,WAAW,MAAM,UAAU,KAAK,MAAM,KAAK,OAAO;GACzD,CACD,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;AAsBf,SAAgB,qBAAqB,SAA+C;CAClF,IAAI,OAAO,YAAY,UACrB,OAAO,OAAO,WAAW,QAAQ;CACnC,IAAI,QAAQ;CACZ,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,SAAS,QACjB,SAAS,OAAO,WAAW,MAAM,KAAK;MAEtC,SAAS,MAAM,KAAK;CAExB,OAAO"}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { a as ExecutionHandle, i as ExecutionContext, n as ContextType, o as SpawnConfig, r as ExecResult, t as ContextCapabilities } from "./types-Ce78ds4h.js";
 import { t as SandboxProvider } from "./index-BiO_5Hm4.js";
-import { A as SessionStore, At as SpawnHookContext, Bt as toolOutputByteLength, C as SkillResource, Ct as PromptTextPart, D as Session, Dt as SessionHookContext, E as CreateSessionOptions, Et as SessionEndStatus, Ft as ToolResultContent, G as ProviderCapabilities, Gt as AgentToolNotAllowedError, Ht as AgentAbortedError, It as ToolResultImageContent, J as ToolCall, Jt as ClassifiedErrorKind, K as StreamCallbacks, Kt as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, Lt as ToolResultTextContent, Mt as ThinkingLevel, N as RemoteStoreOptions, Nt as ToolExecutionMode, O as SessionData, Ot as SessionMessage, Pt as ToolHookContext, Q as OpenRouterParams, Rt as TurnFinishReason, St as PromptPart, T as SkillsConfig, Tt as SessionContentBlock, Ut as AgentContextExceededError, Vt as toolResultToText, W as Provider, Wt as AgentProviderError, X as ToolSpec, Xt as matchesContextExceeded, Y as ToolResult, Z as TurnResult, _t as McpToolHookContext, b as ToolMap, bt as PromptDocumentPart, ct as CerebrasParams, ft as AgentBehavior, gt as McpServerConfig, ht as ChildRunStats, i as AgentOptions, jt as StreamHookContext, k as SessionRun, kt as SessionTurn, mt as AgentStats, ot as OpenAIParams, p as McpConnection, pt as AgentRunOptions, q as StreamOptions, qt as ClassifiedError, r as AgentHooks, t as Agent, ut as AnthropicParams, v as ToolContext, wt as RunHookMap, x as SkillConfig, xt as PromptImagePart, y as ToolDef, yt as OAuthRefreshHookContext, zt as TurnUsage } from "./agent-CGQajqtC.js";
-import { I as ModelUsage, L as flattenTurns, R as statsByModel, _ as ChildAgent, f as ValidationResult, j as InteractionToolOptions, t as Preset, v as SpawnToolOptions, y as SpawnToolState } from "./index-DwbcFBr_.js";
+import { A as SessionStore, At as SpawnHookContext, Bt as toolOutputByteLength, C as SkillResource, Ct as PromptTextPart, D as Session, Dt as SessionHookContext, E as CreateSessionOptions, Et as SessionEndStatus, Ft as ToolResultContent, G as ProviderCapabilities, Gt as AgentToolNotAllowedError, Ht as AgentAbortedError, It as ToolResultImageContent, J as ToolCall, Jt as ClassifiedErrorKind, K as StreamCallbacks, Kt as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, Lt as ToolResultTextContent, Mt as ThinkingLevel, N as RemoteStoreOptions, Nt as ToolExecutionMode, O as SessionData, Ot as SessionMessage, Pt as ToolHookContext, Q as OpenRouterParams, Rt as TurnFinishReason, St as PromptPart, T as SkillsConfig, Tt as SessionContentBlock, Ut as AgentContextExceededError, Vt as toolResultToText, W as Provider, Wt as AgentProviderError, X as ToolSpec, Xt as matchesContextExceeded, Y as ToolResult, Z as TurnResult, _t as McpToolHookContext, b as ToolMap, bt as PromptDocumentPart, ct as CerebrasParams, ft as AgentBehavior, gt as McpServerConfig, ht as ChildRunStats, i as AgentOptions, jt as StreamHookContext, k as SessionRun, kt as SessionTurn, mt as AgentStats, ot as OpenAIParams, p as McpConnection, pt as AgentRunOptions, q as StreamOptions, qt as ClassifiedError, r as AgentHooks, t as Agent, ut as AnthropicParams, v as ToolContext, wt as RunHookMap, x as SkillConfig, xt as PromptImagePart, y as ToolDef, yt as OAuthRefreshHookContext, zt as TurnUsage } from "./agent-CYpPKn5Z.js";
+import { I as ModelUsage, L as flattenTurns, R as statsByModel, _ as ChildAgent, f as ValidationResult, j as InteractionToolOptions, t as Preset, v as SpawnToolOptions, y as SpawnToolState } from "./index-D-cTScN3.js";
 export { type Agent, AgentAbortedError, type AgentBehavior, AgentContextExceededError, type AgentHooks, type AgentOptions, AgentProviderError, type AgentRunOptions, type AgentStats, AgentToolNotAllowedError, type AnthropicParams, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, type CerebrasParams, type ChildAgent, type ChildRunStats, type ClassifiedError, type ClassifiedErrorKind, type ContextCapabilities, type ContextType, type CreateSessionOptions, type ExecResult, type ExecutionContext, type ExecutionHandle, type InteractionToolOptions, type McpConnection, type McpServerConfig, type McpToolHookContext, type ModelUsage, type OAuthRefreshHookContext, type OpenAIParams, type OpenRouterParams, type Preset, type PromptDocumentPart, type PromptImagePart, type PromptPart, type PromptTextPart, type Provider, type ProviderCapabilities, type RemoteStoreOptions, type RunHookMap, type SandboxProvider, type Session, type SessionContentBlock, type SessionData, type SessionEndStatus, type SessionHookContext, type SessionMessage, type SessionRun, type SessionStore, type SessionTurn, type SkillConfig, type SkillResource, type SkillsConfig, type SpawnConfig, type SpawnHookContext, type SpawnToolOptions, type SpawnToolState, type StreamCallbacks, type StreamHookContext, type StreamOptions, type ThinkingLevel, type ToolCall, type ToolContext, type ToolDef, type ToolExecutionMode, type ToolHookContext, type ToolMap, type ToolResult, type ToolResultContent, type ToolResultImageContent, type ToolResultTextContent, type ToolSpec, type TurnFinishReason, type TurnResult, type TurnUsage, type ValidationResult, flattenTurns, matchesContextExceeded, statsByModel, toolOutputByteLength, toolResultToText };

package/docs/ARCHITECTURE.md

@@ -90,7 +90,7 @@ flowchart TB
         S2 --> S3["stream:text hook (per chunk)"]
     end
 
-    STREAM -->|error| CATCH["turn:after hook (zero usage)\nRethrow"]
+    STREAM -->|error| CATCH["stream:error hook (raw err)\nturn:after hook (zero usage)\nRethrow"]
     STREAM -->|ok| S4{"Has text?"}
     S4 -->|yes| S5["stream:end hook"]
     S4 -->|no| AFTER
@@ -428,6 +428,7 @@ turn:before                                      ← turn starts
   oauth:refresh                                  ← (when provider supports it)
   stream:thinking (n) / stream:text (n)          ← each streamed chunk
   stream:end                                     ← text complete (if text present)
+  stream:error                                   ← provider rejected before stream:end (omitted on user-initiated aborts)
 turn:after                                       ← always fires (incl. errors); SessionTurn + toolCounts
   tool:gate           [mutable: block, reason, result?]  ← refuse / substitute / run
   tool:unknown        [mutable: result?, suppressError]  ← no toolDef registered
@@ -494,7 +495,7 @@ spawn:error           ← child run threw
 The child's lifecycle also bubbles to the parent hook surface with `childId` + `depth`, so nested UI renders without subscribing on the child:
 
 ```
-child:stream:text / child:stream:thinking / child:stream:end
+child:stream:text / child:stream:thinking / child:stream:end / child:stream:error
 child:tool:gate / child:mcp:tool:gate          ← share the child's ctx — parent mutations propagate
 child:tool:transform                           ← share the child's ctx — parent mutations propagate
 child:tool:before / child:tool:after / child:tool:error

package/docs/CHAT.md

@@ -154,7 +154,7 @@ The table below indexes every named export; sections further down dive into the
 | `store` | Session reconstruction + persisted UI state + transcript view rules — `eventsFromTurns`, `lastContextSizeFromTurns`, `listSessionMeta`, `deriveSessionTitle`, `titleFromTurns`, `selectableTurnIds`, `stripSpawnTokensLine`, `toolCallPreview`, `toolResultText`, `createStateStore`, `loadState`, `saveState`, `isVisible`, `marginTopFor`, `isEditErrorResult`, `isTurnHighlighted`, `sumRunCosts`, `turnSelectionOwnership`, `TuiState`, `StateStoreApi`. |
 | `streaming` | `useStreamBuffer`, `finalizeStreamingMarkdown`, `finalizeStreamingMarkdownForOwner`, `turnContextSize`. Per-owner finalize handles concurrent parent + child streams. |
 | `theme` + `theme-context` | `Theme`, `BUILTIN_THEMES`, `resolveTheme`, `resolveChipColor`, `DEFAULT_THEME`, themes (`CATPPUCCIN_*`, `VAPORWAVE_THEME`), hooks (`useTheme`, `useColors`, `useSelectStyle`, `useSurfaces`, `useSyntaxStyles`). See **Theme**. |
-| `todos` | `todowrite` / `todoread` tool factory — `createTodoTools` (returns a `Preset`), `isTodoTool`, `getTodosForRun`, `setTodosForRun`, `pruneTodosByRun`, `TODOWRITE_TOOL`, `TODOREAD_TOOL`, `TODOS_METADATA_KEY`, `TODO_WRITE_COUNTS_METADATA_KEY`, `TodoItem`, `TodoStatus`, `CreateTodoToolsOptions`. Run-scoped checkpointing keyed on `session.metadata.todosByRun[runId]`; per-run write budget plumbs through `behavior.toolBudgets`; identical-payload dedup lives in the tool body so it's run-scoped (deliberate — see **Todos** below). Compose with `composePresets` or spread. |
+| `todos` | `todowrite` / `todoread` tool factory — `createTodoTools` (returns a `Preset`), `isTodoTool`, `getTodosForRun`, `setTodosForRun`, `pruneTodosByRun`, `TODOWRITE_TOOL`, `TODOREAD_TOOL`, `TODOS_METADATA_KEY`, `TODO_WRITE_COUNTS_METADATA_KEY`, `TodoItem`, `TodoStatus`, `TodosBag`, `CreateTodoToolsOptions`. Persistent task checkpointing — top-level runs share a session-scoped slot (continuity across prompts); subagent runs get their own slot (isolation). Per-run write budget plumbs through `behavior.toolBudgets`; identical-payload dedup lives in the tool body so it resolves against the active slot. Compose with `composePresets` or spread. See **Todos** below. |
 | `tool-formatters` | Per-tool display verbs + curated input formatters — `TOOL_DISPLAY`, `displayNameFor`, `formatToolCall`, `ToolDisplayMeta`, `ToolFormatLine`. Powers the `'formatted'` `toolCallDisplay` view. See **Tool call display**. |
 | `transcript-anchors` | `computeTurnAnchors(items)` → `TranscriptItem[]` — assigns `turn-anchor-<turnId>` ids consumers wire into their renderer's scroll-into-view (TUI: `ScrollBoxRenderable.scrollChildIntoView`; GUI: DOM `element.scrollIntoView`). |
 | `turn-operations` | `deleteTurnSafely`, `truncateTurnsAt`, `turnAsText`, `countNeighbors`. Fork / delete with orphan tool-pair cleanup. |
@@ -357,6 +357,8 @@ interface Settings {
   targetFps: number
   /** Drip-feed streamed text at a smooth cadence (typewriter) instead of in stream bursts. Default: on. */
   smoothStreaming: boolean
+  /** Inline gradient throbber at the transcript tail while a run is streaming. Default: off. */
+  showThrobber: boolean
   /** Skills allowlist. `undefined` = every discovered skill; `[]` = off. */
   enabledSkills?: readonly string[]
   /** MCPs allowlist. Same semantics. */
@@ -476,25 +478,48 @@ const pending = queue[0] ?? null
 
 ## Todos
 
-`todowrite` and `todoread` give the model a place to plan multi-step work and stream progress as it executes. Monolithic-replacement semantics — every `todowrite` overwrites the active run's list in full. State lives at `session.metadata.todosByRun: Record<runId, TodoItem[]>`; runs are isolated by `runId`, so subagent writes never bleed into the parent's slot. Resume is transparent — the latest `tool_result` block in `session.turns` carries the same snapshot the persisted metadata bag does.
+`todowrite` and `todoread` give the model a place to plan multi-step work and stream progress as it executes. Monolithic-replacement semantics — every `todowrite` overwrites the active list in full. State lives at `session.metadata.todos: TodosBag` and is split by run kind:
+
+```ts
+interface TodosBag {
+  /** Top-level slot — shared across runs whose `parentRunId` is unset. */
+  session?: TodoItem[]
+  /** Per-subagent-run slots, keyed by the child run's id. */
+  byRun?: Record<string, TodoItem[]>
+}
+```
+
+The keying rule, given a `runId`:
+
+- **Top-level run** (no `parentRunId`) → `bag.session`. All top-level runs in the same session share this slot, so a list written in one prompt **survives across the next prompt**. The user aborts a run mid-task, sends a follow-up, and `todoread` returns the same list automatically — the model picks up where it left off without a host-side carry-over hook.
+- **Subagent run** (`parentRunId` set) → `bag.byRun[runId]`. Each child has its own slot; parallel children stay isolated from each other and from the parent. Matches Claude Code's TodoWrite v1 keying (`agentId ?? sessionId`).
+
+**Auto-clear on completion**: when every item is `completed`, the slot is wiped to `[]` on write — prevents stale "all done" lists from shadowing the next prompt's context. The model's reply summarizes the close-out (`Marked N items complete — list cleared.`); only the persisted slot is reset. Same rationale as Claude Code's `TodoWriteTool.ts:70`.
+
+**Archive sidecar**: every non-empty write also stashes the list under `bag.archive` (mirroring the active slot's routing — `archive.session` for top-level, `archive.byRun[runId]` for subagents). Empty writes — whether from auto-clear or an explicit `setTodosForRun(session, runId, [])` — **preserve** the archive. UI surfaces (the TUI modal in particular) fall back to it when the live slot is empty so users can still glance back at "what was just completed" until the model writes a new list. The archive is invisible to `todoread` — strictly model-facing reads always go to the live slot.
 
 Public API (re-exported from `zidane/chat`):
 
-- **Factory** — `createTodoTools(options?)` returns a `Preset` carrying `{ tools, behavior }` (tools + per-run write budget). Identical-payload dedup lives inside the tool body (run-scoped) and deliberately does NOT plumb through `behavior.dedupTools`. Compose with `composePresets` or spread it into your agent setup like any other preset.
+- **Factory** — `createTodoTools(options?)` returns a `Preset` carrying `{ tools, behavior }` (tools + per-run write budget). Identical-payload dedup lives inside the tool body (resolves against the active slot per the keying rule above) and deliberately does NOT plumb through `behavior.dedupTools`. Compose with `composePresets` or spread it into your agent setup like any other preset.
 - **Identities** — `TODOWRITE_TOOL`, `TODOREAD_TOOL`, `isTodoTool(name)`.
-- **Metadata accessors** — `getTodosForRun(session, runId)`, `setTodosForRun(session, runId, items)`, `pruneTodosByRun(session)`, `TODOS_METADATA_KEY`, `TODO_WRITE_COUNTS_METADATA_KEY`.
-- **Types** — `TodoItem`, `TodoStatus` (`'pending' | 'in_progress' | 'completed' | 'cancelled'`), `CreateTodoToolsOptions`.
+- **Metadata accessors** — `getTodosForRun(session, runId)`, `setTodosForRun(session, runId, items)`, `getArchivedTodosForRun(session, runId)`, `pruneTodosByRun(session)`, `TODOS_METADATA_KEY`, `TODO_WRITE_COUNTS_METADATA_KEY`. All route through the keying rule above — top-level reads/writes the session slot, subagent reads/writes its own. The archive accessor reads `bag.archive` with the same routing.
+- **UI selectors** (renderer-agnostic, used by the TUI's todo indicator + modal; reusable by any GUI shell):
+  - `useActiveTodos(session) → ActiveTodosState` — React hook. Recomputes on every parent re-render; selector is O(runs + todos) so memoization is unnecessary (and was previously incorrect — `Session.runs` is mutated in place by `completeRun` / `abortRun`).
+  - `selectActiveTodos(session) → ActiveTodosState` — pure selector, identical contract, no React.
+  - `pickActiveRunId(session) → runId | null` — "the run UI surfaces should reflect right now" (latest-running, falling back to most-recently-appended).
+  - `TODO_STATUS_GLYPHS: Record<TodoStatus, string>` — single source of truth for status icons across surfaces.
+- **Types** — `TodoItem`, `TodoStatus` (`'pending' | 'in_progress' | 'completed' | 'cancelled'`), `TodosBag` (`{ session?, byRun?, archive? }`), `TodoTally`, `ActiveTodosState` (carries both `todos` and `archive` so UI surfaces can render the close-out batch after auto-clear), `CreateTodoToolsOptions`.
 
 `CreateTodoToolsOptions`:
 
 | Option | Default | Notes |
 |---|---|---|
 | `maxItems` | `100` | Per-call item cap. Excess items are truncated by the recursive validator and reported in the tool_result. |
-| `maxWritesPerRun` | `6` | Per-run write cap. Plumbs into `behavior.toolBudgets.todowrite`. Set to `0` to opt out (factory omits the entry; caller-supplied budget wins). |
-| `onMaxWrites` | `'steer'` | `'steer'` or `'block'`. |
-| `remindAfter` | `3` | Append a "you've checkpointed N times — slow down" nudge to the tool_result once the run-cumulative count reaches this. Set to `0` to opt out. Counts executed dispatches only (dedup hits skip the body); use `maxWritesPerRun` for a hard limit covering both. |
+| `maxWritesPerRun` | `0` | Per-run write cap. **Off by default** — `todowrite` is a state-transition tool, capping it punishes the legitimate "finish the N-item plan" path (which needs ≥ N+1 calls). Set to a positive `N` to opt in; the factory then plumbs `behavior.toolBudgets.todowrite = { max: N, onExceed }`. |
+| `onMaxWrites` | `'steer'` | `'steer'` or `'block'`. Only takes effect when `maxWritesPerRun > 0`. |
+| `remindAfter` | `3` | Append a "you've checkpointed N times — slow down" nudge to the tool_result once the cumulative count reaches this. Count is scoped the same way the data is (session-shared for top-level runs, per-run for subagents) so it reflects use of the *active* slot, not noisy per-prompt resets. Set to `0` to opt out. |
 | `reminderText` | built-in | `(count, items) => string \| undefined`. Return `undefined` / `''` to suppress for this call. |
-| `dedupIdentical` | `true` | Short-circuits the tool body when the incoming payload is identical to the current run's stored slot. **Run-scoped on purpose** — the comparison reads `session.metadata.todosByRun[runId]` directly rather than going through `behavior.dedupTools` (whose cache is session-scoped and would silently drop cross-run re-writes after an abort). Counter still advances on no-op re-writes so the reminder catches spam. Set `false` to skip the check entirely. |
+| `dedupIdentical` | `true` | Short-circuits the tool body when the incoming payload is identical to the current slot (session-shared for top-level, per-run for subagents). Does NOT plumb through `behavior.dedupTools` — that cache lives at the gate, is keyed per session, and would conflate top-level + subagent re-writes. Counter still advances on no-op re-writes so the reminder catches spam. Set `false` to skip the check entirely. |
 | `writeDescription` / `readDescription` | built-in | Override the JSON-schema-level descriptions. |
 
 `BUILD_AGENT` opts in via `composePresets`; `PLAN_AGENT` doesn't (read-only mode has nothing to checkpoint). Hosts building custom profiles use the same primitive:
@@ -509,7 +534,7 @@ const myPreset = composePresets(
     tools: { ...basicTools },
     behavior: { ...SHARED_BEHAVIOR },
   }),
-  createTodoTools({ maxWritesPerRun: 6, remindAfter: 3 }),
+  createTodoTools({ remindAfter: 3 }),
 )
 ```
 
@@ -524,14 +549,28 @@ Spread is shallow-merge, so two presets that both touch `dedupTools` / `toolBudg
 Hygiene is layered across the lifecycle:
 
 - **Input time** — schema validation drops malformed items; per-call ID dedup keeps last-wins semantics; empty initial writes don't create a slot.
-- **Per-call reminder** — rides on the tool's own `tool_result`, so the model sees the nudge in the result it just received (no `system:transform` plumbing).
-- **Per-run write budget** — plumbed through `behavior.toolBudgets.todowrite`; same gate, same `tool-budget:exceeded` event. Counts every dispatched call including identical re-writes.
-- **Identical-payload dedup** — handled inside the tool body, against the current run's stored slot. Run-scoped by construction, so an identical re-write in a NEW run after an abort always actually writes (the new run's slot starts empty, the lists never match, the body runs). Deliberately NOT wired through `behavior.dedupTools` (session-scoped cache would silently drop cross-run re-writes — the failure mode the body-level dedup exists to avoid).
-- **Session-level reconciliation** — `pruneTodosByRun(session)` drops orphan keys (and the parallel counter bag) after a `setRuns()` fork or any out-of-band run-list mutation; not automatic on `save()`.
-- **Subagent isolation** — falls out of `runId`-keyed state; each child run owns its own slot.
+- **Auto-clear** — when every item is `completed`, the live slot is wiped on write. Prevents the "all done" list from sitting in the model's context and shadowing the next prompt. The close-out list lands in `bag.archive` so the TUI modal can keep showing it until the model writes a fresh batch.
+- **Per-call reminder** — rides on the tool's own `tool_result`, so the model sees the nudge in the result it just received (no `system:transform` plumbing). Counter is scoped to the active slot (session-shared / per-run).
+- **Per-run write budget (opt-in)** — when the host sets `maxWritesPerRun > 0`, plumbed through `behavior.toolBudgets.todowrite`; same gate, same `tool-budget:exceeded` event. Counts every dispatched call including identical re-writes. Off by default — see the table above for the rationale.
+- **Identical-payload dedup** — handled inside the tool body, against the current slot. The slot resolution naturally splits top-level from subagent, so an identical re-write in the active scope short-circuits to "No change" and a structurally identical write in a different scope (different subagent) writes correctly. Deliberately NOT wired through `behavior.dedupTools` (session-scoped cache would conflate the two).
+- **Session-level reconciliation** — `pruneTodosByRun(session)` drops orphan subagent slots after a `setRuns()` fork or any out-of-band run-list mutation. The top-level `session` slot is unaffected (it's session-scoped, not per-run, so there's no orphan to GC). Not automatic on `save()`.
+- **Subagent isolation** — falls out of `parentRunId`-keyed routing in `getTodosForRun` / `setTodosForRun`; each child run owns its own slot.
 
 Renderer integration: the `TOOL_DISPLAY` registry ships entries for both tools (`Todos N items · …` line shape that matches the tool's result summary), and `DEFAULT_PERSIST_EXCLUDE_TOOLS` skips them from disk-persistence (the latest snapshot is the only state of interest).
 
+### UI surface — opt-in indicator + always-on modal
+
+The chat layer ships two renderer-agnostic primitives any host can build a UI on. The TUI wires both (see **TUI.md**); a GUI shell would reuse `useActiveTodos` + `TODO_STATUS_GLYPHS` and draw its own chrome.
+
+- **Inline indicator.** Single-line "▸ <in-progress content>" badge to render near the prompt input. Show iff `selectActiveTodos(session).inProgress` is non-null. Gated on `Settings.showTodoIndicator` (default `true`). When the active run has no `in_progress` item the indicator returns null — never a placeholder, never visual noise.
+- **Todos modal.** Read-only viewer for the active run's slot. Renders the per-status tally header + a scrollable list of rows (`TODO_STATUS_GLYPHS[status]` + content). No interactive controls — the model is the only writer. The host wires it behind the `openTodos` keybinding action (default `ctrl+t` — see **Keybindings** below); the modal closes on `esc`. Resolves the active run via `pickActiveRunId` (latest running, fallback most-recently-appended) so a child subagent's slot surfaces when it's the live run.
+
+The hook recomputes on every parent re-render (cheap O(runs + todos) selector) so a `setTodosForRun` write — whether to the session slot or a subagent's — lands in the indicator and modal on the next paint without any memoization-cache invalidation gymnastics.
+
+For surfaces that don't sit on the streaming-buffer cascade — typically modal trees rendered above the chat shell — the host should drive an explicit re-render by subscribing to the agent's `tool:after` hook filtered to `TODOWRITE_TOOL` (the hook payload's `name` field). The TUI's `TodosModal` does this so it stays live while open; the indicator gets it for free because it sits inside `ChatScreen` and rides the existing event cascade.
+
+`Settings.showTodoIndicator` (boolean, default `true`) hides only the inline indicator. The modal stays accessible regardless — opening it is an explicit user gesture.
+
 ## Interactions
 
 `present_plan` and `ask_user` let the agent pause for explicit user input. **The call IS the persisted state** — both tools land in `session.turns` as regular `tool_call` blocks, and pending entries are derived from disk via `pendingInteractionsFromTurns(turns)`.
@@ -560,7 +599,7 @@ A user-overridable action catalog. Defaults declared in `KEYBINDING_DEFS`; user
 ```ts
 type KeyAction
   = | 'openSettings' | 'openSessionDetails' | 'openModelPicker' | 'openEffortPicker'
-    | 'cycleAgent' | 'enterSelectTurnMode'
+    | 'openTodos' | 'cycleAgent' | 'enterSelectTurnMode'
     | 'enterQueueSelection' | 'pushQueuedMessage' | 'dropQueuedMessage'
     | 'turnFork' | 'turnDelete' | 'turnCopy'
     | 'sessionDelete' | 'sessionCopyId' | 'sessionGenerateTitle'

package/docs/TUI.md

@@ -193,6 +193,7 @@ Every customizable shortcut routes through `<userDir>/keybindings.json` and is p
 | `ctrl+m` | `openModelPicker` | chat (idle) | open cross-provider model picker |
 | `ctrl+l` | `openEffortPicker` | chat (idle, model has reasoning) | open reasoning-effort picker |
 | `ctrl+s` | `enterSelectTurnMode` | chat (idle) | enter select-turn mode (transcript navigation) |
+| `ctrl+t` | `openTodos` | chat (session attached) | open the active run's `todowrite` checkpoints (read-only) |
 | `shift+tab` | `cycleAgent` | chat (idle, ≥2 profiles) | cycle to next agent profile |
 | `ctrl+↵` | `pushQueuedMessage` | queue-selection mode | push selected queued message into the live run |
 | `backspace` | `dropQueuedMessage` | queue-selection mode | drop selected queued message |
@@ -305,6 +306,23 @@ File-edit tools (`edit` / `multi_edit` / `write_file`) get their own approval su
 
 `isFileEditTool(tool)` (exported from `file-edit-approval-modal.tsx`) is the gate routing predicate. The set is `{'edit', 'multi_edit', 'write_file'}`; everything else stays on the inline `ApprovalBlock` path. For a fully-denied file-edit call, `applyGate` skips the substitute path entirely — sets `ctx.block = true` + emits a synthetic `tool-result` event with body `[fully denied] <edit-outcomes>…</edit-outcomes>` for live display. The persisted result stays the terse `Blocked: User denied this tool call` the harness writes.
 
+### Todos surface — indicator + modal
+
+Two thin chrome layers on top of the renderer-agnostic `useActiveTodos` hook (see [Todos in CHAT.md](./CHAT.md#todos) for the data contract — the keying rule, the auto-clear behavior, and the legacy-bag migration). Both surfaces share `TODO_STATUS_GLYPHS` so a row in the modal and the inline indicator read as the same visual language.
+
+- **`TodoIndicator`** (`src/tui/todo-indicator.tsx`) — single-line `◐  <in-progress content>` badge mounted between the queue block and the prompt in `ChatScreen`. Hides itself (returns `null`) when there's no session, no active run, no `in_progress` item, the terminal is too narrow to render a meaningful tail, or `Settings.showTodoIndicator` is off. Read-only — not focusable, not clickable. Truncates multi-line / oversized content to one visual line so the chat zone stays calm.
+- **`TodosModal`** (`src/tui/todos-modal.tsx`) — opened via `ctrl+t` (`openTodos`), closes on `esc`. Renders the per-status tally header (`3 completed · 1 in progress · 2 pending`) plus a scrollable list of rows. A right-aligned top-border badge mirrors the live counts (`N in progress · M completed · …`) — populated via the new `Modal.rightTitle` slot (absolutely-positioned sibling that rides the top border, same scissor-rect trick as `TitleOverlay` / file-edit modal). Falls back to the archived "last batch" snapshot when the live list is empty (e.g. after the model marked everything `completed` and the slot auto-cleared) with a subtle `· last batch ·` banner so the user can still see what was just finished. Auto-scrolls the first live `in_progress` row into view on open. Capped at ~two-thirds of the terminal height with a floor (`12`) and ceiling (`36`) so the modal never overpowers the transcript. Layout containment matches the file-edit modal — `flexGrow: 1` on the scrollbox + `overflow: 'hidden'` on the panel — so a long list scrolls cleanly without painting over the action footer. The modal subscribes to the agent's `tool:after` hook (filtered to `todowrite`) so it reflects checkpoints written while it's open — `<ModalRoot>` sits above `<AppShell>` in the React tree and doesn't re-render on the streaming-buffer cascade, so the explicit subscription is what drives reactivity.
+
+Both surfaces resolve "what list to show" via `useActiveTodos(session)`, which carries both the live `todos` (model-facing) and the `archive` (sidecar — see [Todos in CHAT.md](./CHAT.md#todos) for the archive contract). The indicator only renders when there's a live `in_progress` item (an archived in-progress item is by definition stale and hidden). The modal renders `todos` when non-empty, falling back to `archive` when the live slot has been auto-cleared.
+
+In addition, every `todowrite` tool call in the transcript renders a small "what's in progress" sub-list directly beneath the formatted call line. The sub-list reads the call's `input.todos` payload (the checkpoint the model just wrote), filters to `status === 'in_progress'`, and prints one indented `◐ <content>` row per item. Hidden when the payload has no in-progress items (e.g. all-completed close-out) so the transcript stays tight. This is purely declarative — it reads the event's own payload, not session state, so it's stable across re-renders and matches what the model intended at that checkpoint (not the latest list state, which the indicator + modal already surface).
+
+Because top-level runs share `session.metadata.todos.session`, a list written in one prompt **stays visible across the next prompt** — the user aborts mid-task, sends a follow-up, and the indicator + modal continue to show the same list until the model rewrites or auto-clears it. Subagent runs surface their own slot when they're the live run (`pickActiveRunId` picks the latest running run); when a subagent completes, the active resolution reflows to the parent's session slot on the next paint.
+
+`ChatScreen` forwards the live `Session` reference through a separate `liveSession` prop (distinct from the lightweight `SessionMeta` snapshot) because the hook reads `session.metadata.todos` directly; the snapshot path would miss mutations that don't change message identity. The reference stays stable across activations of the same session — re-renders are driven by the existing `events` cascade on every tool result.
+
+`Settings.showTodoIndicator` (default `true`) hides only the inline indicator. The modal is always accessible — opening it is an explicit user gesture.
+
 ## Settings rows
 
 The Settings modal is tabbed. The **General** tab renders three row kinds from the chat-level tables; **Skills** and **MCP servers** render the discovered catalogs as enable/disable checklists.
@@ -323,7 +341,7 @@ A single shared search input filters the active tab's list (`label + description
 
 For the live source of truth, see `SETTINGS_TOGGLES` / `SETTINGS_CHOICES` in `src/chat/settings-context.tsx`. The current shape includes:
 
-- **Toggles** — `safeMode`, `allowInteraction`, `resumeLastSession`, `hideSubagentOutput`, `persistToolResults`, `autoCompact`, `showAllProjects`, `showThinking`, `showToolResults`, `showEditDiffs`, `smoothStreaming`.
+- **Toggles** — `safeMode`, `allowInteraction`, `resumeLastSession`, `hideSubagentOutput`, `persistToolResults`, `autoCompact`, `showAllProjects`, `showThinking`, `showToolResults`, `showEditDiffs`, `smoothStreaming`, `showTodoIndicator`, `showThrobber`.
 - **Choices** — `toolCallDisplay` (Formatted / Full / Hidden), `autoCompactThreshold` (60% / 70% / 80% / 90%), `theme` (every entry in `BUILTIN_THEMES`), `targetFps` (30 / 60 / 120).
 
 `enabledSkills` / `enabledMcps` deliberately default to `undefined` (every discovered entry enabled). The Settings modal seeds the allowlist with the current discovery on first toggle so newly-added entries don't silently flip on — the user opts them in.
@@ -488,11 +506,13 @@ src/tui/
   session-details-modal.tsx     Stats + delete / export / title / compact (ctrl+x)
   turn-details-modal.tsx        Fork / delete / copy (opened from select-turn mode)
   file-edit-approval-modal.tsx  FileEditApprovalModal + SingleEditApprovalModal + MultiEditApprovalModal + UnresolvedHunkPanel + `originatorSuffix` (` · child-N` attribution). Inline-mounted in ChatScreen's transcript slot, keyed on `request.id` for force-remount on queue advance — bridges ApprovalDecision (including { kind: 'partial', mask }) to the gate via the helpers in `zidane/chat`'s `edit-approval` module.
+  todo-indicator.tsx            Single-line "in progress todo" badge between the queue block and the prompt (gated on `Settings.showTodoIndicator`; hides itself when nothing's in progress)
+  todos-modal.tsx               Read-only viewer for the active todowrite list (ctrl+t). Resolves the session-shared slot for top-level runs and the per-run slot for subagents; falls back to the archive snapshot when the live slot is empty so a just-completed batch stays visible — see CHAT.md Todos for the keying + archive contracts.
   interaction-block.tsx         InteractionBlock + plan picker + question wizard
   toggle-list-modal.tsx         Generic checkbox-list modal (ToggleListModal)
   completion-popup.tsx          Provider-agnostic autocomplete popover
   discovery-shell.tsx           DiscoveryShell — wires DiscoveryProvider from `zidane/chat` with the three SWR slots (files / skills / mcps)
-  crush-throbber.tsx            CrushThrobber — gradient activity glyph for the thinking affordance
+  crush-throbber.tsx            CrushThrobber — gradient activity glyph for the thinking affordance (gated on `Settings.showThrobber`, off by default)
   clipboard.ts                  OSC 52 writer used by the detail modals
   theme.ts                      buildMdStyle, useMdStyle, MdStyleProvider, ChipStyleProvider, useChipStyle, useChipHighlights
   tree-sitter.ts                Extra grammar registration (registerTreeSitterParsers + initTreeSitterWorker + setupTreeSitter)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,

package/dist/presets-AgF0RFx1.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"presets-AgF0RFx1.js","names":[],"sources":["../src/presets/basic.ts","../src/presets/index.ts"],"sourcesContent":["import { definePreset } from '.'\nimport { edit, listFiles, multiEdit, readFile, shell, writeFile } from '../tools'\nimport { createSpawnTool } from '../tools/spawn'\n\n/**\n * Core tools available in every basic preset (without spawn).\n *\n * `edit` and `multi_edit` ship in the basic set because surgical edits are the\n * default modality for production agents — `write_file` is for full overwrites.\n * `glob` and `grep` are exported but opt-in: not every agent needs codebase\n * search, and shipping them by default would force `tool:gate` work onto\n * consumers that prefer the model to use `shell` + classic Unix tools.\n */\nexport const basicTools = { shell, readFile, writeFile, listFiles, edit, multiEdit }\n\nexport default definePreset({\n  name: 'basic',\n  system: 'You are a helpful assistant with access to shell, file reading, file writing, surgical and multi-edit tools, directory listing, and sub-agent spawning. Prefer `edit` / `multi_edit` for in-place changes and `write_file` for full file overwrites. Use them to accomplish tasks in the project directory.',\n  // `persist: true` shares the parent's session with every child agent — child\n  // turns land in `session.turns` tagged with their own `runId`, and the run\n  // itself is recorded in `session.runs` with `parentRunId` + `depth`. That's\n  // what lets a reloaded TUI session reconstruct the full subagent tree (see\n  // `eventsFromTurns` in `tui/store.ts`). Hosts that want children in-memory\n  // only can construct their own preset with `createSpawnTool()`.\n  tools: { ...basicTools, spawn: createSpawnTool({ persist: true }) },\n})\n","import type { AgentHooks, AgentOptions } from '../agent'\n\nexport type { AgentHookMap } from '../agent'\n\n/**\n * A preset is a reusable slice of `AgentOptions` — spread it into `createAgent()`\n * to configure tools, a default system prompt, aliases, behavior defaults, and\n * agent-lifetime hooks.\n *\n * `provider`, `execution`, `session`, and internal fields are excluded so presets\n * remain shareable and composable.\n *\n * ```ts\n * import { basic } from 'zidane/presets'\n * createAgent({ ...basic, provider })\n * ```\n *\n * ### Composing multiple presets\n *\n * Bare `...spread` is shallow — `{ ...a, ...b }` overwrites every key `b`\n * defines, including `hooks`. Use {@link composePresets} when you want\n * field-aware merging (per-event hook concat, tools shallow-merge, etc.):\n *\n * ```ts\n * createAgent({ ...composePresets(basic, telemetry, mine), provider })\n * ```\n */\nexport type Preset = Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>\n\n/**\n * Identity helper for type inference when defining a preset.\n */\nexport function definePreset(config: Preset): Preset {\n  return config\n}\n\n/**\n * Field-aware composition of presets. Right-most preset wins for scalar fields;\n * objects shallow-merge; arrays and hook handler lists concatenate. Designed so\n * stacking presets does the obvious thing without the spread-collision footgun:\n *\n * - `name`, `system`, `eager`, `skills`              → last-defined wins\n * - `tools`, `toolAliases`, `behavior`               → shallow-merge (later keys override)\n * - `behavior.dedupTools`, `behavior.toolBudgets`    → **deep-merge** (per-tool-name; later wins on collision)\n * - `mcpServers`                                     → concat with last-wins on `name` collision\n * - `hooks`                                          → per-event concat; every handler fires\n *\n * `hooks` always emerges as `event → handler[]` so downstream registration\n * (in `createAgent`) sees a uniform shape. Order of handlers within an event\n * follows preset order: earlier presets register first.\n *\n * `mcpServers` is deduped by `name` because shipping two servers with the same\n * name would trip the connector at runtime — a later preset overriding an\n * earlier preset's `github` server is the practical intent.\n *\n * `behavior.dedupTools` and `behavior.toolBudgets` get the same per-key deep-merge\n * because they are tool-name-keyed records — a preset that ships a dedup hasher\n * for one tool should not erase a hasher another preset ships for a different\n * tool. Last-wins still applies on a per-tool collision so a downstream preset\n * can override an upstream preset's policy for one specific tool. Other\n * `behavior` fields keep last-wins semantics.\n */\nexport function composePresets(...presets: Preset[]): Preset {\n  const out: Preset = {}\n  const hooksByEvent: { [K in keyof AgentHooks]?: AgentHooks[K][] } = {}\n  // Keep mcpServers in source-order on first sight, but allow later\n  // declarations to override earlier ones with the same `name`. A `Map`\n  // keyed by name gives O(1) override + stable iteration.\n  const mcpByName = new Map<string, NonNullable<Preset['mcpServers']>[number]>()\n\n  for (const p of presets) {\n    if (p.name !== undefined)\n      out.name = p.name\n    if (p.system !== undefined)\n      out.system = p.system\n    if (p.eager !== undefined)\n      out.eager = p.eager\n    if (p.skills !== undefined)\n      out.skills = p.skills\n    if (p.tools)\n      out.tools = { ...out.tools, ...p.tools }\n    if (p.toolAliases)\n      out.toolAliases = { ...out.toolAliases, ...p.toolAliases }\n    if (p.behavior) {\n      // Top-level shallow-merge first; then deep-merge the two tool-name-keyed\n      // sub-records so per-tool entries from earlier presets aren't clobbered.\n      const merged: NonNullable<Preset['behavior']> = { ...out.behavior, ...p.behavior }\n      if (out.behavior?.dedupTools || p.behavior.dedupTools) {\n        merged.dedupTools = { ...out.behavior?.dedupTools, ...p.behavior.dedupTools }\n      }\n      if (out.behavior?.toolBudgets || p.behavior.toolBudgets) {\n        merged.toolBudgets = { ...out.behavior?.toolBudgets, ...p.behavior.toolBudgets }\n      }\n      out.behavior = merged\n    }\n    if (p.mcpServers) {\n      for (const server of p.mcpServers)\n        mcpByName.set(server.name, server)\n    }\n    if (p.hooks) {\n      for (const [event, handler] of Object.entries(p.hooks)) {\n        if (handler === undefined)\n          continue\n        const list = Array.isArray(handler) ? handler : [handler]\n        const key = event as keyof AgentHooks\n        // Safe cast: we read the loose `AgentHookMap` shape (handler-or-array)\n        // and re-emit only as arrays. Each `list` element matches the event's\n        // handler signature by construction (the input was typed `AgentHookMap`).\n        const bucket = (hooksByEvent[key] ??= []) as unknown[]\n        bucket.push(...(list as unknown[]))\n      }\n    }\n  }\n\n  if (mcpByName.size > 0)\n    out.mcpServers = [...mcpByName.values()]\n\n  if (Object.keys(hooksByEvent).length > 0)\n    out.hooks = hooksByEvent\n\n  return out\n}\n\nexport { default as basic, basicTools } from './basic'\n"],"mappings":";;;;;;;;;;;AAaA,MAAa,aAAa;CAAE;CAAO;CAAU;CAAW;CAAW;CAAM;CAAW;AAEpF,IAAA,gBAAe,aAAa;CAC1B,MAAM;CACN,QAAQ;CAOR,OAAO;EAAE,GAAG;EAAY,OAAO,gBAAgB,EAAE,SAAS,MAAM,CAAC;EAAE;CACpE,CAAC;;;;;;ACOF,SAAgB,aAAa,QAAwB;CACnD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BT,SAAgB,eAAe,GAAG,SAA2B;CAC3D,MAAM,MAAc,EAAE;CACtB,MAAM,eAA8D,EAAE;CAItE,MAAM,4BAAY,IAAI,KAAwD;CAE9E,KAAK,MAAM,KAAK,SAAS;EACvB,IAAI,EAAE,SAAS,KAAA,GACb,IAAI,OAAO,EAAE;EACf,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,UAAU,KAAA,GACd,IAAI,QAAQ,EAAE;EAChB,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,OACJ,IAAI,QAAQ;GAAE,GAAG,IAAI;GAAO,GAAG,EAAE;GAAO;EAC1C,IAAI,EAAE,aACJ,IAAI,cAAc;GAAE,GAAG,IAAI;GAAa,GAAG,EAAE;GAAa;EAC5D,IAAI,EAAE,UAAU;GAGd,MAAM,SAA0C;IAAE,GAAG,IAAI;IAAU,GAAG,EAAE;IAAU;GAClF,IAAI,IAAI,UAAU,cAAc,EAAE,SAAS,YACzC,OAAO,aAAa;IAAE,GAAG,IAAI,UAAU;IAAY,GAAG,EAAE,SAAS;IAAY;GAE/E,IAAI,IAAI,UAAU,eAAe,EAAE,SAAS,aAC1C,OAAO,cAAc;IAAE,GAAG,IAAI,UAAU;IAAa,GAAG,EAAE,SAAS;IAAa;GAElF,IAAI,WAAW;;EAEjB,IAAI,EAAE,YACJ,KAAK,MAAM,UAAU,EAAE,YACrB,UAAU,IAAI,OAAO,MAAM,OAAO;EAEtC,IAAI,EAAE,OACJ,KAAK,MAAM,CAAC,OAAO,YAAY,OAAO,QAAQ,EAAE,MAAM,EAAE;GACtD,IAAI,YAAY,KAAA,GACd;GACF,MAAM,OAAO,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;GACzD,MAAM,MAAM;GAKZ,CADgB,aAAa,SAAS,EAAE,EACjC,KAAK,GAAI,KAAmB;;;CAKzC,IAAI,UAAU,OAAO,GACnB,IAAI,aAAa,CAAC,GAAG,UAAU,QAAQ,CAAC;CAE1C,IAAI,OAAO,KAAK,aAAa,CAAC,SAAS,GACrC,IAAI,QAAQ;CAEd,OAAO"}