@wrongstack/core 0.1.9 → 0.1.10

package/dist/{provider-txgB0Oq9.d.ts → context-BmM2xGUZ.d.ts}

@@ -46,11 +46,34 @@ interface ImageBlock {
         url?: string;
     };
 }
-type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ImageBlock;
+/**
+ * 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;
+    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;
+declare function isThinkingBlock(b: ContentBlock): b is ThinkingBlock;
 
 type MessageRole = 'user' | 'assistant' | 'system';
 interface Message {
@@ -60,379 +83,115 @@ interface Message {
 declare function asBlocks(content: string | ContentBlock[]): ContentBlock[];
 declare function asText(content: string | ContentBlock[]): string;
 
-interface SessionMetadata {
-    id: string;
-    title?: string;
-    model?: string;
-    provider?: string;
-    startedAt: string;
-    endedAt?: string;
-}
-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: 'user_input';
-    ts: string;
-    content: string | ContentBlock[];
-} | {
-    type: 'llm_request';
-    ts: string;
-    model: string;
-    messageCount: number;
-} | {
-    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;
-} | {
-    type: 'compaction';
-    ts: string;
-    before: number;
-    after: number;
-} | {
-    type: 'error';
-    ts: string;
-    message: string;
-    phase: string;
-} | {
-    type: 'session_end';
-    ts: string;
-    usage: Usage;
-} | {
-    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;
-    outputSize: number;
-} | {
-    type: 'message_truncated';
-    ts: string;
-    before: number;
-    after: number;
-};
-interface SessionSummary {
-    id: string;
-    title: string;
-    startedAt: string;
-    model: string;
-    provider: string;
-    tokenTotal: number;
-}
-interface SessionData {
-    metadata: SessionMetadata;
-    events: SessionEvent[];
-    messages: Message[];
-    usage: Usage;
-}
-interface ResumedSession {
-    writer: SessionWriter;
-    data: SessionData;
-}
-interface SessionStore {
-    create(meta: Omit<SessionMetadata, 'startedAt'>): Promise<SessionWriter>;
-    load(id: string): Promise<SessionData>;
+/**
+ * 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.
+ */
+type ErrorCode = 'PROVIDER_RATE_LIMITED' | 'PROVIDER_AUTH_FAILED' | 'PROVIDER_OVERLOADED' | 'PROVIDER_INVALID_REQUEST' | 'PROVIDER_SERVER_ERROR' | 'PROVIDER_NETWORK_ERROR' | 'PROVIDER_CONTEXT_OVERFLOW' | 'TOOL_NOT_FOUND' | 'TOOL_PERMISSION_DENIED' | 'TOOL_EXECUTION_FAILED' | 'TOOL_TIMEOUT' | 'TOOL_INPUT_INVALID' | 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_PARSE_FAILED' | 'CONFIG_MIGRATION_NEEDED' | 'PLUGIN_LOAD_FAILED' | 'PLUGIN_API_MISMATCH' | 'PLUGIN_MISSING_DEPENDENCY' | 'AGENT_ITERATION_LIMIT' | 'AGENT_CONTEXT_OVERFLOW' | 'AGENT_ABORTED' | 'AGENT_RUN_FAILED' | 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED' | 'CONTAINER_TOKEN_ALREADY_BOUND' | 'CONTAINER_TOKEN_NOT_BOUND' | 'REGISTRY_DUPLICATE' | 'REGISTRY_NOT_FOUND' | 'UNKNOWN';
+type ErrorSubsystem = 'provider' | 'tool' | 'config' | 'plugin' | 'agent' | 'session' | 'container' | '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>;
+    constructor(opts: {
+        message: string;
+        code: ErrorCode;
+        subsystem: ErrorSubsystem;
+        severity?: ErrorSeverity;
+        recoverable?: boolean;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
     /**
-     * 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.
+     * Render a one-line user-facing description.
+     * Subclasses should override for domain-specific formatting.
      */
-    resume(id: string): Promise<ResumedSession>;
-    list(limit?: number): Promise<SessionSummary[]>;
-    delete(id: string): Promise<void>;
-}
-interface SessionWriter {
-    readonly id: string;
-    append(event: SessionEvent): Promise<void>;
-    close(): Promise<void>;
+    describe(): string;
 }
-
-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;
+/**
+ * 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;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
 }
-interface TokenCounter {
-    account(usage: Usage, model?: string): void;
-    total(): Usage;
-    estimateCost(): {
-        input: number;
-        output: number;
-        total: number;
-        currency: 'USD';
-    };
-    cacheStats(): CacheStats;
-    reset(): void;
+/**
+ * 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>;
+        cause?: unknown;
+    });
 }
-
 /**
- * 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.
+ * Plugin loading / lifecycle errors.
  */
-interface RunEnv {
-    readonly provider: Provider;
-    readonly session: SessionWriter;
-    readonly signal: AbortSignal;
-    readonly tokenCounter: TokenCounter;
-    readonly cwd: string;
-    readonly projectRoot: string;
-    readonly model: string;
-    readonly systemPrompt: readonly TextBlock[];
-    readonly tools: readonly Tool[];
+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>;
+        cause?: unknown;
+    });
 }
 /**
- * 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;
-
-/**
- * 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.
+ * Agent runtime errors — thrown by Agent.run when a non-WrongStackError
+ * escapes the inner loop, so callers always see a structured error.
  */
-type StateChange = {
-    kind: 'message_appended';
-    message: Message;
-} | {
-    kind: 'messages_replaced';
-    messages: readonly 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;
-    constructor(ctx: Context);
-    get messages(): readonly Message[];
-    get todos(): readonly TodoItem[];
-    get meta(): Readonly<Record<string, unknown>>;
-    /**
-     * Cheap immutable snapshot. Useful for tests and for compaction passes
-     * that need a stable view across an async boundary.
-     */
-    snapshot(): ReadonlyConversationState;
-    appendMessage(message: Message): void;
-    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;
+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;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
 }
 /**
- * Convenience constructor. The wrapper holds a reference, not a copy.
+ * 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 wrapAsState(ctx: Context): ConversationState;
-
-interface TodoItem {
-    id: string;
-    content: string;
-    status: 'pending' | 'in_progress' | 'completed';
-    activeForm?: string;
-}
-interface RunOptions {
-    signal?: AbortSignal;
-    model?: string;
-    executionStrategy?: 'parallel' | 'sequential' | 'smart';
-    maxIterations?: number;
-}
-interface ContextInit {
-    systemPrompt: TextBlock[];
-    provider: Provider;
-    session: SessionWriter;
-    signal: AbortSignal;
-    tokenCounter: TokenCounter;
-    cwd: string;
-    projectRoot: string;
-    model: string;
-    tools?: Tool[];
-}
+declare function toWrongStackError(err: unknown, code?: Extract<ErrorCode, 'AGENT_RUN_FAILED' | 'AGENT_ABORTED' | 'UNKNOWN'>): WrongStackError;
 /**
- * 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.
+ * Session storage errors.
  */
-declare class Context implements RunEnv {
-    messages: Message[];
-    todos: TodoItem[];
-    readFiles: Set<string>;
-    fileMtimes: Map<string, number>;
-    systemPrompt: TextBlock[];
-    provider: Provider;
-    session: SessionWriter;
-    signal: AbortSignal;
-    tokenCounter: TokenCounter;
-    cwd: string;
-    projectRoot: string;
-    model: string;
-    tools: Tool[];
-    meta: Record<string, unknown>;
-    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. The
-     * hook fires when the run aborts OR ends normally — Agent.run wires
-     * this through a RunController. When no run is active the hook fires
-     * immediately so callers don't leak resources.
-     *
-     * **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>;
-    recordRead(absPath: string, mtimeMs: number): void;
-    hasRead(absPath: string): boolean;
-    lastReadMtime(absPath: string): number | undefined;
-    usage(): Usage;
+declare class SessionError extends WrongStackError {
+    readonly sessionId?: string;
+    constructor(opts: {
+        message: string;
+        code: Extract<ErrorCode, 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED'>;
+        sessionId?: string;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+    });
 }
+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;
 
 type Permission = 'auto' | 'confirm' | 'deny';
 interface JSONSchema {
@@ -569,120 +328,30 @@ interface ToolCallContext {
 }
 
 /**
- * WrongStack error hierarchy.
+ * Token usage for a single provider call, normalized across providers.
  *
- * 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.
- */
-type ErrorCode = 'PROVIDER_RATE_LIMITED' | 'PROVIDER_AUTH_FAILED' | 'PROVIDER_OVERLOADED' | 'PROVIDER_INVALID_REQUEST' | 'PROVIDER_SERVER_ERROR' | 'PROVIDER_NETWORK_ERROR' | 'PROVIDER_CONTEXT_OVERFLOW' | 'TOOL_NOT_FOUND' | 'TOOL_PERMISSION_DENIED' | 'TOOL_EXECUTION_FAILED' | 'TOOL_TIMEOUT' | 'TOOL_INPUT_INVALID' | 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_PARSE_FAILED' | 'CONFIG_MIGRATION_NEEDED' | 'PLUGIN_LOAD_FAILED' | 'PLUGIN_API_MISMATCH' | 'PLUGIN_MISSING_DEPENDENCY' | 'AGENT_ITERATION_LIMIT' | 'AGENT_CONTEXT_OVERFLOW' | 'AGENT_ABORTED' | 'AGENT_RUN_FAILED' | 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED' | 'CONTAINER_TOKEN_ALREADY_BOUND' | 'CONTAINER_TOKEN_NOT_BOUND' | 'REGISTRY_DUPLICATE' | 'REGISTRY_NOT_FOUND' | 'UNKNOWN';
-type ErrorSubsystem = 'provider' | 'tool' | 'config' | 'plugin' | 'agent' | 'session' | 'container' | '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>;
-    constructor(opts: {
-        message: string;
-        code: ErrorCode;
-        subsystem: ErrorSubsystem;
-        severity?: ErrorSeverity;
-        recoverable?: boolean;
-        context?: Record<string, unknown>;
-        cause?: unknown;
-    });
-    /**
-     * 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.
+ * 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.
  */
-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;
-        context?: Record<string, unknown>;
-        cause?: unknown;
-    });
-}
-/**
- * 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>;
-        cause?: unknown;
-    });
-}
-/**
- * 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>;
-        cause?: unknown;
-    });
-}
-/**
- * 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;
-        context?: Record<string, unknown>;
-        cause?: unknown;
-    });
-}
-/**
- * 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;
-    constructor(opts: {
-        message: string;
-        code: Extract<ErrorCode, 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED'>;
-        sessionId?: string;
-        context?: Record<string, unknown>;
-        cause?: unknown;
-    });
-}
-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;
-
-interface Usage {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
+interface Usage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
 }
 interface Capabilities {
     tools: boolean;
@@ -721,7 +390,7 @@ type StreamEvent = {
     model: string;
 } | {
     type: 'content_block_start';
-    kind: 'text' | 'tool_use';
+    kind: 'text' | 'tool_use' | 'thinking';
     id?: string;
     name?: string;
 } | {
@@ -743,6 +412,17 @@ type StreamEvent = {
     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;
@@ -807,4 +487,384 @@ declare class ProviderError extends WrongStackError {
     describe(): string;
 }
 
-export { toWrongStackError as $, AgentError as A, type ToolResultBlock as B, type CacheStats as C, type ToolStreamEvent as D, type ErrorCode as E, type ToolUseBlock as F, asBlocks as G, asText as H, type ImageBlock as I, type JSONSchema as J, isAgentError as K, isConfigError as L, type Message as M, isImageBlock as N, isPluginError as O, type Permission as P, isSessionError as Q, type Request as R, type SessionData as S, type TextBlock as T, type Usage as U, isTextBlock as V, WrongStackError as W, isToolError as X, isToolResultBlock as Y, isToolUseBlock as Z, isWrongStackError as _, type Capabilities as a, Context as a0, type ContextInit as a1, ConversationState as a2, type ReadonlyConversationState as a3, type RunEnv as a4, type RunOptions as a5, type StateChange as a6, type StateChangeHandler as a7, type TodoItem as a8, extractRunEnv as a9, wrapAsState as aa, ConfigError as b, type ContentBlock as c, type ErrorSeverity as d, type ErrorSubsystem as e, type MessageRole as f, PluginError as g, type Provider as h, ProviderError as i, type ProviderErrorBody as j, type Response as k, type ResumedSession as l, SessionError as m, type SessionEvent as n, type SessionMetadata as o, type SessionStore as p, type SessionSummary as q, type SessionWriter as r, type StopReason as s, type StreamEvent as t, type TokenCounter as u, type Tool as v, type ToolCallContext as w, ToolError as x, type ToolFinalEvent as y, type ToolProgressEvent as z };
+interface SessionMetadata {
+    id: string;
+    title?: string;
+    model?: string;
+    provider?: string;
+    startedAt: string;
+    endedAt?: string;
+}
+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: 'user_input';
+    ts: string;
+    content: string | ContentBlock[];
+} | {
+    type: 'llm_request';
+    ts: string;
+    model: string;
+    messageCount: number;
+} | {
+    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;
+} | {
+    type: 'compaction';
+    ts: string;
+    before: number;
+    after: number;
+} | {
+    type: 'error';
+    ts: string;
+    message: string;
+    phase: string;
+} | {
+    type: 'session_end';
+    ts: string;
+    usage: Usage;
+} | {
+    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;
+    outputSize: number;
+} | {
+    type: 'message_truncated';
+    ts: string;
+    before: number;
+    after: number;
+};
+interface SessionSummary {
+    id: string;
+    title: string;
+    startedAt: string;
+    model: string;
+    provider: string;
+    tokenTotal: number;
+}
+interface SessionData {
+    metadata: SessionMetadata;
+    events: SessionEvent[];
+    messages: Message[];
+    usage: Usage;
+}
+interface ResumedSession {
+    writer: SessionWriter;
+    data: SessionData;
+}
+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>;
+    list(limit?: number): Promise<SessionSummary[]>;
+    delete(id: string): Promise<void>;
+}
+interface SessionWriter {
+    readonly id: string;
+    append(event: SessionEvent): Promise<void>;
+    close(): Promise<void>;
+}
+
+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;
+    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: '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;
+    constructor(ctx: Context);
+    get messages(): readonly Message[];
+    get todos(): readonly TodoItem[];
+    get meta(): Readonly<Record<string, unknown>>;
+    /**
+     * Cheap immutable snapshot. Useful for tests and for compaction passes
+     * that need a stable view across an async boundary.
+     */
+    snapshot(): ReadonlyConversationState;
+    appendMessage(message: Message): void;
+    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;
+    readonly model: string;
+    readonly systemPrompt: readonly TextBlock[];
+    readonly tools: readonly Tool[];
+}
+/**
+ * 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;
+}
+interface RunOptions {
+    signal?: AbortSignal;
+    model?: string;
+    executionStrategy?: 'parallel' | 'sequential' | 'smart';
+    maxIterations?: number;
+}
+interface ContextInit {
+    systemPrompt: TextBlock[];
+    provider: Provider;
+    session: SessionWriter;
+    signal: AbortSignal;
+    tokenCounter: TokenCounter;
+    cwd: string;
+    projectRoot: string;
+    model: string;
+    tools?: Tool[];
+}
+/**
+ * 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.
+ */
+declare class Context implements RunEnv {
+    messages: Message[];
+    todos: TodoItem[];
+    readFiles: Set<string>;
+    fileMtimes: Map<string, number>;
+    systemPrompt: TextBlock[];
+    provider: Provider;
+    session: SessionWriter;
+    signal: AbortSignal;
+    tokenCounter: TokenCounter;
+    cwd: string;
+    projectRoot: string;
+    model: string;
+    tools: Tool[];
+    meta: Record<string, unknown>;
+    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. The
+     * hook fires when the run aborts OR ends normally — Agent.run wires
+     * this through a RunController. When no run is active the hook fires
+     * immediately so callers don't leak resources.
+     *
+     * **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>;
+    recordRead(absPath: string, mtimeMs: number): void;
+    hasRead(absPath: string): boolean;
+    lastReadMtime(absPath: string): number | undefined;
+    usage(): Usage;
+}
+
+export { toWrongStackError as $, AgentError as A, type ToolStreamEvent as B, type Capabilities as C, type ToolUseBlock as D, type ErrorCode as E, asBlocks as F, asText as G, isAgentError as H, type ImageBlock as I, type JSONSchema as J, isConfigError as K, isImageBlock as L, type Message as M, isPluginError as N, isSessionError as O, type Permission as P, isTextBlock as Q, type Request as R, type SessionData as S, type TextBlock as T, type Usage as U, isThinkingBlock as V, WrongStackError as W, isToolError as X, isToolResultBlock as Y, isToolUseBlock as Z, isWrongStackError as _, ConfigError as a, Context as a0, type TokenCounter as a1, type CacheStats as a2, type ContextInit as a3, ConversationState as a4, type ReadonlyConversationState as a5, type RunEnv as a6, type RunOptions as a7, type StateChange as a8, type StateChangeHandler as a9, type TodoItem as aa, extractRunEnv as ab, wrapAsState as ac, type ContentBlock as b, type ErrorSeverity as c, type ErrorSubsystem as d, type MessageRole as e, PluginError as f, type Provider as g, ProviderError as h, type ProviderErrorBody as i, type Response as j, type ResumedSession as k, SessionError as l, type SessionEvent as m, type SessionMetadata as n, type SessionStore as o, type SessionSummary as p, type SessionWriter as q, type StopReason as r, type StreamEvent as s, type ThinkingBlock as t, type Tool as u, type ToolCallContext as v, ToolError as w, type ToolFinalEvent as x, type ToolProgressEvent as y, type ToolResultBlock as z };