@wrongstack/core 0.1.1 → 0.1.3

package/dist/provider-DovtyuM8.d.ts

@@ -0,0 +1,813 @@
+interface TextBlock {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+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;
+    content: string;
+    is_error?: boolean;
+}
+interface ImageBlock {
+    type: 'image';
+    source: {
+        type: 'base64' | 'url';
+        media_type?: string;
+        data?: string;
+        url?: string;
+    };
+}
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ImageBlock;
+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;
+
+type MessageRole = 'user' | 'assistant' | 'system';
+interface Message {
+    role: MessageRole;
+    content: string | ContentBlock[];
+}
+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>;
+    /**
+     * 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;
+}
+
+/**
+ * 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;
+
+/**
+ * Observable wrapper for the mutable conversation state. Provides snapshot
+ * and change-notification semantics on top of the existing `Context`
+ * mutable fields (messages, todos, meta), without forcing every call site
+ * to migrate.
+ *
+ * Design notes:
+ *
+ *  - This is a **wrapper**, not a replacement. The underlying `Context`
+ *    fields are still mutated directly by tools and middleware that don't
+ *    know about ConversationState. The wrapper observes those mutations by
+ *    snapshotting on each accessor call, comparing length/identity, and
+ *    firing onChange. This is intentional during migration: it lets new
+ *    code subscribe to changes without breaking the unaware-existing code.
+ *
+ *  - For full decoupling (the dev-plan #1 target), every mutation must go
+ *    through `ConversationState.appendMessage()` etc. instead of
+ *    `ctx.messages.push(...)`. That's a follow-up refactor — the API shape
+ *    here is designed to support it.
+ *
+ *  - `meta` is a free-form bag; we shallow-watch its keys. Deep mutations
+ *    inside `meta.foo` won't trigger onChange. Use immutable replacement
+ *    (`setMeta('foo', newValue)`) if you need notification.
+ */
+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;
+};
+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;
+    /**
+     * Subscribe to mutations that go through this wrapper. Note: mutations
+     * that bypass the wrapper (e.g. `ctx.messages.push(...)` directly) are
+     * NOT observed — by design during migration, since we don't want to
+     * monkey-patch arrays. Migrating call sites to use this API is the
+     * dev-plan #1 work.
+     */
+    onChange(listener: StateChangeHandler): () => void;
+    private emit;
+}
+/**
+ * Convenience constructor — creates a ConversationState bound to the
+ * given Context. The wrapper holds a reference, not a copy.
+ */
+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[];
+}
+/**
+ * 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;
+}
+
+type Permission = 'auto' | 'confirm' | 'deny';
+interface JSONSchema {
+    type?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema;
+    enum?: unknown[];
+    description?: string;
+    [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;
+    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;
+    usageHint?: string;
+    inputSchema: JSONSchema;
+    permission: Permission;
+    mutating: boolean;
+    maxOutputBytes?: number;
+    timeoutMs?: number;
+    /**
+     * Hint for the TUI spinner — does NOT affect actual timeout enforcement.
+     * Use `timeoutMs` for hard limits. Leave undefined when duration varies
+     * unpredictably.
+     */
+    estimatedDurationMs?: number;
+    execute(input: I, ctx: Context, opts: {
+        signal: AbortSignal;
+    }): Promise<O>;
+    /**
+     * 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>;
+}
+interface ToolCallContext {
+    tool: Tool;
+    input: unknown;
+    callId: string;
+    ctx: Context;
+    signal: AbortSignal;
+}
+
+/**
+ * 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;
+    });
+    /**
+     * 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;
+        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 Capabilities {
+    tools: boolean;
+    parallelTools: boolean;
+    vision: boolean;
+    streaming: boolean;
+    promptCache: boolean;
+    systemPrompt: boolean;
+    jsonMode: boolean;
+    maxContext: number;
+    cacheControl: 'native' | 'auto' | 'none';
+}
+interface Request {
+    model: string;
+    system?: TextBlock[];
+    messages: Message[];
+    tools?: Tool[];
+    maxTokens: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    toolChoice?: 'auto' | 'required' | 'none' | {
+        type: 'tool';
+        name: string;
+    };
+}
+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';
+    id?: string;
+    name?: string;
+} | {
+    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: '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;
+    /** Human-readable explanation from the provider. */
+    message?: string;
+    /** Provider request id, when present in the body or headers. */
+    requestId?: string;
+    /** Parsed Retry-After header (or equivalent body hint) in milliseconds. */
+    retryAfterMs?: number;
+    /** The raw response body (truncated), kept for debugging. */
+    raw?: string;
+}
+declare class ProviderError extends WrongStackError {
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly providerId: string;
+    readonly body?: ProviderErrorBody;
+    constructor(message: string, status: number, retryable: boolean, providerId: string, opts?: {
+        body?: ProviderErrorBody;
+        cause?: unknown;
+    });
+    /**
+     * 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;
+}
+
+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 };