@wrongstack/core 0.284.0 → 0.285.0

package/dist/tool-BNlnIJvo.d.ts

@@ -1,2190 +0,0 @@
-interface TextBlock {
-    type: 'text';
-    text: string;
-    cache_control?: {
-        type: 'ephemeral' | undefined;
-    };
-}
-interface ToolUseBlock {
-    type: 'tool_use';
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-    /**
-     * Provider-specific opaque metadata captured from the wire response.
-     * Echoed back verbatim in the next request so providers that bind
-     * extra state to function calls keep working. Example: Gemini's
-     * `thoughtSignature` — required for tool-use turns with thinking
-     * models, otherwise the next request fails with 400 "Function call
-     * is missing a thought_signature in functionCall parts".
-     *
-     * Keys are namespaced by intent so multiple wires can coexist:
-     *   - `google.thoughtSignature` — Gemini signed-thought blob
-     * Other providers can add their own keys without colliding.
-     */
-    providerMeta?: Record<string, unknown>;
-}
-interface ToolResultBlock {
-    type: 'tool_result';
-    tool_use_id: string;
-    /**
-     * The original tool name. Useful for providers like Google Gemini that
-     * need the tool name in `functionResponse.name` — the tool_use_id is
-     * only a session-local identifier and is not stable across replays.
-     * Always set by ToolExecutor; may be absent on manually-constructed blocks.
-     */
-    name?: string | undefined;
-    content: string;
-    is_error?: boolean | undefined;
-}
-interface ImageBlock {
-    type: 'image';
-    source: {
-        type: 'base64' | 'url';
-        media_type?: string | undefined;
-        data?: string | undefined;
-        url?: string | undefined;
-    };
-}
-/**
- * Chain-of-thought / extended-thinking content emitted by the model.
- *
- * Both Anthropic extended thinking (`{type:'thinking', thinking, signature}`)
- * and DeepSeek reasoning mode (top-level `reasoning_content` on the assistant
- * message) require this content to be echoed back verbatim on the next
- * request, otherwise the provider returns 400:
- *   - Anthropic: "The `content[].thinking` in the thinking mode must be passed back"
- *   - DeepSeek:  "The `reasoning_content` in the thinking mode must be passed back"
- *
- * `signature` is Anthropic-specific (an opaque integrity blob). DeepSeek
- * doesn't issue a signature — the field is absent for that provider.
- *
- * Per Anthropic, thinking blocks MUST appear before any text/tool_use blocks
- * in an assistant message. Stream builders preserve that order.
- */
-interface ThinkingBlock {
-    type: 'thinking';
-    thinking: string;
-    signature?: string | undefined;
-    providerMeta?: Record<string, unknown>;
-}
-type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ImageBlock | ThinkingBlock;
-declare function isTextBlock(b: ContentBlock): b is TextBlock;
-declare function isToolUseBlock(b: ContentBlock): b is ToolUseBlock;
-declare function isToolResultBlock(b: ContentBlock): b is ToolResultBlock;
-declare function isImageBlock(b: ContentBlock): b is ImageBlock;
-
-/**
- * Side-effect risk classification for structured audit recording (P2 #5).
- *
- * @see {@link import('../core/context.js').Context.recordSideEffect}
- */
-/**
- * The kind of risk a tool side-effect poses. Used by /diag and session
- * replay to filter and group side effects.
- */
-type SideEffectRisk = 'fs.write' | 'shell' | 'package' | 'network' | 'config';
-/**
- * A structured record of a non-filesystem side effect produced by a tool.
- * Appended to the session JSONL as a `side_effect` event for audit and
- * observability.
- */
-interface SideEffect {
-    /** Session-unique tool call ID (from the tool_use block). */
-    toolUseId: string;
-    /** Tool name: 'bash' | 'install' | 'fetch' | ... */
-    toolName: string;
-    /** ISO timestamp. */
-    ts: string;
-    /** The input the tool received (command, url, packages). */
-    input: Record<string, unknown>;
-    /**
-     * Optional outcome summary — NOT the full output (that's already in the
-     * tool_result block). A short string like "exit 0", "installed 42 packages",
-     * "HTTP 200 (12KB)", or "timed out".
-     */
-    outcome?: string | undefined;
-    /** Risk classification for filtering in /diag. */
-    risk: SideEffectRisk;
-}
-
-type MessageRole = 'user' | 'assistant' | 'system';
-interface Message {
-    role: MessageRole;
-    content: string | ContentBlock[];
-    /**
-     * ISO-8601 timestamp from the originating SessionEvent.
-     * Populated by SessionStore.replay() during session load/resume
-     * so consumers (WebUI, TUI, exports) can reconstruct the original
-     * conversation timeline instead of seeing every message stamped
-     * with "now". Absent for in-memory messages created during a live
-     * run — those use wall-clock time from the caller.
-     */
-    ts?: string | undefined;
-    /**
-     * Pre-computed token estimate for this message, set by
-     * ConversationState on append/replace. Used by estimateMessageTokens
-     * and estimateRequestTokens to skip the O(n·m) content-block walk
-     * on every context-pressure check. Undefined means "not yet computed"
-     * — the estimator falls back to walking content blocks.
-     */
-    _estTokens?: number | undefined;
-}
-
-/**
- * WrongStack error hierarchy.
- *
- * Every error thrown by the framework is a `WrongStackError` with a
- * machine-readable `code`, a `subsystem` tag, and a `severity` level.
- * This lets consumers (CLI, TUI, plugins, tests) branch on structured
- * data instead of parsing error messages.
- */
-/**
- * Machine-readable error codes as frozen constants.
- *
- * Use `ERROR_CODES.X` instead of raw string literals for:
- * - IDE autocomplete and compile-time validation
- * - Safe refactoring (rename updates all usages)
- * - Plugin extensibility (extend the object to add custom codes)
- *
- * The `ErrorCode` type is derived from this object, so adding a new
- * code here automatically updates the type without extra changes.
- */
-declare const ERROR_CODES: {
-    readonly PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED";
-    readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
-    readonly PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED";
-    readonly PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST";
-    readonly PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR";
-    readonly PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR";
-    readonly PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW";
-    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
-    readonly TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED";
-    readonly TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED";
-    readonly TOOL_TIMEOUT: "TOOL_TIMEOUT";
-    readonly TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID";
-    readonly CONFIG_INVALID: "CONFIG_INVALID";
-    readonly CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND";
-    readonly CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED";
-    readonly CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED";
-    readonly PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED";
-    readonly PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH";
-    readonly PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY";
-    readonly AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT";
-    readonly AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW";
-    readonly AGENT_ABORTED: "AGENT_ABORTED";
-    readonly AGENT_RUN_FAILED: "AGENT_RUN_FAILED";
-    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
-    readonly SESSION_CORRUPTED: "SESSION_CORRUPTED";
-    readonly SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED";
-    readonly CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND";
-    readonly CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND";
-    readonly CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY";
-    readonly REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE";
-    readonly REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND";
-    readonly REGISTRY_INVALID: "REGISTRY_INVALID";
-    readonly FS_READ_FAILED: "FS_READ_FAILED";
-    readonly FS_WRITE_FAILED: "FS_WRITE_FAILED";
-    readonly FS_MKDIR_FAILED: "FS_MKDIR_FAILED";
-    readonly FS_DELETE_FAILED: "FS_DELETE_FAILED";
-    readonly FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED";
-    readonly SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED";
-    readonly SDD_PARSE_FAILED: "SDD_PARSE_FAILED";
-    readonly SDD_INVALID_STATE: "SDD_INVALID_STATE";
-    readonly SDD_NOT_READY: "SDD_NOT_READY";
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly PARSE_FAILED: "PARSE_FAILED";
-    readonly UNKNOWN: "UNKNOWN";
-};
-/**
- * Union type derived from `ERROR_CODES`. Using `typeof ERROR_CODES[keyof typeof ERROR_CODES]`
- * instead of a string literal union means TypeScript auto-updates the type whenever
- * a new code is added to `ERROR_CODES` — no need to keep two lists in sync.
- */
-type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
-type ErrorSubsystem = 'provider' | 'tool' | 'config' | 'plugin' | 'agent' | 'session' | 'sdd' | 'container' | 'fs' | 'general';
-type ErrorSeverity = 'fatal' | 'error' | 'warning';
-declare class WrongStackError extends Error {
-    readonly code: ErrorCode;
-    readonly subsystem: ErrorSubsystem;
-    readonly severity: ErrorSeverity;
-    readonly recoverable: boolean;
-    readonly context?: Record<string, unknown> | undefined;
-    constructor(opts: {
-        message: string;
-        code: ErrorCode;
-        subsystem: ErrorSubsystem;
-        severity?: ErrorSeverity | undefined;
-        recoverable?: boolean | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-    /**
-     * Render a one-line user-facing description.
-     * Subclasses should override for domain-specific formatting.
-     */
-    describe(): string;
-}
-/**
- * Tool execution errors — thrown by ToolExecutor and individual tools.
- */
-declare class ToolError extends WrongStackError {
-    readonly toolName: string;
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'TOOL_NOT_FOUND' | 'TOOL_PERMISSION_DENIED' | 'TOOL_EXECUTION_FAILED' | 'TOOL_TIMEOUT' | 'TOOL_INPUT_INVALID'>;
-        toolName: string;
-        recoverable?: boolean | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Config loading / validation errors.
- */
-declare class ConfigError extends WrongStackError {
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_PARSE_FAILED' | 'CONFIG_MIGRATION_NEEDED'>;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Plugin loading / lifecycle errors.
- */
-declare class PluginError extends WrongStackError {
-    readonly pluginName: string;
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'PLUGIN_LOAD_FAILED' | 'PLUGIN_API_MISMATCH' | 'PLUGIN_MISSING_DEPENDENCY'>;
-        pluginName: string;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Agent runtime errors — thrown by Agent.run when a non-WrongStackError
- * escapes the inner loop, so callers always see a structured error.
- */
-declare class AgentError extends WrongStackError {
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'AGENT_ITERATION_LIMIT' | 'AGENT_CONTEXT_OVERFLOW' | 'AGENT_ABORTED' | 'AGENT_RUN_FAILED'>;
-        recoverable?: boolean | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Wrap an arbitrary thrown value into a `WrongStackError` so the caller
- * always gets a structured error. Pass-throughs WrongStackError instances
- * unchanged; raw `Error`s and primitives get an `AGENT_RUN_FAILED` wrapper
- * with the original preserved as `cause`.
- */
-declare function toWrongStackError(err: unknown, code?: Extract<ErrorCode, 'AGENT_RUN_FAILED' | 'AGENT_ABORTED' | 'UNKNOWN'>): WrongStackError;
-/**
- * Session storage errors.
- */
-declare class SessionError extends WrongStackError {
-    readonly sessionId?: string | undefined;
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED'>;
-        sessionId?: string | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * SDD (Spec-Driven Development) errors — spec validation, parsing, and
- * state machine violations in the AISpecBuilder, TaskFlow, and TaskTracker.
- */
-declare class SddError extends WrongStackError {
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'SDD_VALIDATION_FAILED' | 'SDD_PARSE_FAILED' | 'SDD_INVALID_STATE' | 'SDD_NOT_READY'>;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * File system operation errors.
- */
-declare class FsError extends WrongStackError {
-    readonly path?: string | undefined;
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'FS_READ_FAILED' | 'FS_WRITE_FAILED' | 'FS_MKDIR_FAILED' | 'FS_DELETE_FAILED' | 'FS_ATOMIC_WRITE_FAILED'>;
-        path?: string | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * HTTP fetch error — thrown when a network request returns a non-OK status.
- * Carries the response status so {@link classifyToolError} can branch on it
- * (429 → transient, 404 → not_found, 401 → permission) without duck-typing
- * the error via `'response' in err`.
- *
- * P3 #18 (before-release.md): the previous `'response' in err` check caught
- * any Error with a `response` property, including custom errors, proxy
- * objects, or mocked errors in tests. `instanceof FetchError` is reliable.
- *
- * Tools and providers that make HTTP requests and need the executor to
- * classify their failures should throw `new FetchError({ status, message })`
- * instead of a bare `Error` with an ad-hoc `response` field.
- */
-declare class FetchError extends WrongStackError {
-    readonly status: number;
-    constructor(opts: {
-        message: string;
-        status: number;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Tool input validation error — thrown when a tool's input fails a validation
- * check that the JSON Schema cannot express (e.g. `old_string === new_string`
- * in edit, or a cross-field invariant). Use this instead of a bare
- * `throw new Error('...validation...')` so {@link classifyToolError} can
- * match on `instanceof` rather than a locale-dependent message substring.
- *
- * P2 #6 (before-release.md): the previous `err.message.includes('validation')`
- * check misclassified any error whose message happened to contain "validation"
- * (e.g. a third-party "input validation timeout") as a VALIDATION error.
- *
- * Named `ToolValidationError` (not `ValidationError`) to avoid colliding with
- * the existing `ValidationError` interface exported by json-schema-validate.ts
- * (a validation-result shape, not an Error subclass).
- */
-declare class ToolValidationError extends WrongStackError {
-    constructor(opts: {
-        message: string;
-        /** Field path or tool name that failed validation, for diagnostics. */
-        field?: string | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-/**
- * Response / payload parse error — thrown when an upstream HTTP response,
- * file, or data structure is well-formed at the transport layer (HTTP 200,
- * valid JSON) but is missing required fields or has an unexpected shape.
- *
- * Distinct from `ConfigError(CONFIG_PARSE_FAILED)` (which is specifically
- * for config-file parsing) and `FetchError` (which covers HTTP non-OK
- * responses). `ParseError` fills the gap: the request succeeded but the
- * response body couldn't be interpreted.
- *
- * Common sites: OAuth token responses missing `access_token`, device-code
- * responses missing `device_code`, registry responses with unexpected
- * schemas.
- */
-declare class ParseError extends WrongStackError {
-    readonly source?: string | undefined;
-    constructor(opts: {
-        message: string;
-        /**
-         * What was being parsed — e.g. `'oauth-token-response'`,
-         * `'device-code-response'`. Lets consumers distinguish parse failures
-         * from different upstream APIs without parsing the message.
-         */
-        source?: string | undefined;
-        context?: Record<string, unknown> | undefined;
-        cause?: unknown | undefined;
-    });
-}
-declare function isWrongStackError(err: unknown): err is WrongStackError;
-declare function isToolError(err: unknown): err is ToolError;
-declare function isConfigError(err: unknown): err is ConfigError;
-declare function isPluginError(err: unknown): err is PluginError;
-declare function isSessionError(err: unknown): err is SessionError;
-declare function isAgentError(err: unknown): err is AgentError;
-declare function isFsError(err: unknown): err is FsError;
-declare function isToolValidationError(err: unknown): err is ToolValidationError;
-declare function isFetchError(err: unknown): err is FetchError;
-declare function isParseError(err: unknown): err is ParseError;
-declare function isSddError(err: unknown): err is SddError;
-
-/**
- * Token usage for a single provider call, normalized across providers.
- *
- * Disjoint semantics: the four fields never overlap. `input` is the count
- * of FRESH input tokens (billed at the full input rate); `cacheRead` and
- * `cacheWrite` are separate cached subsets each priced at their own rate.
- * The total context the model loaded for this turn is
- * `input + (cacheRead ?? 0) + (cacheWrite ?? 0)`.
- *
- * Provider quirks normalized at the adapter layer:
- *  - Anthropic: returns `input_tokens` already disjoint from cache fields.
- *  - OpenAI / OpenAI-compatible: `prompt_tokens` is the TOTAL including
- *    cached portion; the adapter subtracts `cached_tokens` to stay disjoint.
- *  - Google: `promptTokenCount` likewise includes cache; adapter subtracts
- *    `cachedContentTokenCount`.
- *
- * Cost math and the context-fullness chip both depend on the disjoint
- * invariant — a TOTAL `input` plus a separate `cacheRead` count would bill
- * cached tokens twice and skew cache-hit-ratio reporting.
- */
-type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
-type CacheTtl = '5m' | '1h';
-/**
- * Provider-agnostic response-format directive.
- *
- * - `{ type: 'text' }` — free-form text (default).
- * - `{ type: 'json_object' }` — valid JSON without a schema constraint.
- * - `{ type: 'json_schema', jsonSchema: { name, schema, strict? } }` — JSON
- *   constrained to the supplied JSON Schema. The `strict` flag is
- *   OpenAI-specific; Gemini ignores it in favour of `responseMimeType`.
- *
- * Each provider adapter maps this into its own wire format:
- *   OpenAI  → `response_format`
- *   Gemini  → `responseMimeType` + `responseSchema`
- *   Anthropic → (not yet supported; uses tools for structured output)
- */
-interface JsonSchemaSpec {
-    name: string;
-    /** OpenAI-specific: enable strict schema adherence. */
-    strict?: boolean | undefined;
-    /** The JSON Schema object describing the expected shape. */
-    schema: Record<string, unknown>;
-    /** Optional human-readable description (OpenAI). */
-    description?: string | undefined;
-}
-type ResponseFormat = {
-    type: 'text';
-} | {
-    type: 'json_object';
-} | {
-    type: 'json_schema';
-    jsonSchema: JsonSchemaSpec;
-};
-/**
- * Safety category threshold pair used by Google Gemini's `safetySettings`.
- *
- * Categories: `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_HATE_SPEECH`,
- * `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_DANGEROUS_CONTENT`.
- *
- * Thresholds: `BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`,
- * `BLOCK_LOW_AND_ABOVE`.
- */
-interface SafetySetting {
-    category: string;
-    threshold: string;
-}
-interface Usage {
-    input: number;
-    output: number;
-    cacheRead?: number | undefined;
-    /** Back-compat aggregate of all cache-write tokens. Prefer TTL-specific fields when present. */
-    cacheWrite?: number | undefined;
-    cacheWrite5m?: number | undefined;
-    cacheWrite1h?: number | undefined;
-}
-/**
- * Effective prompt tokens loaded by the model for one request.
- *
- * Provider adapters normalize `Usage` to disjoint fields: `input` is fresh
- * full-rate tokens, `cacheRead` is cached prefix tokens, and `cacheWrite` is
- * the cache-written prefix segment. Context-window pressure cares about the
- * full prompt the model saw, not only the bill-at-full-rate slice.
- */
-declare function effectiveInputTokens(usage: Usage): number;
-interface ReasoningRequest {
-    enabled?: boolean | undefined;
-    effort?: ReasoningEffort | undefined;
-    preserve?: boolean | undefined;
-    display?: 'summarized' | 'omitted' | undefined;
-}
-interface RequestCacheControl {
-    ttl?: CacheTtl | undefined;
-}
-interface ReasoningConfig {
-    default: 'enabled' | 'disabled' | 'adaptive' | 'always_on';
-    disableSupported: boolean;
-    effortSupported: boolean;
-    effortLevels: ReasoningEffort[];
-    preserveThinking: 'unsupported' | 'optional' | 'always_on';
-}
-interface Capabilities {
-    tools: boolean;
-    parallelTools: boolean;
-    vision: boolean;
-    streaming: boolean;
-    promptCache: boolean;
-    systemPrompt: boolean;
-    jsonMode: boolean;
-    reasoning: boolean;
-    maxContext: number;
-    /**
-     * Maximum output tokens the model can produce in a single response.
-     * Used as the default for `Request.maxTokens` when the caller doesn't
-     * supply an explicit value — letting subagents run up to the model's
-     * native ceiling instead of a fixed 8192 cap. Omit (undefined) to fall
-     * back to a conservative default; populate per family in
-     * `family-capabilities.ts` once you know the spec.
-     */
-    maxOutput?: number | undefined;
-    cacheControl: 'native' | 'auto' | 'none';
-    /** Model accepts `top_k` / `topK` sampling parameter. */
-    topK?: boolean | undefined;
-    /** Model accepts `frequency_penalty` / `frequencyPenalty` parameter. */
-    frequencyPenalty?: boolean | undefined;
-    /** Model accepts `presence_penalty` / `presencePenalty` parameter. */
-    presencePenalty?: boolean | undefined;
-    /** Model accepts `seed` parameter for deterministic generation. */
-    seed?: boolean | undefined;
-    /**
-     * Model accepts JSON Schema / structured-output constraints
-     * (OpenAI `response_format.json_schema`, Gemini `responseMimeType`+`responseSchema`).
-     * Distinct from `jsonMode` (which is just a system-prompt hint).
-     */
-    structuredOutput?: boolean | undefined;
-    /** Model supports log-probability output (`logprobs`, `top_logprobs`). */
-    logprobs?: boolean | undefined;
-    /** Model supports audio input/output modality. */
-    audio?: boolean | undefined;
-    /** Model supports the `n` parameter for multiple completions. */
-    multipleCompletions?: boolean | undefined;
-}
-interface Request {
-    model: string;
-    system?: TextBlock[] | undefined;
-    messages: Message[];
-    tools?: Tool[] | undefined;
-    /**
-     * Cap on output tokens for this single response. Optional — when
-     * omitted, the provider adapter falls back to its own
-     * `capabilities.maxOutput` (which the catalog populates from
-     * `ModelsDevModel.limit.output`). If neither is available, the
-     * adapter applies a conservative 8192 safety net. Letting this stay
-     * undefined at the call site means callers like Chimera can hand the
-     * model its native output ceiling without hard-coding a number.
-     */
-    maxTokens?: number | undefined;
-    temperature?: number | undefined;
-    topP?: number | undefined;
-    topK?: number | undefined;
-    frequencyPenalty?: number | undefined;
-    presencePenalty?: number | undefined;
-    seed?: number | undefined;
-    /**
-     * End-user identifier for abuse monitoring and per-user rate limiting.
-     * - Anthropic → `metadata.user_id`
-     * - OpenAI   → `user`
-     * - Gemini   → (not supported)
-     */
-    user?: string | undefined;
-    /**
-     * Number of response candidates to generate. Google Gemini supports
-     * this via `generationConfig.candidateCount`. OpenAI does not have
-     * an equivalent (`n` is conceptually similar but distinct).
-     */
-    candidateCount?: number | undefined;
-    /**
-     * Whether to return log probabilities for output tokens.
-     * - OpenAI → `logprobs: boolean` (+ `topLogprobs: number`)
-     * - Gemini → `generationConfig.logprobs: number` (how many top candidates)
-     * Default undefined = no logprobs requested.
-     */
-    logprobs?: boolean | undefined;
-    /**
-     * Number of most probable tokens to return log probabilities for
-     * (OpenAI `top_logprobs`). Only meaningful when `logprobs` is true.
-     * Range: 0-20. Gemini ignores this (uses `logprobs` as the count).
-     */
-    topLogprobs?: number | undefined;
-    stopSequences?: string[] | undefined;
-    toolChoice?: 'auto' | 'required' | 'none' | {
-        type: 'tool' | undefined;
-        name: string;
-    };
-    reasoning?: ReasoningRequest | undefined;
-    cache?: RequestCacheControl | undefined;
-    /**
-     * Structured-output / response-format directive.
-     * When set, the provider adapter maps this to its native response-format
-     * parameter (OpenAI `response_format`, Gemini `responseMimeType`, etc.).
-     * The model must advertise `capabilities.structuredOutput` for this to be
-     * honoured; unsupported models will likely 400 or ignore it.
-     */
-    responseFormat?: ResponseFormat | undefined;
-    /**
-     * Safety category thresholds for filtering harmful content.
-     * - Gemini → top-level `safetySettings` array with `{ category, threshold }`
-     * - OpenAI → not supported (uses server-side moderation)
-     * - Anthropic → not supported
-     */
-    safetySettings?: SafetySetting[] | undefined;
-}
-type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'refusal';
-interface Response {
-    content: ContentBlock[];
-    stopReason: StopReason;
-    usage: Usage;
-    model: string;
-}
-type StreamEvent = {
-    type: 'message_start';
-    model: string;
-} | {
-    type: 'content_block_start';
-    kind: 'text' | 'tool_use' | 'thinking';
-    id?: string | undefined;
-    name?: string | undefined;
-} | {
-    type: 'content_block_stop';
-    index: number;
-} | {
-    type: 'text_delta';
-    text: string;
-} | {
-    type: 'tool_use_start';
-    id: string;
-    name: string;
-} | {
-    type: 'tool_use_input_delta';
-    id: string;
-    partial: string;
-} | {
-    type: 'tool_use_stop';
-    id: string;
-    input: unknown;
-    providerMeta?: Record<string, unknown>;
-} | {
-    type: 'thinking_start';
-    providerMeta?: Record<string, unknown>;
-} | {
-    type: 'thinking_delta';
-    text: string;
-} | {
-    type: 'thinking_signature';
-    signature: string;
-} | {
-    type: 'thinking_stop';
-} | {
-    type: 'message_stop';
-    stopReason: StopReason;
-    usage: Usage;
-};
-interface Provider {
-    readonly id: string;
-    readonly capabilities: Capabilities;
-    /** Canonical streaming entry point. `complete()` defaults to a wrapper that
-     * aggregates this stream — providers may override for non-streaming wires. */
-    stream(req: Request, opts: {
-        signal: AbortSignal;
-    }): AsyncIterable<StreamEvent>;
-    complete(req: Request, opts: {
-        signal: AbortSignal;
-    }): Promise<Response>;
-}
-/**
- * Structured body parsed from a provider's HTTP error response. Populated
- * best-effort: providers return JSON shaped differently (Anthropic uses
- * `{error: {type, message}}`, OpenAI uses `{error: {message, code}}`,
- * Google uses `{error: {status, message}}`), so the fields here are the
- * intersection that's usable for rendering and routing.
- */
-interface ProviderErrorBody {
-    /** Provider-specific kind, e.g. "overloaded_error", "rate_limit_error", "invalid_request_error". */
-    type?: string | undefined;
-    /** Human-readable explanation from the provider. */
-    message?: string | undefined;
-    /** Provider request id, when present in the body or headers. */
-    requestId?: string | undefined;
-    /** Parsed Retry-After header (or equivalent body hint) in milliseconds. */
-    retryAfterMs?: number | undefined;
-    /** The raw response body (truncated to ~2 KB), kept for debugging. */
-    raw?: string | undefined;
-    /** True when `raw` was truncated; check `rawLength` for the original size. */
-    truncated?: boolean | undefined;
-    /** Original length of the response body in bytes, when `truncated` is true. */
-    rawLength?: number | undefined;
-}
-/**
- * Canonical provider-failure taxonomy. Computed ONCE at error-construction
- * time (`classifyProviderError`) and carried on `ProviderError.kind` so
- * every downstream consumer — retry policy, cross-provider fallback,
- * recovery strategies, the subagent error classifier — branches on the
- * same classification instead of re-deriving it from status codes and
- * message regexes. When a new provider's error format needs special
- * handling, this module is the only place to teach it.
- */
-type ProviderErrorKind = 'rate_limit' | 'overloaded' | 'server' | 'timeout' | 'network' | 'stream_hang' | 'auth' | 'context_overflow' | 'content_filter' | 'invalid_request' | 'unknown';
-/**
- * Classify a provider HTTP failure into the canonical taxonomy from its
- * status code plus the parsed error body (and, for message-only errors
- * without a structured body, the error message itself). Pure and total —
- * always returns a kind, never throws.
- */
-declare function classifyProviderError(status: number, body?: ProviderErrorBody, message?: string): ProviderErrorKind;
-/**
- * Whether a kind is worth retrying against the SAME provider/model.
- * `context_overflow` is deliberately false — the request must shrink first;
- * `auth`/`invalid_request`/`content_filter` won't improve on replay.
- *
- * Exhaustive by construction (`Record<ProviderErrorKind, …>`): adding a new
- * kind refuses to compile until it is classified here. Every kind→X mapping
- * in the codebase follows this drift-guard pattern — see also KIND_TO_CODE
- * below, DefaultRetryPolicy.maxAttempts, fallback-model shouldFallback, and
- * the coordinator's providerErrorToSubagentError.
- */
-declare function isRetryableKind(kind: ProviderErrorKind): boolean;
-declare class ProviderError extends WrongStackError {
-    readonly status: number;
-    readonly retryable: boolean;
-    readonly providerId: string;
-    /** Canonical failure classification — see {@link ProviderErrorKind}. */
-    readonly kind: ProviderErrorKind;
-    readonly body?: ProviderErrorBody | undefined;
-    constructor(message: string, status: number, retryable: boolean, providerId: string, opts?: {
-        body?: ProviderErrorBody | undefined;
-        cause?: unknown | undefined;
-        /** Override the computed classification (rarely needed — tests, custom wires). */
-        kind?: ProviderErrorKind | undefined;
-    });
-    /**
-     * Render a one-line, user-facing description. Designed for the CLI/TUI
-     * status line and the agent's retry warning. Avoids dumping raw JSON
-     * (which is what users see today when a 529 lands and the log message
-     * includes the full `{"type":"error",...}` body).
-     *
-     * Examples:
-     *   "minimax-coding-plan overloaded (529): High traffic detected. Upgrade for highspeed model. [req 06534785201de9c0…]"
-     *   "openai rate limited (429): Retry after 12s"
-     *   "anthropic invalid request (400): messages.0.role must be one of 'user'|'assistant'"
-     *   "groq HTTP 500 (server error)"
-     */
-    describe(): string;
-}
-/**
- * Thrown when the provider stream stops delivering data mid-response.
- * This is distinct from a network error (TCP reset, DNS failure) — the
- * connection is established and the response started, but chunks stopped
- * arriving before the stream completed.
- *
- * Status 599 is used as a sentinel to distinguish stream hangs from
- * regular HTTP errors while still flowing through ProviderError-based
- * retry and fallback infrastructure.
- */
-declare class StreamHangError extends ProviderError {
-    /** Name of the provider that hung, e.g. "zai", "anthropic". */
-    readonly hungProviderId: string;
-    /** Model that was being called when the hang occurred. */
-    readonly hungModel: string;
-    /** How long (ms) we waited for the next chunk before declaring a hang. */
-    readonly hangTimeoutMs: number;
-    /** How many bytes were received before the hang. */
-    readonly bytesReceived: number;
-    /** Elapsed time (ms) from the start of the stream until the hang. */
-    readonly elapsedMs: number;
-    constructor(opts: {
-        providerId: string;
-        model: string;
-        hangTimeoutMs: number;
-        bytesReceived: number;
-        elapsedMs: number;
-        cause?: unknown | undefined;
-    });
-}
-
-interface SessionMetadata {
-    id: string;
-    title?: string | undefined;
-    model?: string | undefined;
-    provider?: string | undefined;
-    startedAt: string;
-    endedAt?: string | undefined;
-    /** Set when a session is closed with open tool calls — used to restore pending state on resume. */
-    pendingToolUses?: string[] | undefined;
-    /** Parent journal metadata when this session was created by fork(). */
-    forkedFrom?: {
-        sessionId: string;
-        checkpointPromptIndex?: number | undefined;
-        checkpointHash: string;
-        workspace: 'shared-current';
-        workspaceCheckpointHash?: string | undefined;
-    } | undefined;
-}
-/**
- * SessionEvent — per-session persistent JSONL audit + reconstruct log.
- *
- * ## Two-Tier Model (see Config.session.auditLevel)
- *
- * **Core Reconstruct Set** (always persisted, minimal & reliable):
- * - `session_start`, `session_resumed`, `session_forked`, `user_input`, `llm_response`, `tool_result`
- * - `context_snapshot`, `checkpoint`, `file_snapshot`, `file_observation`, `rewound`
- * - `in_flight_start` / `in_flight_end`, `session_end`
- *
- * These events are **required** for correct resume, rewind, crash recovery
- * and conversation replay. They are written regardless of auditLevel.
- *
- * **Audit Detail Set** (controlled by `session.auditLevel`):
- * - `llm_request` (lightweight by default)
- * - `tool_use`, `tool_call_start`/`tool_call_end`
- * - `compaction`, `error`, `message_truncated`, provider retries, etc.
- *
- * When `auditLevel: "minimal"` only Core Reconstruct events are guaranteed.
- * `"standard"` (default) adds the most valuable lightweight audit events.
- * `"full"` enables heavier payloads (may be stored in a sidecar replay log).
- *
- * ## Guarantees
- * - All appends are best-effort. A failed write logs a throttled warning but
- *   never aborts the agent loop.
- * - Sensitive content in `user_input`, `llm_response`, and
- *   `context_snapshot` is passed through the configured SecretScrubber before
- *   being written or summarized.
- * - The log is append-only JSONL. Individual lines may be malformed after
- *   hard crashes; `DefaultSessionStore.load()` silently skips bad lines.
- *
- * ## Location (source of truth: resolveWstackPaths)
- * ~/.wrongstack/projects/<sha256(projectRoot).slice(0,12)>/sessions/<date>/sess_<ULID>.jsonl
- *
- * The only files that live inside the project tree are the committed
- * `.wrongstack/AGENTS.md` and `.wrongstack/skills/`.
- */
-type SessionEvent = {
-    type: 'session_start';
-    ts: string;
-    id: string;
-    model: string;
-    provider: string;
-} | {
-    type: 'session_resumed';
-    ts: string;
-    id: string;
-    model: string;
-    provider: string;
-} | {
-    type: 'session_forked';
-    ts: string;
-    parentSessionId: string;
-    parentCheckpointPromptIndex?: number | undefined;
-    parentCheckpointHash: string;
-    /** The child journal is isolated; filesystem state remains shared. */
-    workspace: 'shared-current';
-    workspaceCheckpointHash?: string | undefined;
-} | {
-    type: 'user_input';
-    ts: string;
-    content: string | ContentBlock[];
-} | {
-    type: 'llm_request';
-    ts: string;
-    model: string;
-    messageCount: number;
-    /** Estimated total input tokens for this request (messages + tools + system). */
-    estimatedInputTokens?: number | undefined;
-    /** Number of tools offered to the model in this request. */
-    toolCount?: number | undefined;
-} | {
-    type: 'llm_response';
-    ts: string;
-    content: ContentBlock[];
-    stopReason: string;
-    usage: Usage;
-} | {
-    type: 'tool_use';
-    ts: string;
-    name: string;
-    id: string;
-    input: unknown;
-} | {
-    type: 'tool_result';
-    ts: string;
-    id: string;
-    content: unknown;
-    isError: boolean;
-} | {
-    /**
-     * Exact post-rewrite conversation state. Replay replaces all messages
-     * reconstructed before this event, then continues applying later events.
-     * Currently emitted after compaction.
-     */
-    type: 'context_snapshot';
-    ts: string;
-    reason: 'compaction';
-    messages: Message[];
-} | {
-    type: 'compaction';
-    ts: string;
-    before: number;
-    after: number;
-    /** Pressure level that triggered the compaction. */
-    level?: 'warn' | 'soft' | 'hard' | undefined;
-    aggressive?: boolean | undefined;
-    /** Summary of token savings per phase (elision, summary, selective). */
-    reductions?: Array<{
-        phase: string;
-        saved: number;
-    }>;
-    /** Context budget snapshot used to trigger this compaction. */
-    budget?: {
-        maxContext: number;
-        inputTokens: number;
-        availableInputTokens: number;
-        remainingInputTokens: number;
-        reservedOutputTokens: number;
-        reservedSafetyTokens: number;
-        load: number;
-        overflowTokens: number;
-    } | undefined;
-    /** Adaptive trigger signals observed alongside token pressure. */
-    signals?: {
-        repeatedReadCount?: number | undefined;
-    } | undefined;
-    /**
-     * Lossless digest of the range collapsed during this compaction (text
-     * content preserved; raw tool I/O omitted). Captures *what* was collapsed
-     * for forensics. May be truncated for log size. Absent when nothing was
-     * collapsed (e.g. elision-only passes).
-     */
-    digest?: string | undefined;
-} | {
-    type: 'error';
-    ts: string;
-    message: string;
-    phase: string;
-} | {
-    type: 'session_end';
-    ts: string;
-    usage: Usage;
-    pendingToolUses?: string[] | undefined;
-} | {
-    type: 'mode_changed';
-    ts: string;
-    from: string;
-    to: string;
-} | {
-    type: 'task_created';
-    ts: string;
-    taskId: string;
-    title: string;
-} | {
-    type: 'task_updated';
-    ts: string;
-    taskId: string;
-    status: string;
-} | {
-    type: 'task_completed';
-    ts: string;
-    taskId: string;
-    title: string;
-} | {
-    type: 'task_failed';
-    ts: string;
-    taskId: string;
-    title: string;
-    error: string;
-} | {
-    type: 'agent_spawned';
-    ts: string;
-    agentId: string;
-    role: string;
-} | {
-    type: 'agent_stopped';
-    ts: string;
-    agentId: string;
-} | {
-    type: 'agent_error';
-    ts: string;
-    agentId: string;
-    error: string;
-} | {
-    type: 'spec_parsed';
-    ts: string;
-    specId: string;
-    title: string;
-    completeness: number;
-} | {
-    type: 'spec_analyzed';
-    ts: string;
-    specId: string;
-    gaps: string[];
-} | {
-    type: 'skill_activated';
-    ts: string;
-    skillName: string;
-} | {
-    type: 'skill_deactivated';
-    ts: string;
-    skillName: string;
-} | {
-    type: 'tool_call_start';
-    ts: string;
-    name: string;
-    id: string;
-    input: unknown;
-} | {
-    type: 'tool_call_end';
-    ts: string;
-    name: string;
-    id: string;
-    durationMs: number;
-    /** Legacy field kept for backward compatibility. Prefer outputBytes. */
-    outputSize: number;
-    ok?: boolean | undefined;
-    outputBytes?: number | undefined;
-    outputTokens?: number | undefined;
-    outputLines?: number | undefined;
-} | {
-    /** Lightweight sampled progress from Tool.executeStream (only at auditLevel 'full'). */
-    type: 'tool_progress';
-    ts: string;
-    name: string;
-    id: string;
-    event: {
-        type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output';
-        text?: string | undefined;
-        data?: Record<string, unknown>;
-    };
-} | {
-    type: 'message_truncated';
-    ts: string;
-    before: number;
-    after: number;
-} | {
-    type: 'provider_retry';
-    ts: string;
-    providerId: string;
-    attempt: number;
-    delayMs: number;
-    status?: number | undefined;
-    description: string;
-} | {
-    type: 'provider_error';
-    ts: string;
-    providerId: string;
-    status?: number | undefined;
-    description: string;
-    retryable: boolean;
-} | {
-    type: 'checkpoint';
-    ts: string;
-    promptIndex: number;
-    promptPreview: string;
-    /** Content-addressed Git HEAD + dirty/untracked workspace manifest. */
-    workspaceCheckpoint?: WorkspaceCheckpointRef | undefined;
-} | {
-    type: 'file_snapshot';
-    ts: string;
-    promptIndex: number;
-    files: FileSnapshot[];
-} | {
-    /**
-     * Hash of a file version observed by a tool. The latest observation per
-     * path is revalidated when the session resumes so stale tool context is
-     * surfaced to the model before it continues.
-     */
-    type: 'file_observation';
-    ts: string;
-    path: string;
-    hash: string;
-    mtimeMs: number;
-    source: 'user' | 'write';
-} | {
-    type: 'rewound';
-    ts: string;
-    toPromptIndex: number;
-    revertedFiles: string[];
-} | {
-    /**
-     * Idea #1 from IDEAS.md — Stateful Session Recovery.
-     *
-     * Marks the start of "the process is currently working on this
-     * point in the log". If the process exits cleanly, a matching
-     * `in_flight_end` follows. If the process dies (crash, OOM,
-     * machine sleep, SIGKILL), ordinary request/response/tool events may
-     * follow the start marker but no later lifecycle boundary closes it.
-     * `SessionRecovery.detectStale` scans for that latest unmatched
-     * lifecycle boundary and flags the session as resumable.
-     *
-     * `context` is a free-form description of the current
-     * operation (e.g. "iteration 14 / tool: read / id: tu-7") so
-     * the recovery UI can show "what was the agent doing when it
-     * died?".
-     */
-    type: 'in_flight_start';
-    ts: string;
-    context: string;
-} | {
-    type: 'in_flight_end';
-    ts: string;
-    reason: 'clean' | 'aborted' | 'recovered';
-} | {
-    /**
-     * Structured side-effect audit record (P2 #5). Appended by tools that
-     * perform non-filesystem mutations (bash, install, fetch) so /diag and
-     * session replay can show what the agent did beyond file edits.
-     * Unlike file_snapshot, this is purely for observability — no undo.
-     */
-    type: 'side_effect';
-    ts: string;
-    toolUseId: string;
-    toolName: string;
-    input: Record<string, unknown>;
-    outcome?: string | undefined;
-    risk: 'fs.write' | 'shell' | 'package' | 'network' | 'config';
-};
-type FileSnapshot = {
-    path: string;
-    action: 'created' | 'modified' | 'deleted';
-    before: string | null;
-    after: string | null;
-};
-interface WorkspaceCheckpointRef {
-    manifestHash: string;
-    baseHead: string;
-    entryCount: number;
-    unresolvedCount: number;
-    capturedAt: string;
-    /** Base Git tree plus every non-ignored changed/untracked path. */
-    coverage: 'git-head-plus-dirty';
-}
-interface WorkspaceMaterializationResult {
-    targetRoot: string;
-    writtenFiles: string[];
-    deletedFiles: string[];
-    errors: string[];
-}
-type ResumeFileStatus = 'modified' | 'deleted' | 'unreadable' | 'outside_project';
-interface ResumeFileValidationEntry {
-    /** Absolute path recorded by the original tool observation. */
-    path: string;
-    /** Timestamp of the latest observation that was checked. */
-    observedAt: string;
-    status: ResumeFileStatus;
-    expectedHash: string;
-    actualHash?: string | undefined;
-    detail?: string | undefined;
-}
-interface ResumeValidation {
-    checkedAt: string;
-    /** Number of distinct paths with a valid persisted observation. */
-    checkedFileCount: number;
-    /** Changed, missing, unreadable, or out-of-scope paths. */
-    staleFiles: ResumeFileValidationEntry[];
-}
-interface SessionSummary {
-    id: string;
-    title: string;
-    /**
-     * Optional user-supplied name for the session. Unlike {@link title} (which
-     * is auto-derived from the first user message and overwritten on every
-     * rebuild), `name` is set explicitly via {@link SessionStore.rename} and
-     * persisted in the `.summary.json` sidecar and `_index.jsonl`. Listings
-     * should prefer `name` over `title` when present; `title` remains the
-     * fallback and stays in sync as the conversation evolves.
-     */
-    name?: string | undefined;
-    startedAt: string;
-    /** When the session finished (null if still running / crashed). */
-    endedAt?: string | undefined;
-    model: string;
-    provider: string;
-    tokenTotal: number;
-    /** Number of LLM iterations (turn cycles). */
-    iterationCount?: number | undefined;
-    /** Number of tool calls executed. */
-    toolCallCount?: number | undefined;
-    /** Number of tool calls that returned an error. */
-    toolErrorCount?: number | undefined;
-    /** Number of files changed (created + modified + deleted). */
-    fileChangeCount?: number | undefined;
-    /** Per-tool breakdown: tool name → call count. */
-    toolBreakdown?: Record<string, number>;
-    /** Number of compaction events. */
-    compactionCount?: number | undefined;
-    /** Session outcome: 'completed', 'error', 'timeout', 'aborted', or undefined. */
-    outcome?: 'completed' | 'error' | 'timeout' | 'aborted' | undefined;
-}
-interface SessionData {
-    metadata: SessionMetadata;
-    events: SessionEvent[];
-    messages: Message[];
-    usage: Usage;
-    /** Tool execution records extracted from `tool_call_end` events — used for TUI tool entry rendering on resume. */
-    toolCallEnds: Array<{
-        name: string;
-        id: string;
-        durationMs: number;
-        ok: boolean;
-        outputBytes?: number | undefined;
-        outputTokens?: number | undefined;
-        outputLines?: number | undefined;
-    }>;
-    /** Present on resume when the store is configured with a project root. */
-    resumeValidation?: ResumeValidation | undefined;
-}
-interface ResumedSession {
-    writer: SessionWriter;
-    data: SessionData;
-}
-interface SessionForkOptions {
-    /** Omit to fork the latest persisted event boundary. */
-    checkpointPromptIndex?: number | undefined;
-}
-interface ForkedSession {
-    id: string;
-    data: SessionData;
-    parentSessionId: string;
-    checkpointPromptIndex?: number | undefined;
-    /** SHA-256 of the exact parent event prefix used to create this branch. */
-    checkpointHash: string;
-    /** Session history is isolated, but both branches still see the same files. */
-    workspace: 'shared-current';
-    /** Available for checkpoint forks captured by workspace-CAS-aware writers. */
-    workspaceCheckpoint?: WorkspaceCheckpointRef | undefined;
-}
-interface SessionStore {
-    create(meta: Omit<SessionMetadata, 'startedAt'>): Promise<SessionWriter>;
-    load(id: string): Promise<SessionData>;
-    /**
-     * Open an existing session for append, returning both a writer that
-     * continues writing to the same JSONL file and the replayed state
-     * (messages + usage) so the caller can hydrate a Context. A
-     * `session_resumed` marker is appended for audit.
-     */
-    resume(id: string): Promise<ResumedSession>;
-    /**
-     * Create a non-destructive child journal from a persisted parent boundary.
-     * Parent file snapshots are intentionally not inherited as rewind authority;
-     * filesystem isolation is the caller's worktree/CAS responsibility.
-     */
-    fork?(id: string, opts?: SessionForkOptions): Promise<ForkedSession>;
-    /** Apply a captured workspace manifest to an already-isolated checkout. */
-    materializeWorkspaceCheckpoint?(checkpoint: WorkspaceCheckpointRef, targetRoot: string): Promise<WorkspaceMaterializationResult>;
-    list(limit?: number): Promise<SessionSummary[]>;
-    /**
-     * Set or clear a user-supplied name on a session. An empty/whitespace
-     * `name` clears the field (the summary's auto-derived `title` remains).
-     * Persists the change to the `.summary.json` sidecar and updates the
-     * `_index.jsonl` cache so subsequent `list()` calls reflect it.
-     * Returns the refreshed summary. Throws if the session does not exist.
-     */
-    rename(id: string, name: string): Promise<SessionSummary>;
-    delete(id: string): Promise<void>;
-    /**
-     * Rewrite the session JSONL file to contain only a fresh session_start
-     * event, effectively clearing all conversation history for that session.
-     * Called by /clear to wipe persistent chat history.
-     */
-    clearHistory(id: string): Promise<void>;
-    /**
-     * Delete sessions whose JSONL file mtime is older than maxAgeDays.
-     * Also removes associated summary files, plan/todos sidecars, and
-     * session directories. Returns the count of deleted sessions.
-     * Sessions referenced by active.json are never pruned.
-     */
-    prune(maxAgeDays?: number): Promise<number>;
-    /**
-     * Rebuild the session index from disk. Scans all session directories,
-     * computes summaries, and writes a fresh _index.jsonl. Returns the
-     * number of sessions indexed.
-     */
-    rebuildIndex?(): Promise<number>;
-    /**
-     * Streaming event-level search. Walks the JSONL once without buffering
-     * the whole file, calling `predicate(event, eventIndex, ts)` for each
-     * parsed event. Stops as soon as `limit` matches are collected (when
-     * provided) and yields only the matching events back to the caller.
-     *
-     * Implementations that don't support streaming MUST omit this method;
-     * the SessionReader fallback path will then call `load()` instead. The
-     * method is intentionally non-throwing for missing files — a missing
-     * session yields an empty array, matching `load()` semantics for ENOENT.
-     *
-     * @param id  Session id (with or without the `.jsonl` suffix).
-     * @param predicate  Returns true to keep the event in the result set.
-     * @param opts.limit  Maximum number of hits to keep. Omit for unbounded.
-     * @param opts.signal  Optional AbortSignal for early termination.
-     */
-    searchEvents?(id: string, predicate: (event: SessionEvent, eventIndex: number, ts: string) => boolean, opts?: {
-        limit?: number | undefined;
-        signal?: AbortSignal | undefined;
-    }): Promise<Array<{
-        event: SessionEvent;
-        eventIndex: number;
-        ts: string;
-    }>>;
-}
-interface SessionWriter {
-    readonly id: string;
-    /**
-     * Session-level trace ID for correlating storage events with agent
-     * iterations in observability pipelines. Generated once at Context
-     * creation time and stored here so storage operations can include it
-     * in `storage.*` events even though the store has no direct handle
-     * on the Context.
-     */
-    traceId?: string | undefined;
-    /**
-     * Absolute path to the JSONL file this writer appends to, when one
-     * exists. In-memory writers (tests, ephemeral sessions) leave it
-     * undefined. Observability surfaces (`/fleet log`, FleetPanel) use
-     * this to tell the user *where* the transcript lives without
-     * having to recompute the path from session metadata.
-     */
-    readonly transcriptPath?: string | undefined;
-    /** IDs of tool_use blocks that have been sent but not yet received a tool_result.
-     * Used by the REPL to serialize pending state into `session_end` for proper resume. */
-    readonly pendingToolUses: string[];
-    append(event: SessionEvent): Promise<void>;
-    /**
-     * Append a batch of events in one call. Semantically equivalent to calling
-     * `append()` for each event sequentially, but avoids N individual function
-     * calls, scrub/observe cycles, and timer rescheduling. The caller is
-     * responsible for ensuring events are in the correct order.
-     */
-    appendBatch(events: SessionEvent[]): Promise<void>;
-    /**
-     * Flush any buffered events to disk immediately. Use after critical
-     * events (user_input, llm_response) to ensure they survive a crash
-     * or SIGKILL that would otherwise leave them in the in-memory buffer.
-     * Idempotent — safe to call even when the buffer is empty. File-backed
-     * writers reject on a failed disk append while retaining the batch for a
-     * later retry; callers may log/degrade without losing event chronology.
-     */
-    flush(): Promise<void>;
-    /**
-     * Last-gasp synchronous drain for hard-exit paths (e.g. `process.exit`
-     * after rapid Ctrl+C) where the async `flush()` cannot be awaited.
-     * Writes whatever is still in the in-memory buffer with a blocking
-     * append. Best-effort — errors are swallowed. Optional: in-memory
-     * writers have nothing durable to drain.
-     */
-    flushSync?(): void;
-    close(): Promise<void>;
-    /**
-     * Register a file change for later snapshotting.
-     * Called by write/edit/delete tools to track pending changes.
-     */
-    recordFileChange(input: {
-        path: string;
-        action: 'created' | 'modified' | 'deleted';
-        before: string | null;
-        after: string | null;
-    }): void;
-    /**
-     * Persist the hash of a file version observed by a tool. Optional for
-     * alternate/in-memory writers; file-backed writers use it for stale-file
-     * validation during resume.
-     */
-    recordFileObservation?(input: {
-        path: string;
-        hash: string;
-        mtimeMs: number;
-        source: 'user' | 'write';
-    }): void;
-    /**
-     * Record a structured side effect for audit (P2 #5). Implementations
-     * append a `side_effect` event to the session JSONL. Best-effort —
-     * callers fire-and-forget; errors are swallowed.
-     */
-    recordSideEffect(input: {
-        toolUseId: string;
-        toolName: string;
-        input: Record<string, unknown>;
-        outcome?: string | undefined;
-        risk: 'fs.write' | 'shell' | 'package' | 'network' | 'config';
-    }): void;
-    /**
-     * Write a checkpoint marker after a user input is processed.
-     * Also flushes any pending file snapshots.
-     */
-    writeCheckpoint(promptIndex: number, promptPreview: string): Promise<void>;
-    /**
-     * Write a file snapshot after file changes are detected.
-     * Called by the file watcher or tool interceptor.
-     */
-    writeFileSnapshot(promptIndex: number, files: FileSnapshot[]): Promise<void>;
-    /**
-     * Truncate conversation history to a given checkpoint promptIndex.
-     * Called after rewind — removes user_input/llm_response/tool_result events
-     * that come after the target checkpoint, then writes a rewound event.
-     * Returns the number of events removed.
-     */
-    truncateToCheckpoint(promptIndex: number): Promise<number>;
-    /**
-     * Clear the session transcript file, resetting the on-disk history.
-     * Called by /clear to wipe chat history from persistent storage.
-     */
-    clearSession(): Promise<void>;
-    /**
-     * Idea #1 from IDEAS.md — Stateful Session Recovery.
-     *
-     * Writes an `in_flight_start` event at the current point in the
-     * log. The agent loop should call this at the start of every
-     * long-running operation (an iteration, a tool execution, a
-     * streaming LLM call) so that a crashed process leaves a
-     * visible "what was I doing?" marker. Pair with
-     * `clearInFlightMarker` on clean shutdown.
-     *
-     * The `context` string is surfaced verbatim by
-     * `SessionRecovery.detectStale` and the `/resume --incomplete`
-     * CLI command, so prefer something a human can read at a glance:
-     *   "iteration 14 / tool: read / id: tu-7"
-     */
-    writeInFlightMarker(context: string): Promise<void>;
-    /**
-     * Writes an `in_flight_end` event. Call on every clean exit
-     * point (after a successful iteration, after the user issues
-     * /exit, after a graceful SIGINT, etc.). The `reason` is
-     * surfaced in the session log for postmortem review.
-     */
-    clearInFlightMarker(reason: 'clean' | 'aborted' | 'recovered'): Promise<void>;
-}
-
-type ToolEvidenceStatus = 'seen' | 'referenced';
-interface ToolOutputMetadata {
-    toolUseId: string;
-    toolName: string;
-    ok: boolean;
-    inputSummary?: string | undefined;
-    summary: string;
-    files: string[];
-    symbols: string[];
-    commands: string[];
-    errors: string[];
-    status: ToolEvidenceStatus;
-    referenceCount: number;
-    seenAt: number;
-    referencedAt?: number | undefined;
-    outputBytes?: number | undefined;
-    outputTokens?: number | undefined;
-    outputLines?: number | undefined;
-}
-interface ContextFileEvidence {
-    path: string;
-    reads: number;
-    writes: number;
-    tools: string[];
-    referenced: boolean;
-    lastToolUseId?: string | undefined;
-}
-interface ContextIntentEvidence {
-    text: string;
-    updatedAt: number;
-}
-interface ContextRepeatedReadEvidence {
-    file: string;
-    count: number;
-    lastToolUseId: string;
-}
-/** Where a completed-work ledger entry came from. */
-type CompletedWorkSource = 'todo' | 'plan' | 'task' | 'verification' | 'manual';
-/**
- * One unit of finished work, kept in the session's completed-work ledger so
- * the model (and a resumed session) can see what is already done and build
- * on it instead of redoing it. Persisted via the completed-work checkpoint
- * (`storage/completed-work-checkpoint.ts`).
- */
-interface CompletedWorkEvidence {
-    /** Stable dedupe key — completing the same unit twice updates in place (e.g. "task:<id>"). */
-    key: string;
-    source: CompletedWorkSource;
-    summary: string;
-    /** Epoch ms when the work was marked complete. */
-    completedAt: number;
-    /** Optional pointer to proof (test run, commit hash, file path). */
-    evidence?: string | undefined;
-}
-interface ContextEvidenceState {
-    currentIntent?: ContextIntentEvidence | undefined;
-    sessionGoals: string[];
-    implicitFacts: string[];
-    activeErrors: string[];
-    toolCalls: ToolOutputMetadata[];
-    fileGraph: Record<string, ContextFileEvidence>;
-    repeatedReads: ContextRepeatedReadEvidence[];
-    /** Ledger of finished work (tasks, todos, verifications) — see {@link CompletedWorkEvidence}. */
-    completedWork: CompletedWorkEvidence[];
-    lastReadPath?: string | undefined;
-    updatedAt: number;
-}
-
-interface CacheStats {
-    /** Tokens served from cache (cheaper). */
-    readTokens: number;
-    /** Tokens written into the cache (more expensive than input on first hit). */
-    writeTokens: number;
-    /** Hit ratio: cacheRead / (cacheRead + input). 0 when nothing cached. */
-    hitRatio: number;
-}
-interface TokenCounter {
-    account(usage: Usage, model?: string): void | undefined;
-    /** Optional live session binding used by token.accounted events. */
-    setSessionId?(sessionId: string | (() => string | undefined) | undefined): void;
-    /**
-     * Disjoint token counts from the most recently-accounted request. Sum
-     * input + cacheRead + cacheWrite for per-request context pressure tracking
-     * (e.g. status bar ctx bar) — tokenCounter.total() is cumulative across all
-     * requests and cannot be compared meaningfully against a per-request
-     * maxContext ceiling.
-     */
-    currentRequestTokens(): {
-        input: number;
-        cacheRead: number;
-        cacheWrite: number;
-    };
-    /**
-     * Override the last-request token snapshot. Used by slash commands like
-     * /compact that modify ctx.messages without making an API request —
-     * after calling this, the TUI/REPL context bar reflects the new size.
-     */
-    setCurrentRequestTokens(input: number, cacheRead?: number, cacheWrite?: number): void;
-    total(): Usage;
-    estimateCost(): {
-        input: number;
-        output: number;
-        total: number;
-        currency: 'USD';
-    };
-    cacheStats(): CacheStats;
-    reset(): void;
-}
-
-/**
- * Observable wrapper for mutable conversation state. Production code should
- * mutate messages, todos, and meta through this API so subscribers see a
- * deterministic change stream. The underlying Context arrays are still
- * exposed for read compatibility and legacy tests.
- *
- * L1-A invariant: direct mutations of `ctx.messages` / `ctx.todos` bypass
- * the observer layer. Prefer `ctx.state.appendMessage()` etc. to keep
- * subscribers in sync. The compatibility arrays exist so existing code
- * that reads `ctx.messages` directly still works — they are NOT safe for
- * external writes.
- */
-type StateChange = {
-    kind: 'message_appended';
-    message: Message;
-} | {
-    kind: 'messages_replaced';
-    messages: readonly Message[];
-} | {
-    kind: 'message_updated';
-    index: number;
-    message: Message;
-} | {
-    kind: 'todos_replaced';
-    todos: readonly TodoItem[];
-} | {
-    kind: 'meta_set';
-    key: string;
-    value: unknown;
-} | {
-    kind: 'meta_deleted';
-    key: string;
-} | {
-    kind: 'meta_cleared';
-};
-type StateChangeHandler = (change: StateChange, state: ConversationState) => void;
-interface ReadonlyConversationState {
-    readonly messages: readonly Message[];
-    readonly todos: readonly TodoItem[];
-    readonly meta: Readonly<Record<string, unknown>>;
-}
-declare class ConversationState {
-    private readonly ctx;
-    private readonly listeners;
-    private _revision;
-    constructor(ctx: Context);
-    get messages(): readonly Message[];
-    get todos(): readonly TodoItem[];
-    get meta(): Readonly<Record<string, unknown>>;
-    /** Monotonic mutation counter for consumers that need to detect rewrites. */
-    get revision(): number;
-    /**
-     * Cheap immutable snapshot. Useful for tests and for compaction passes
-     * that need a stable view across an async boundary.
-     *
-     * Uses shallow-freeze instead of deep-freeze: only the wrapper object
-     * and the three content arrays are frozen. Individual message/todo
-     * objects are NOT recursively frozen — they are reconstructed via
-     * spread copies and are immutable by convention. This cuts the freeze
-     * count from O(n·m·d) (n=messages, m=content blocks, d=depth) to O(1).
-     */
-    snapshot(): ReadonlyConversationState;
-    appendMessage(message: Message): void;
-    /**
-     * Append a content block to the trailing user message's content array.
-     * Mutates only that one message (a single indexed assignment) — avoids
-     * the O(n) array copy + token-cache re-walk that `replaceMessages()`
-     * would do for a single-message edit. Used by the agent loop to fold
-     * btw-notes / queued-mailbox blocks into the conversation.
-     *
-     * The block is folded only into a *user* message (preserves
-     * user/assistant alternation between tool batches). Returns false when
-     * there is no trailing user message to fold into — callers should
-     * `appendMessage({ role: 'user', content: [block] })` instead.
-     */
-    appendBlockToLastUserMessage(block: ContentBlock): boolean;
-    replaceMessages(messages: Message[]): void;
-    replaceTodos(todos: TodoItem[]): void;
-    setMeta(key: string, value: unknown): void;
-    deleteMeta(key: string): void;
-    clearMeta(): void;
-    /**
-     * Subscribe to mutations that go through this wrapper. Direct mutations of
-     * the compatibility arrays are intentionally not observed.
-     */
-    onChange(listener: StateChangeHandler): () => void;
-    private emit;
-}
-/**
- * Convenience constructor. The wrapper holds a reference, not a copy.
- */
-declare function wrapAsState(ctx: Context): ConversationState;
-
-/**
- * Immutable run environment — the set-once dependencies for an agent run.
- *
- * `Context` today doubles as both a DI bag (provider, session, tokenCounter,
- * cwd, …) and a mutable state container (messages, todos, meta). That makes
- * it hard to test (every test reconstructs the full bag) and easy to abuse
- * (any tool can swap the provider mid-run).
- *
- * `RunEnv` is the immutable half: a read-only projection that subsystems
- * can hold instead of the whole `Context`. It's a view, not a copy — pulling
- * a `RunEnv` from a `Context` is O(1) and reflects the same underlying
- * references. The opposite direction (set things on Context) still works,
- * and `extractRunEnv` rebuilds the view if you need a snapshot.
- *
- * Migration path: new APIs accept `RunEnv` instead of `Context` when they
- * only need read access. Existing APIs continue to accept `Context` until
- * a full split is scheduled.
- */
-interface RunEnv {
-    readonly provider: Provider;
-    readonly session: SessionWriter;
-    readonly signal: AbortSignal;
-    readonly tokenCounter: TokenCounter;
-    readonly cwd: string;
-    readonly projectRoot: string;
-    /** Mutable working directory — starts as `cwd`. */
-    readonly workingDir: string;
-    readonly model: string;
-    readonly systemPrompt: readonly TextBlock[];
-    readonly tools: readonly Tool[];
-    readonly agentId: string;
-    readonly agentName: string;
-}
-/**
- * Build a `RunEnv` view from a Context. The returned object is a shallow
- * frozen view — mutations to `Context` are visible (it's the same
- * references), but the view itself can't be mutated.
- *
- * Use this in subsystems that want to declare "I only need read access to
- * the env" without rewriting their signature to accept the full Context.
- */
-declare function extractRunEnv(ctx: Context): RunEnv;
-
-interface TodoItem {
-    id: string;
-    content: string;
-    status: 'pending' | 'in_progress' | 'completed';
-    activeForm?: string | undefined;
-    /** When promoted from a plan item, stores the plan item's id. */
-    promotedFromPlan?: string | undefined;
-    /** When promoted from a task, stores the task's id. */
-    promotedFromTask?: string | undefined;
-}
-interface RunOptions {
-    signal?: AbortSignal | undefined;
-    model?: string | undefined;
-    executionStrategy?: 'parallel' | 'sequential' | 'smart' | undefined;
-    maxIterations?: number | undefined;
-    /**
-     * Enable autonomous continue for this specific run. When true, the agent
-     * loop re-runs on `[continue]`/`[next step]`/`[proceed]` markers or
-     * `continue_to_next_iteration()` tool calls instead of returning.
-     * Overrides `AgentInit.autonomousContinue` for this call only.
-     */
-    autonomousContinue?: boolean | undefined;
-}
-interface ContextInit {
-    systemPrompt: TextBlock[];
-    provider: Provider;
-    session: SessionWriter;
-    signal: AbortSignal;
-    tokenCounter: TokenCounter;
-    cwd: string;
-    projectRoot: string;
-    /** Mutable working directory. Defaults to `cwd`. Must stay within `projectRoot`. */
-    workingDir?: string | undefined;
-    /**
-     * When false, file tools and `setWorkingDir()` are confined to `projectRoot`.
-     * Defaults to `false` (restrictive) when omitted so directly-constructed
-     * contexts (tests, embedded callers) keep the safe behavior; the runtime
-     * passes the config-derived value (default `true` — permissive) explicitly.
-     */
-    allowOutsideProjectRoot?: boolean | undefined;
-    model: string;
-    tools?: Tool[] | undefined;
-    /** Agent id performing this run (e.g. 'leader', 'executor', 'tech-stack'). */
-    agentId?: string | undefined;
-    /** Human-readable agent name. */
-    agentName?: string | undefined;
-    /**
-     * Session-level trace ID for correlating storage events with agent
-     * iterations in observability pipelines. Stored on the SessionWriter
-     * so that storage operations can emit it in `storage.*` events.
-     * When set, the Context constructor propagates it to
-     * `session.traceId` automatically.
-     */
-    traceId?: string | undefined;
-}
-/**
- * L1-A: `Context` is the live agent-run object. Its read-only environment
- * shape is exposed by the `RunEnv` interface (every field below the
- * conversation state) and its mutable shape by `ConversationState` (the
- * `state` accessor). New code should declare the narrower type at its
- * parameter — pass `ctx` for it. Existing tools that accept `Context`
- * still work because `Context` structurally satisfies both.
- *
- * The single source of truth for the project directory is `projectRoot`.
- * All tools (read/write/bash/exec) resolve paths relative to this.
- * Sessions, config, memory, and logs are also stored under this root.
- *
- * There IS a mutable `workingDir` (separate from `projectRoot`) that can be
- * changed at runtime via `setWorkingDir()`. It starts as `cwd` and allows
- * the agent and user to navigate within the project without spawning a new
- * process. All changes must stay inside `projectRoot`.
- */
-declare class Context implements RunEnv {
-    messages: Message[];
-    todos: TodoItem[];
-    /**
-     * Files whose content the **user / model has explicitly seen** via the
-     * `read` tool (or an edit's auto-read, which surfaces the content to the
-     * model). This is the set the permission policy's write-smart-bypass
-     * (step 7) checks — writing a file the model has already read is treated
-     * as "no new content to approve". It must NEVER contain files only touched
-     * by `edit`/`write`, otherwise the model could repeatedly overwrite a file
-     * whose content the user never saw (P1 #1, before-release.md).
-     *
-     * Tool-driven mutations record via `writtenFiles` + `recordRead(..., 'write')`
-     * so mtime tracking still works without widening the bypass.
-     */
-    readFiles: Set<string>;
-    /**
-     * Files written by `edit`/`write` in this session. Tracked for observability
-     * and to keep `readFiles` (the permission-bypass source of truth) clean.
-     * `recordRead(path, mtime, 'write')` adds here instead of `readFiles`.
-     */
-    writtenFiles: Set<string>;
-    fileMtimes: Map<string, number>;
-    /**
-     * sha-256 (hex) of file content at the last recorded read/write, when the
-     * recording tool had the content in hand. Used by `edit` as the authoritative
-     * staleness arbiter: mtime comparison has a 2 s tolerance window on Windows
-     * (FAT/NTFS granularity) during which an external modification is invisible,
-     * and conversely a bare `touch` bumps mtime without changing content. Hash
-     * equality resolves both cases exactly. Entries are dropped whenever a
-     * hash-less `recordRead` observes a *different* mtime (content may have
-     * changed under us — fall back to the mtime heuristic rather than trust a
-     * stale hash).
-     */
-    fileHashes: Map<string, string>;
-    /**
-     * Structured side-effect records accumulated during the current run
-     * (P2 #5). Populated by `recordSideEffect()` — read by /diag for an
-     * in-memory audit trail without parsing the JSONL file. Cleared by
-     * `clearFileTracking()` alongside read/written-file tracking.
-     */
-    sideEffects: SideEffect[];
-    contextEvidence: ContextEvidenceState;
-    systemPrompt: TextBlock[];
-    provider: Provider;
-    session: SessionWriter;
-    signal: AbortSignal;
-    tokenCounter: TokenCounter;
-    cwd: string;
-    projectRoot: string;
-    /** Mutable working directory — starts as `cwd`. Change via `setWorkingDir()`. */
-    workingDir: string;
-    /**
-     * When true, file tools (via `_util.ts`) and `setWorkingDir()` reject paths
-     * outside `projectRoot`. When false, those boundary checks are bypassed so
-     * tools may reach paths outside the project (still gated by permission
-     * tiers). Mutable so `/settings` can toggle it live on the running session.
-     */
-    allowOutsideProjectRoot: boolean;
-    model: string;
-    tools: Tool[];
-    meta: Record<string, unknown>;
-    /** Agent id performing this run (e.g. 'leader', 'executor'). */
-    agentId: string;
-    /** Human-readable agent name. */
-    agentName: string;
-    /**
-     * Session-level trace ID for correlating storage events with agent
-     * iterations. Stored here and also propagated to `session.traceId`
-     * so storage operations can include it in `storage.*` events.
-     */
-    traceId: string | undefined;
-    /** Callbacks fired when `setWorkingDir()` changes the working directory. */
-    private _onWorkingDirChanged;
-    /**
-     * Set to true when the conversation gains new tool_use or tool_result
-     * blocks — the only time repairToolUseAdjacency() can find new issues.
-     * buildAndRunRequestPipeline() checks this flag to skip an O(n) scan
-     * on iterations where no tool content was added (pure text responses).
-     */
-    toolAdjacencyDirty: boolean;
-    /**
-     * H1: pre-computed total-request token estimate from the most recent
-     * `estimateRequestTokens()` call in the agent loop's pre-flight step.
-     * The middleware that decides when to compact, the `emitContextPct`
-     * helper that drives the live context-fill bar, and the pre-flight
-     * itself all need this number; previously each one walked the same
-     * messages/system/tools arrays independently. Stashing it here lets
-     * the three call sites share a single compute per iteration.
-     *
-     * The value is the **uncalibrated** total. Callers that want the
-     * calibrated number apply the per-(provider,model) ratio themselves.
-     */
-    lastRequestTokens: number | undefined;
-    constructor(init: ContextInit);
-    /**
-     * Observable wrapper over the mutable conversation state. Lazy so
-     * subsystems that don't subscribe pay nothing. Mutations made directly
-     * on `ctx.messages` / `ctx.todos` are still visible through this
-     * wrapper's read API (it holds a reference, not a copy) but only
-     * mutations that go through `state.appendMessage()` etc. fire
-     * `onChange`. New code should prefer the wrapper API.
-     */
-    private _state;
-    get state(): ConversationState;
-    /**
-     * Register a teardown hook tied to the current run's abort signal.
-     * Hooks registered before a run starts are stored and fired when the
-     * next run ends; there is no immediate fire when no run is active.
-     *
-     * **Scope:** these hooks fire on the **whole agent run's** abort, not on
-     * an individual tool call. For per-tool teardown of resources owned by
-     * the tool author (child processes, handles), prefer `Tool.cleanup` —
-     * see its JSDoc for the full rule.
-     */
-    private abortHooks;
-    registerAbortHook(fn: () => void | Promise<void>): () => void;
-    drainAbortHooks(): Promise<void>;
-    /**
-     * Record that a file's content was seen / mtime was observed.
-     *
-     * `source` controls which tracking set is populated — and therefore whether
-     * the permission policy's write-smart-bypass (step 7) will auto-approve a
-     * subsequent `write` to this path:
-     *
-     * - `'user'` (default): the model/user saw the content (via `read`, or an
-     *   edit's auto-read that surfaced it). Adds to `readFiles` → bypass applies.
-     * - `'write'`: a tool wrote the file (`edit`/`write`) and is recording the
-     *   new mtime so subsequent edits detect external modification. Adds to
-     *   `writtenFiles` only — the bypass does NOT apply, because the user never
-     *   approved the new content (P1 #1, before-release.md).
-     *
-     * `fileMtimes` is updated in both cases so mtime-based staleness checks work.
-     *
-     * `contentHash` (sha-256 hex of the exact content seen) is optional so
-     * existing callers keep working. When provided it is stored in `fileHashes`
-     * and becomes the authoritative staleness arbiter for later edits. When
-     * omitted, a previously stored hash survives only if the observed mtime is
-     * unchanged — a different mtime with no fresh hash means the content may
-     * have changed, so the stale hash is dropped and staleness checks fall back
-     * to mtime comparison.
-     */
-    recordRead(absPath: string, mtimeMs: number, source?: 'user' | 'write', contentHash?: string): void;
-    /** Clear accumulated file-read metadata after compaction or at boundaries
-     *  where stale read history could cause tools to skip legitimate re-reads.
-     *  The agent re-populates this naturally on the next file access. */
-    clearFileTracking(): void;
-    /**
-     * Record a structured side effect for the audit trail (P2 #5).
-     * Called by tools that perform non-filesystem mutations (bash, install,
-     * fetch) so /diag and session replay can show what the agent did beyond
-     * file edits.
-     *
-     * Unlike recordFileChange(), this does NOT support undo — it is purely
-     * for observability and audit. The event is appended to the session
-     * JSONL fire-and-forget; errors are swallowed so recording never blocks
-     * tool execution.
-     */
-    recordSideEffect(sideEffect: SideEffect): void;
-    /**
-     * True if the model/user has explicitly seen this file's content via `read`
-     * (or an edit auto-read). Tool-only writes (`source: 'write'`) do NOT count
-     * — this is the source of truth for the permission policy's write bypass.
-     */
-    hasRead(absPath: string): boolean;
-    /** True if `edit`/`write` wrote this file in the current session. */
-    hasWritten(absPath: string): boolean;
-    lastReadMtime(absPath: string): number | undefined;
-    /** sha-256 (hex) of the content at the last recorded read/write, if the
-     *  recording tool supplied one. See `fileHashes` for drop semantics. */
-    lastReadHash(absPath: string): string | undefined;
-    /**
-     * Change the working directory for path resolution. Resolves relative paths
-     * against `projectRoot` and validates the result is within the project root.
-     * Fires all registered `onWorkingDirChanged` callbacks.
-     * Returns the resolved absolute path.
-     */
-    setWorkingDir(dir: string): string;
-    /**
-     * Register a callback that fires when the working directory changes.
-     * Returns an unsubscribe function. Callbacks are fired synchronously
-     * inside `setWorkingDir()` — errors in callbacks are swallowed so one
-     * bad listener doesn't prevent others from executing.
-     */
-    onWorkingDirChanged(cb: (newDir: string, oldDir: string) => void): () => void;
-    usage(): Usage;
-}
-
-type Permission = 'auto' | 'confirm' | 'deny';
-/**
- * Risk tier for tools in YOLO mode. YOLO auto-approves normal project work,
- * while clearly destructive calls still require confirmation.
- *
- * - `safe`       — read-only, no side effects (read, glob, grep, etc.)
- * - `standard`   — non-destructive writes and mutations (write, edit, safe shell commands)
- * - `destructive` — irreversible or broadside effects (recursive deletes, db drops, etc.)
- */
-type RiskTier = 'safe' | 'standard' | 'destructive';
-/**
- * Icon identifiers for tools — each UI (WebUI/TUI/REPL) maps these to its own icon library.
- * Add the icon directly on each Tool so all UIs consume the same canonical value.
- */
-type ToolIconId = 'file' | 'edit' | 'search' | 'folder' | 'terminal' | 'web' | 'git' | 'tree' | 'code' | 'test' | 'package' | 'document' | 'scaffold' | 'todo' | 'plan' | 'task' | 'meta' | 'index' | 'json' | 'diff' | 'logs' | 'settings' | 'fallback';
-interface JSONSchema {
-    type?: string | undefined;
-    properties?: Record<string, JSONSchema>;
-    required?: string[] | undefined;
-    items?: JSONSchema | undefined;
-    enum?: unknown[] | undefined;
-    description?: string | undefined;
-    [k: string]: unknown;
-}
-/**
- * Tool progress event — yielded by `Tool.executeStream` to give the UI
- * something to render while a long-running tool works. The executor
- * publishes each event via EventBus as `tool.progress` so the TUI, logger,
- * and observability layer can consume them uniformly.
- *
- * Keep events small. They are buffered through the EventBus synchronously
- * and rendered on the main thread.
- */
-interface ToolProgressEvent {
-    /**
-     * - `log`           — verbose informational message (e.g. "scanning…")
-     * - `warning`       — non-fatal issue (e.g. "skipped X due to ENOENT")
-     * - `metric`        — numeric data (e.g. files scanned so far)
-     * - `file_changed`  — a tool that mutates the workspace announces a write
-     * - `partial_output` — stream of textual output (bash stdout, fetch body)
-     */
-    type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output';
-    text?: string | undefined;
-    data?: Record<string, unknown>;
-}
-/**
- * Terminal event for `executeStream`. The output must match the tool's
- * declared output type — the executor unwraps `output` and treats it like
- * a normal `execute` return value.
- */
-interface ToolFinalEvent<O> {
-    type: 'final';
-    output: O;
-}
-type ToolStreamEvent<O = unknown> = ToolProgressEvent | ToolFinalEvent<O>;
-interface Tool<I = unknown, O = unknown> {
-    name: string;
-    description: string;
-    /**
-     * Pre-computed token estimate for this tool's definition (name +
-     * description + JSON-serialized inputSchema). Set by ToolRegistry on
-     * registration; consumed by estimateToolDefTokens / estimateRequestTokens
-     * to skip redundant JSON.stringify on every context-pressure check.
-     */
-    _estDefTokens?: number | undefined;
-    usageHint?: string | undefined;
-    /** Structured guidance for choosing between similar tools. */
-    selection?: {
-        /** A concise boundary where this tool should not be selected. */
-        doNotUseWhen: string;
-        /** Tool names the model should prefer for that boundary. */
-        useInstead?: readonly string[] | undefined;
-    } | undefined;
-    /** Optional category for grouping in help lists and system prompts. */
-    category?: string | undefined;
-    inputSchema: JSONSchema;
-    permission: Permission;
-    mutating: boolean;
-    /**
-     * Risk tier for selective YOLO gating. When YOLO is active, clearly
-     * destructive calls still emit `confirm`. Defaults to `standard` when
-     * omitted — callers should always check `riskTier` after the basic
-     * permission decision.
-     */
-    riskTier?: RiskTier | undefined;
-    /**
-     * Input-field name that the permission policy should match trust rules
-     * against. Without this, the policy falls back to a heuristic
-     * (`command` / `path` / `url` / `name`) that can collide across tools —
-     * e.g. an HTTP tool whose `path` means "request path" would be checked
-     * against filesystem-path trust rules. Set explicitly to avoid the
-     * cross-tool subject collision.
-     *
-     * The named field's value must be a string at runtime; non-string values
-     * fall back to the heuristic.
-     */
-    subjectKey?: string | undefined;
-    maxOutputBytes?: number | undefined;
-    timeoutMs?: number | undefined;
-    /**
-     * Hint for the TUI spinner — does NOT affect actual timeout enforcement.
-     * Use `timeoutMs` for hard limits. Leave undefined when duration varies
-     * unpredictably.
-     */
-    estimatedDurationMs?: number | undefined;
-    /**
-     * Declarative security capabilities granted by this tool.
-     *
-     * Examples: "shell.arbitrary", "fs.write", "fs.write.outside-project",
-     * "net.outbound", "mcp.proxy", "subagent.spawn", "config.mutate".
-     *
-     * These are used by permission policies (especially subagent guards) and
-     * future capability-based allowlists. Prefer well-known values over ad-hoc strings.
-     *
-     * This field is optional for backward compatibility. Tools without it are
-     * treated conservatively by guards.
-     */
-    capabilities?: readonly string[] | undefined;
-    /**
-     * Icon identifier for this tool — consumed by all UIs (WebUI/TUI/REPL) to
-     * render a tool-specific icon instead of a generic fallback.
-     * Each UI maps this id to its own icon library.
-     */
-    icon?: ToolIconId | undefined;
-    execute(input: I, ctx: Context, opts: {
-        signal: AbortSignal;
-    }): Promise<O>;
-    /**
-     * Optional cross-field validation hook. Called by the executor AFTER
-     * JSON Schema validation passes and AFTER PreToolUse hooks may have
-     * rewritten the input, but BEFORE permission checks and execution.
-     *
-     * Use this for invariants the JSON Schema cannot express — e.g.
-     * `old_string !== new_string` in edit, or `end > start` in a range tool.
-     * Return an array of validation errors (empty = valid). The executor
-     * surfaces them to the model just like schema validation errors, so the
-     * model can self-correct without the tool's `execute()` running.
-     *
-     * P3 #16 (before-release.md): tools that implement cross-field checks
-     * inside `execute()` can migrate them here for earlier rejection and
-     * consistent error formatting.
-     */
-    validate?(input: I): string[];
-    /**
-     * Optional streaming variant. When defined, the executor prefers this
-     * over `execute` — yielded events become `tool.progress` EventBus events
-     * and the terminal `final` event provides the output. Tools that don't
-     * have intermediate state shouldn't implement this; the default `execute`
-     * path is more efficient.
-     */
-    executeStream?(input: I, ctx: Context, opts: {
-        signal: AbortSignal;
-    }): AsyncIterable<ToolStreamEvent<O>>;
-    /**
-     * Optional teardown hook fired by the executor when the tool's run is
-     * aborted (signal triggered). Errors thrown here are swallowed so they
-     * never mask the originating failure.
-     *
-     * **When to use `cleanup` vs `ctx.registerAbortHook`:**
-     *
-     * - Use `cleanup` for resources **owned by the tool author** that are
-     *   established at execute-time: child processes spawned by the tool,
-     *   file handles opened by the tool, network connections initiated by
-     *   the tool. The lifecycle is co-located with the tool definition, so
-     *   readers see the resource and its teardown in one place.
-     *
-     *   ```ts
-     *   async execute(input, ctx, opts) {
-     *     const child = spawn(...);
-     *     // … tool work …
-     *   },
-     *   async cleanup(_input, _ctx) {
-     *     // best-effort kill of any child still running
-     *   }
-     *   ```
-     *
-     * - Use `ctx.registerAbortHook` for **context-scoped teardown** registered
-     *   dynamically inside `execute`: when the tool delegates to a library
-     *   that needs cancellation, or when the resource is created lazily
-     *   somewhere down the call stack and the natural cleanup point isn't
-     *   at the tool boundary. The hook fires when the **agent run** ends,
-     *   not when this specific tool call aborts.
-     *
-     *   ```ts
-     *   async execute(input, ctx, opts) {
-     *     const handle = openHelper();
-     *     ctx.registerAbortHook(() => handle.dispose());
-     *     // … work …
-     *   }
-     *   ```
-     *
-     * If both are registered for the same resource, `cleanup` fires first
-     * (on tool abort) and the abort-hook fires after on the wider run abort.
-     * Avoid double-free by gating one on the other's effect, or pick a single
-     * teardown channel per resource.
-     */
-    cleanup?(input: I, ctx: Context): Promise<void>;
-    /**
-     * Optional custom output serializer. When present, the executor's output
-     * serializer calls this INSTEAD of the central `renderToolObject()` switch
-     * — the tool owns its own pretty-printing.
-     *
-     * Return a string representation of the output that the model will see in
-     * its tool_result block. The serializer applies the iteration output cap
-     * AFTER this runs, so don't worry about truncation.
-     *
-     * P3 #21 (before-release.md): `renderToolObject()` is a god function with
-     * 30+ per-tool branches, far from each tool's definition. New tools that
-     * want custom output no longer need to add a branch there — they implement
-     * this method instead. Existing branches stay until migrated incrementally.
-     */
-    serialize?(output: O, input: I): string;
-}
-interface ToolCallContext {
-    tool: Tool;
-    input: unknown;
-    callId: string;
-    ctx: Context;
-    signal: AbortSignal;
-}
-/**
- * Error categories for tool execution failures.
- * Used by the executor to classify errors and determine retry strategy.
- */
-declare enum ToolErrorCategory {
-    TRANSIENT = "transient",// ETIMEDOUT, ECONNRESET, network timeout, HTTP 429/503
-    NOT_FOUND = "not_found",// ENOENT, ENOTDIR, HTTP 404
-    PERMISSION = "permission",// EACCES, EPERM, HTTP 401/403
-    VALIDATION = "validation",// schema validation error, HTTP 400
-    FATAL = "fatal"
-}
-/**
- * Structured tool error information for the LLM and retry logic.
- */
-interface ToolErrorInfo {
-    readonly category: ToolErrorCategory;
-    /** Whether the operation can be retried automatically. */
-    readonly retryable: boolean;
-    /** User-facing message describing the error. */
-    readonly userMessage: string;
-    /** Optional technical detail for debugging. */
-    readonly detail?: string;
-}
-
-export { type FileSnapshot as $, type TodoItem as A, type ToolUseBlock as B, type CacheStats as C, type ToolResultBlock as D, AgentError as E, type ForkedSession as F, type CompletedWorkEvidence as G, type CompletedWorkSource as H, ConfigError as I, type JSONSchema as J, type ContextEvidenceState as K, type ContextFileEvidence as L, type Message as M, type ContextInit as N, type ContextIntentEvidence as O, type Provider as P, type ContextRepeatedReadEvidence as Q, type ReasoningRequest as R, type SessionEvent as S, type TokenCounter as T, type Usage as U, ERROR_CODES as V, type WorkspaceCheckpointRef as W, type ErrorCode as X, type ErrorSeverity as Y, type ErrorSubsystem as Z, FetchError as _, type ReasoningConfig as a, FsError as a0, type ImageBlock as a1, type JsonSchemaSpec as a2, type MessageRole as a3, ParseError as a4, PluginError as a5, type ProviderErrorBody as a6, type ProviderErrorKind as a7, type ReadonlyConversationState as a8, type RequestCacheControl as a9, effectiveInputTokens as aA, extractRunEnv as aB, isAgentError as aC, isConfigError as aD, isFetchError as aE, isFsError as aF, isImageBlock as aG, isParseError as aH, isPluginError as aI, isRetryableKind as aJ, isSddError as aK, isSessionError as aL, isTextBlock as aM, isToolError as aN, isToolResultBlock as aO, isToolUseBlock as aP, isToolValidationError as aQ, isWrongStackError as aR, toWrongStackError as aS, wrapAsState as aT, type ResponseFormat as aa, type ResumeFileStatus as ab, type ResumeFileValidationEntry as ac, type ResumeValidation as ad, type RunEnv as ae, type SafetySetting as af, SddError as ag, SessionError as ah, type SideEffect as ai, type SideEffectRisk as aj, type StateChange as ak, type StateChangeHandler as al, type StopReason as am, type StreamEvent as an, StreamHangError as ao, type ThinkingBlock as ap, type ToolCallContext as aq, ToolError as ar, type ToolErrorInfo as as, type ToolEvidenceStatus as at, type ToolFinalEvent as au, type ToolIconId as av, type ToolStreamEvent as aw, ToolValidationError as ax, WrongStackError as ay, classifyProviderError as az, type SessionWriter as b, type Request as c, Context as d, type Response as e, type Permission as f, type Tool as g, ProviderError as h, type ContentBlock as i, type SessionMetadata as j, type SessionStore as k, ToolErrorCategory as l, type ToolProgressEvent as m, type RiskTier as n, type ToolOutputMetadata as o, type ReasoningEffort as p, type CacheTtl as q, type Capabilities as r, type TextBlock as s, type RunOptions as t, ConversationState as u, type SessionForkOptions as v, type WorkspaceMaterializationResult as w, type ResumedSession as x, type SessionData as y, type SessionSummary as z };