noumen 0.1.0 → 0.3.0

package/dist/agent-1nFVUP9E.d.ts

@@ -0,0 +1,1332 @@
+import { A as AIProvider, S as StreamEvent, b as ChatMessage, E as Entry, U as UUID, d as FileCheckpointSnapshot, f as ContentReplacementRecord$1, g as SessionInfo, M as ModelPricing, h as UsageRecord, i as CostSummary, j as ModelUsageSummary, k as ChatCompletionUsage, l as ThinkingConfig, m as MemoryConfig, O as OutputFormat, e as ContentPart, R as RunOptions, c as CheckpointConfig, n as ToolResult } from './types-LrU4LRmX.js';
+import { j as VirtualComputer, E as ExecOptions, C as CommandResult, V as VirtualFs, T as Tool, H as HookDefinition, S as SubagentConfig, k as SubagentRun, l as TaskStore, e as LspServerManager, m as FileCheckpointManager, n as FileStateCacheConfig, L as LspServerConfig } from './types-RPKUTu1k.js';
+import { C as CacheControlConfig } from './cache-DsRqxx6v.js';
+import { M as McpServerConfig, T as TokenStorage } from './types-2kTLUCnD.js';
+import { c as PermissionHandler, d as PermissionConfig } from './types-CD0rUKKT.js';
+
+type ProviderName = "openai" | "anthropic" | "gemini" | "openrouter" | "bedrock" | "vertex" | "ollama";
+declare const DEFAULT_MODELS: Record<string, string>;
+declare const SUPPORTED_PROVIDERS: ProviderName[];
+interface ResolveProviderOptions {
+    apiKey?: string;
+    model?: string;
+    baseURL?: string;
+}
+/**
+ * Resolve a provider from a name string or pass through an AIProvider instance.
+ * API key resolution order:
+ * 1. Explicit apiKey option
+ * 2. Provider-specific env var (OPENAI_API_KEY, etc.)
+ * 3. NOUMEN_API_KEY generic env var
+ */
+declare function resolveProvider(input: AIProvider | ProviderName, opts?: ResolveProviderOptions): Promise<AIProvider>;
+/**
+ * Auto-detect provider from available environment variables.
+ */
+declare function detectProvider(): Promise<ProviderName | undefined>;
+
+/**
+ * Filesystem and network restriction config passed to `@anthropic-ai/sandbox-runtime`.
+ */
+interface SandboxConfig {
+    filesystem?: {
+        /** Paths the agent may write to (default: `[cwd]`). Write is denied everywhere else. */
+        allowWrite?: string[];
+        /** Paths to explicitly deny writes within allowed regions. */
+        denyWrite?: string[];
+        /** Paths to deny reading. By default everything is readable. */
+        denyRead?: string[];
+        /** Paths to re-allow reading within denyRead regions. Takes precedence over denyRead. */
+        allowRead?: string[];
+    };
+    network?: {
+        /** Domains the agent may reach via HTTP/HTTPS/SOCKS. */
+        allowedDomains?: string[];
+        /** Domains to explicitly block. */
+        deniedDomains?: string[];
+    };
+}
+interface SandboxedLocalComputerOptions {
+    defaultCwd?: string;
+    defaultTimeout?: number;
+    sandbox?: SandboxConfig;
+}
+/**
+ * `VirtualComputer` that wraps every command with OS-level sandboxing via
+ * `@anthropic-ai/sandbox-runtime`. Uses macOS Seatbelt (`sandbox-exec`) or
+ * Linux bubblewrap (`bwrap`) under the hood.
+ */
+declare class SandboxedLocalComputer implements VirtualComputer {
+    private defaultCwd;
+    private defaultTimeout;
+    private sandboxConfig;
+    private initPromise;
+    private initialized;
+    constructor(opts?: SandboxedLocalComputerOptions);
+    private buildRuntimeConfig;
+    private ensureInitialized;
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+    /**
+     * Tear down the sandbox runtime. Call when the agent is done.
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Minimal subset of the dockerode Container interface used by DockerComputer.
+ * Avoids a hard import of dockerode at the module level.
+ */
+interface DockerContainer {
+    exec(options: Record<string, unknown>): Promise<{
+        start(opts?: Record<string, unknown>): Promise<NodeJS.ReadableStream>;
+        inspect(): Promise<{
+            ExitCode: number;
+        }>;
+    }>;
+}
+interface DockerComputerOptions {
+    /** A dockerode Container instance for the target container. */
+    container: DockerContainer;
+    /** Default working directory for commands (default: /). */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution inside a Docker container.
+ *
+ * Requires `dockerode` as an optional peer dependency.
+ * The user is responsible for container lifecycle (create, start, stop).
+ */
+declare class DockerComputer implements VirtualComputer {
+    private container;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: DockerComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+/**
+ * Minimal subset of the E2B Sandbox interface used by E2BComputer and E2BFs.
+ * Avoids a hard import of `e2b` at the module level.
+ */
+interface E2BSandboxInstance {
+    commands: {
+        run(cmd: string, opts?: {
+            cwd?: string;
+            timeout?: number;
+            envs?: Record<string, string>;
+        }): Promise<{
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+        }>;
+    };
+    files: {
+        read(path: string, opts?: {
+            format?: string;
+        }): Promise<string>;
+        write(path: string, data: string): Promise<unknown>;
+        remove(path: string): Promise<void>;
+        makeDir(path: string): Promise<unknown>;
+        list(path: string): Promise<Array<{
+            name: string;
+            path: string;
+            type?: string;
+            size?: number;
+            modifiedTime?: Date;
+        }>>;
+        exists(path: string): Promise<boolean>;
+        getInfo(path: string): Promise<{
+            name: string;
+            path: string;
+            type?: string;
+            size?: number;
+            modifiedTime?: Date;
+        }>;
+    };
+}
+interface E2BComputerOptions {
+    /** An E2B Sandbox instance created via `Sandbox.create()`. */
+    sandbox: E2BSandboxInstance;
+    /** Default working directory for commands. */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution in an E2B cloud sandbox.
+ *
+ * Requires `e2b` as an optional peer dependency.
+ * The user is responsible for sandbox lifecycle (create, close).
+ */
+declare class E2BComputer implements VirtualComputer {
+    private sandbox;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: E2BComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+/**
+ * Minimal subset of the Freestyle VM interface used by FreestyleComputer and
+ * FreestyleFs. Avoids a hard import of `freestyle-sandboxes` at the module
+ * level — the real SDK is only loaded dynamically during `FreestyleSandbox`
+ * auto-creation.
+ */
+interface FreestyleVmInstance {
+    exec(command: string, opts?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string | null;
+        stderr: string | null;
+        statusCode: number | null;
+    }>;
+    fs: {
+        readTextFile(path: string): Promise<string>;
+        writeTextFile(path: string, content: string): Promise<void>;
+        readDir(path: string): Promise<Array<{
+            name: string;
+            kind: string;
+        }>>;
+    };
+    suspend(): Promise<unknown>;
+    start(): Promise<unknown>;
+}
+interface FreestyleComputerOptions {
+    /** A Freestyle VM instance. */
+    vm: FreestyleVmInstance;
+    /** Default working directory for commands. */
+    defaultCwd?: string;
+    /** Default timeout in ms for commands (default: 30000). */
+    defaultTimeout?: number;
+}
+/**
+ * VirtualComputer backed by command execution in a Freestyle VM.
+ *
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ * The user is responsible for VM lifecycle when using explicit mode.
+ */
+declare class FreestyleComputer implements VirtualComputer {
+    private vm;
+    private defaultCwd;
+    private defaultTimeout;
+    constructor(opts: FreestyleComputerOptions);
+    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
+}
+
+/**
+ * Bundled sandbox: a `VirtualFs` and `VirtualComputer` paired together.
+ *
+ * Use one of the built-in factories (`LocalSandbox`, `UnsandboxedLocal`,
+ * `SpritesSandbox`) or supply any object that satisfies this shape for
+ * custom sandboxes (Docker, E2B, Daytona, in-memory, etc.).
+ */
+interface Sandbox {
+    fs: VirtualFs;
+    computer: VirtualComputer;
+    /** Optional cleanup — called by Agent.close() to tear down OS-level sandbox state. */
+    dispose?(): Promise<void>;
+    /**
+     * Lazily provision the underlying sandbox resource. Idempotent — repeated
+     * calls return the same single-flight promise.
+     *
+     * When `sandboxId` is provided the sandbox reconnects to an existing
+     * resource instead of creating a new one. This is used during session
+     * resume: the stored sandbox identifier is read from session metadata
+     * and passed here so the agent reattaches to its previous container.
+     *
+     * When omitted a fresh resource is provisioned (for factories that
+     * support auto-creation) or the call is a no-op (for factories that
+     * were given a pre-created resource up front).
+     */
+    init?(sandboxId?: string): Promise<void>;
+    /**
+     * Return the opaque identifier for this sandbox instance so it can be
+     * persisted in session metadata and used to reconnect later via `init()`.
+     * Returns `undefined` before `init()` has resolved or for sandboxes
+     * that don't support reconnection.
+     */
+    sandboxId?(): string | undefined;
+}
+interface UnsandboxedLocalOptions {
+    /** Working directory for both file resolution and command execution. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+}
+/**
+ * Create a `Sandbox` backed by the host filesystem and shell with **no
+ * OS-level isolation**. The agent can access anything the host process can.
+ *
+ * Use this for development or fully-trusted environments where sandboxing
+ * overhead is unwanted. For production use, prefer `LocalSandbox()` (which
+ * wraps commands with `@anthropic-ai/sandbox-runtime`).
+ */
+declare function UnsandboxedLocal(opts?: UnsandboxedLocalOptions): Sandbox;
+interface LocalSandboxOptions {
+    /** Working directory for both file resolution and command execution. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+    /**
+     * Sandbox restrictions. Defaults: writes allowed only in `cwd`,
+     * reads allowed everywhere, network unrestricted.
+     */
+    sandbox?: SandboxConfig;
+}
+/**
+ * Create a `Sandbox` with OS-level isolation via `@anthropic-ai/sandbox-runtime`.
+ *
+ * - **macOS**: Seatbelt (`sandbox-exec`) profiles restrict filesystem and network.
+ * - **Linux**: bubblewrap (`bwrap`) + socat for namespace-based isolation.
+ *
+ * Filesystem operations (`VirtualFs`) use the host `node:fs` — the sandbox
+ * boundary is enforced on shell commands (`VirtualComputer`), which is where
+ * the agent executes arbitrary code.
+ *
+ * Requires `@anthropic-ai/sandbox-runtime` as a peer dependency.
+ */
+declare function LocalSandbox(opts?: LocalSandboxOptions): Sandbox;
+interface SpritesSandboxOptions {
+    /** sprites.dev API token. */
+    token: string;
+    /**
+     * Name of an existing sprite container. When provided the sandbox
+     * attaches to this sprite directly — no auto-creation occurs and
+     * `dispose()` will **not** delete it (lifecycle is yours to manage).
+     *
+     * When omitted a new sprite is provisioned on the first `init()` call
+     * (via `POST /v1/sprites`). The auto-created sprite is deleted when
+     * `dispose()` is called, and its name is available via `sandboxId()`
+     * for session persistence.
+     */
+    spriteName?: string;
+    /** Base URL for sprites API (default: https://api.sprites.dev). */
+    baseURL?: string;
+    /** Working directory inside the sprite (default: /home/sprite). */
+    workingDir?: string;
+    /**
+     * Optional prefix for auto-generated sprite names (default: "noumen-").
+     * Only used when `spriteName` is omitted.
+     */
+    namePrefix?: string;
+}
+/**
+ * Create a `Sandbox` backed by a remote sprites.dev container.
+ * Full isolation — the agent has no access to the host machine.
+ *
+ * **Auto-creation:** When `spriteName` is omitted the sandbox is created
+ * lazily on the first `init()` call via the Sprites REST API. The sprite
+ * name is available through `sandboxId()` so callers can persist it in
+ * session metadata for reconnection on resume. Pass the stored name back
+ * through `init(storedId)` to reattach instead of creating a new sprite.
+ *
+ * **Explicit ID:** When `spriteName` is provided the sandbox attaches to
+ * that sprite immediately on `init()`. `dispose()` is a no-op in this
+ * case — the caller owns the sprite's lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create — sprite provisioned on first init()
+ * const sandbox = SpritesSandbox({ token: process.env.SPRITES_TOKEN! });
+ *
+ * // Explicit — attach to pre-existing sprite, no auto-lifecycle
+ * const sandbox = SpritesSandbox({
+ *   token: process.env.SPRITES_TOKEN!,
+ *   spriteName: "my-sprite",
+ * });
+ * ```
+ */
+declare function SpritesSandbox(opts: SpritesSandboxOptions): Sandbox;
+interface DockerSandboxOptions {
+    /**
+     * A pre-existing dockerode Container instance. When provided the sandbox
+     * attaches to this container directly — no auto-creation occurs and
+     * `dispose()` will **not** stop or remove it.
+     *
+     * When omitted, a new container is created from `image` on the first
+     * `init()` call via a dynamic import of `dockerode`. The auto-created
+     * container is stopped and removed when `dispose()` is called.
+     */
+    container?: DockerContainer;
+    /**
+     * Docker image to use for auto-creation (e.g. `"ubuntu:22.04"`).
+     * Required when `container` is omitted; ignored when `container` is provided.
+     */
+    image?: string;
+    /** Command to run in the auto-created container (default: `["sleep", "infinity"]`). */
+    cmd?: string[];
+    /** Environment variables for the auto-created container. */
+    env?: string[];
+    /** Extra options passed to dockerode `createContainer`. */
+    dockerOptions?: Record<string, unknown>;
+    /** Working directory inside the container. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+}
+/**
+ * Create a `Sandbox` backed by a Docker container.
+ * Requires `dockerode` as an optional peer dependency.
+ *
+ * **Auto-creation:** When `container` is omitted and `image` is provided,
+ * the container is created and started lazily on the first `init()` call.
+ * The container ID is available through `sandboxId()` for session
+ * persistence. Pass the stored ID back through `init(storedId)` to
+ * reattach to an existing container on resume.
+ *
+ * **Explicit container:** When `container` is provided, `init()` binds
+ * it immediately. `dispose()` is a no-op — the caller owns the
+ * container's lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create from image
+ * const sandbox = DockerSandbox({ image: "ubuntu:22.04", cwd: "/workspace" });
+ *
+ * // Explicit container (lifecycle managed externally)
+ * const sandbox = DockerSandbox({ container: myDockerodeContainer });
+ * ```
+ */
+declare function DockerSandbox(opts: DockerSandboxOptions): Sandbox;
+interface E2BSandboxOptions {
+    /**
+     * A pre-existing E2B Sandbox instance (e.g. from `Sandbox.create()`).
+     * When provided the sandbox attaches to this instance — no auto-creation
+     * occurs and `dispose()` will **not** kill it.
+     *
+     * When omitted, a new E2B sandbox is created on the first `init()` call
+     * via a dynamic import of the `e2b` package. The auto-created sandbox
+     * is killed when `dispose()` is called.
+     */
+    sandbox?: E2BSandboxInstance;
+    /**
+     * E2B template to use for auto-creation (default: `"base"`).
+     * Only used when `sandbox` is omitted.
+     */
+    template?: string;
+    /**
+     * E2B API key. Falls back to the `E2B_API_KEY` environment variable
+     * when omitted. Only used during auto-creation.
+     */
+    apiKey?: string;
+    /** Timeout (ms) for the auto-created E2B sandbox (default: E2B SDK default). */
+    timeoutMs?: number;
+    /** Working directory inside the sandbox. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+}
+/**
+ * Create a `Sandbox` backed by an E2B cloud sandbox.
+ * Requires `e2b` as an optional peer dependency.
+ *
+ * **Auto-creation:** When `sandbox` is omitted the E2B sandbox is
+ * provisioned lazily on the first `init()` call via the E2B SDK.
+ * The sandbox ID is available through `sandboxId()` for session
+ * persistence. Pass the stored ID back through `init(storedId)` to
+ * reconnect to the same sandbox on resume (via `Sandbox.connect()`).
+ *
+ * **Explicit instance:** When `sandbox` is provided, `init()` binds
+ * it immediately. `dispose()` is a no-op — the caller owns the
+ * sandbox's lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create — sandbox provisioned on first init()
+ * const sandbox = E2BSandbox({ template: "base" });
+ *
+ * // Explicit — attach to pre-existing instance
+ * const sandbox = E2BSandbox({ sandbox: await E2BSdk.Sandbox.create() });
+ * ```
+ */
+declare function E2BSandbox(opts: E2BSandboxOptions): Sandbox;
+interface FreestyleSandboxOptions {
+    /**
+     * A pre-existing Freestyle VM instance. When provided the sandbox
+     * attaches to this VM directly — no auto-creation occurs and
+     * `dispose()` will **not** suspend or delete it.
+     *
+     * When omitted, a new VM is created on the first `init()` call via
+     * a dynamic import of the `freestyle-sandboxes` package.
+     */
+    vm?: FreestyleVmInstance;
+    /**
+     * Freestyle API key. Falls back to the `FREESTYLE_API_KEY` environment
+     * variable when omitted. Only used during auto-creation.
+     */
+    apiKey?: string;
+    /** Snapshot ID to create the VM from. Only used during auto-creation. */
+    snapshotId?: string;
+    /**
+     * A `VmSpec` instance or configuration object passed through to
+     * `freestyle.vms.create()`. Only used during auto-creation.
+     */
+    spec?: unknown;
+    /**
+     * Idle timeout in seconds for the auto-created VM (default: 600).
+     * The VM auto-suspends after this many seconds of network inactivity.
+     */
+    idleTimeoutSeconds?: number;
+    /** Working directory inside the VM. */
+    cwd?: string;
+    /** Default timeout (ms) for shell commands. */
+    defaultTimeout?: number;
+    /** Files to provision at creation time. */
+    additionalFiles?: Record<string, {
+        content: string;
+        encoding?: string;
+    }>;
+    /** Git repos to clone at creation time. */
+    gitRepos?: Array<{
+        repo: string;
+        path: string;
+        rev?: string;
+    }>;
+    /**
+     * What to do with auto-created VMs on `dispose()`:
+     * - `"suspend"` (default) — suspends the VM, preserving full memory
+     *   state for near-instant resume on reconnect.
+     * - `"delete"` — permanently deletes the VM and frees all resources.
+     */
+    disposeStrategy?: "suspend" | "delete";
+}
+/**
+ * Create a `Sandbox` backed by a Freestyle VM.
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ *
+ * **Auto-creation:** When `vm` is omitted a new Freestyle VM is
+ * provisioned lazily on the first `init()` call. The VM ID is available
+ * through `sandboxId()` for session persistence. Pass the stored ID back
+ * through `init(storedId)` to reconnect (this also wakes suspended VMs).
+ *
+ * By default, auto-created VMs are **suspended** on `dispose()` rather
+ * than deleted. This preserves full memory state and allows near-instant
+ * resume. Set `disposeStrategy: "delete"` for full cleanup.
+ *
+ * **Explicit instance:** When `vm` is provided, `init()` binds it
+ * immediately. `dispose()` is a no-op — the caller owns the VM's
+ * lifecycle.
+ *
+ * @example
+ * ```ts
+ * // Auto-create — VM provisioned on first init()
+ * const sandbox = FreestyleSandbox({ cwd: "/workspace" });
+ *
+ * // Auto-create from a snapshot
+ * const sandbox = FreestyleSandbox({
+ *   snapshotId: "abc123",
+ *   cwd: "/workspace",
+ * });
+ *
+ * // Explicit — attach to pre-existing VM
+ * const sandbox = FreestyleSandbox({ vm: existingVm });
+ * ```
+ */
+declare function FreestyleSandbox(opts: FreestyleSandboxOptions): Sandbox;
+
+interface SkillDefinition {
+    name: string;
+    /** Skill body content (after frontmatter is stripped) */
+    content: string;
+    path?: string;
+    description?: string;
+    /** Glob patterns for files this skill applies to (from frontmatter `paths`) */
+    globs?: string[];
+    /** Tool names this skill is allowed to use */
+    allowedTools?: string[];
+    /** Execution context: inline expands into conversation, fork runs as sub-agent */
+    context?: "inline" | "fork";
+    /** Hint for the $ARGUMENTS placeholder */
+    argumentHint?: string;
+}
+
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+interface WebSearchConfig {
+    search: (query: string, domains?: string[]) => Promise<WebSearchResult[]>;
+}
+/**
+ * Create a WebSearch tool backed by a user-provided search implementation.
+ * This keeps noumen provider-agnostic — plug in Tavily, SerpAPI, Brave Search, etc.
+ *
+ * @example
+ * ```ts
+ * const webSearch = createWebSearchTool({
+ *   search: async (query) => {
+ *     const res = await tavily.search({ query });
+ *     return res.results.map(r => ({ title: r.title, url: r.url, snippet: r.content }));
+ *   },
+ * });
+ * ```
+ */
+declare function createWebSearchTool(config: WebSearchConfig): Tool;
+/**
+ * Default WebSearch tool that returns a helpful error when no search provider
+ * is configured. Register this as a placeholder; consumers should replace
+ * it with `createWebSearchTool(config)`.
+ */
+declare const webSearchToolPlaceholder: Tool;
+
+interface RetryConfig {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    retryableStatuses?: number[];
+    fallbackModel?: string;
+    /** Max consecutive overloaded (529) errors before triggering model fallback. */
+    maxConsecutiveOverloaded?: number;
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+interface RetryEngineOptions extends RetryConfig {
+    model: string;
+    thinkingBudget?: number;
+    signal?: AbortSignal;
+}
+interface RetryContext {
+    attempt: number;
+    model: string;
+    maxTokensOverride?: number;
+}
+type RetryEvent = Extract<StreamEvent, {
+    type: "retry_attempt" | "retry_exhausted";
+}>;
+
+declare const SpanStatusCode: {
+    readonly OK: 0;
+    readonly ERROR: 1;
+};
+type SpanStatusCode = (typeof SpanStatusCode)[keyof typeof SpanStatusCode];
+type SpanAttributeValue = string | number | boolean;
+interface SpanOptions {
+    parent?: Span;
+    attributes?: Record<string, SpanAttributeValue>;
+}
+interface Span {
+    readonly name: string;
+    setAttribute(key: string, value: SpanAttributeValue): void;
+    addEvent(name: string, attributes?: Record<string, SpanAttributeValue>): void;
+    setStatus(code: SpanStatusCode, message?: string): void;
+    end(): void;
+}
+interface Tracer {
+    startSpan(name: string, options?: SpanOptions): Span;
+}
+interface TracingConfig {
+    tracer: Tracer;
+}
+
+interface MicrocompactConfig {
+    enabled: boolean;
+    /** Keep the N most recent compactable tool results uncleared. Default: 5 */
+    keepRecent?: number;
+}
+interface MicrocompactResult {
+    messages: ChatMessage[];
+    tokensFreed: number;
+}
+/**
+ * Tools whose results can be safely cleared to free context tokens.
+ * Includes read-heavy tools (ReadFile, Grep, Glob, WebFetch, WebSearch,
+ * Bash) as well as mutation tools (EditFile, WriteFile) whose results
+ * are short confirmation strings the model can reconstruct from context.
+ */
+declare const COMPACTABLE_TOOLS: Set<string>;
+declare const CLEARED_PLACEHOLDER = "[tool result cleared to save context]";
+/**
+ * Clear the content of old tool-result messages to free context tokens
+ * without a full summarization pass.
+ *
+ * Only results from {@link COMPACTABLE_TOOLS} are eligible. The most
+ * recent `keepRecent` eligible results are preserved; older ones have
+ * their content replaced with {@link CLEARED_PLACEHOLDER}.
+ *
+ * Returns a **new** messages array (shallow-copied where unchanged).
+ */
+declare function microcompactMessages(messages: ChatMessage[], config: MicrocompactConfig): MicrocompactResult;
+
+interface ToolResultBudgetConfig {
+    enabled: boolean;
+    /** Max total chars across all tool results in one group. Default: 200_000 */
+    maxCharsPerGroup?: number;
+    /** Max chars for a single tool result before individual truncation. Default: 50_000 */
+    maxCharsPerResult?: number;
+    /** Number of preview chars to keep when truncating. Default: 1_000 */
+    previewChars?: number;
+}
+/**
+ * Tracks which tool_call_ids have already been truncated so that
+ * decisions are deterministic across repeated calls and session resume.
+ */
+interface BudgetState {
+    truncatedIds: Set<string>;
+}
+declare function createBudgetState(): BudgetState;
+interface ToolResultBudgetResult {
+    messages: ChatMessage[];
+    state: BudgetState;
+    tokensFreed: number;
+    truncatedEntries: Array<{
+        toolCallId: string;
+        originalChars: number;
+        truncatedChars: number;
+    }>;
+}
+/**
+ * Enforce per-group and per-result character budgets on tool results.
+ *
+ * For each assistant-round group: first enforce per-result caps (truncate
+ * any single result exceeding `maxCharsPerResult`), then if the group
+ * total still exceeds `maxCharsPerGroup`, truncate the largest results
+ * first until under budget.
+ *
+ * Tool results that were already truncated (tracked in `state`) are
+ * left as-is for deterministic resume.
+ */
+declare function enforceToolResultBudget(messages: ChatMessage[], config: ToolResultBudgetConfig, state?: BudgetState): ToolResultBudgetResult;
+
+declare class SessionStorage {
+    private fs;
+    private sessionDir;
+    private writeLock;
+    constructor(fs: VirtualFs, sessionDir: string);
+    /**
+     * Serialize writes through a simple promise chain so parallel
+     * appendEntry calls don't interleave large JSONL records.
+     */
+    private serializedWrite;
+    private getTranscriptPath;
+    ensureDir(): Promise<void>;
+    appendEntry(sessionId: string, entry: Entry): Promise<void>;
+    /**
+     * Append multiple entries atomically as a single write.
+     * All entries are serialized into one string and written in one appendFile
+     * call, preventing partial writes on crash.
+     */
+    appendEntriesBatch(sessionId: string, entries: Entry[]): Promise<void>;
+    appendMessage(sessionId: string, message: ChatMessage, parentUuid?: UUID | null): Promise<UUID>;
+    appendCompactBoundary(sessionId: string): Promise<UUID>;
+    appendSummary(sessionId: string, summaryMessage: ChatMessage, parentUuid?: UUID | null): Promise<UUID>;
+    appendToolResultOverflow(sessionId: string, toolCallId: string, originalContent: string): Promise<void>;
+    appendCheckpointEntry(sessionId: string, messageId: string, snapshot: FileCheckpointSnapshot, isSnapshotUpdate: boolean): Promise<void>;
+    appendSnipBoundary(sessionId: string, removedUuids: string[]): Promise<void>;
+    appendContentReplacement(sessionId: string, replacements: ContentReplacementRecord$1[]): Promise<void>;
+    appendMetadata(sessionId: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Re-append custom-title and key metadata entries after a compact boundary
+     * so they remain discoverable in the active-entries window.
+     */
+    reAppendMetadataAfterCompact(sessionId: string): Promise<void>;
+    loadMessages(sessionId: string): Promise<ChatMessage[]>;
+    loadAllEntries(sessionId: string): Promise<Entry[]>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    deleteSession(sessionId: string): Promise<void>;
+    listSessions(): Promise<SessionInfo[]>;
+}
+
+interface ReactiveCompactConfig {
+    enabled: boolean;
+}
+interface ReactiveCompactResult {
+    messages: ChatMessage[];
+    strategy: "compacted" | "truncated";
+}
+/**
+ * Attempt to recover from a context-overflow error by compacting the
+ * conversation. If compaction itself fails (e.g. the context is so large
+ * that even the summarizer cannot run), falls back to
+ * {@link truncateHeadForPTLRetry} which drops the oldest turn groups
+ * until the estimate fits within the target.
+ *
+ * Returns `null` if there are not enough messages to meaningfully compact
+ * or truncate (less than 2 messages).
+ */
+declare function tryReactiveCompact(provider: AIProvider, model: string, messages: ChatMessage[], storage: SessionStorage, sessionId: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<ReactiveCompactResult | null>;
+
+/**
+ * Disk-backed tool result storage.
+ *
+ * When a tool result exceeds a size threshold, the full content is persisted
+ * to VirtualFs and replaced in-memory with a compact stub containing a
+ * preview and path. This prevents context window bloat while preserving
+ * the full data for resume.
+ */
+
+interface ToolResultStorageConfig {
+    enabled: boolean;
+    /** Directory under which persisted results are stored. Default: ".noumen/tool-results" */
+    storageDir?: string;
+    /** Char threshold for a single result before spilling to disk. Default: 50_000 */
+    defaultThreshold?: number;
+    /** Per-tool overrides (tool name -> threshold). Use Infinity to never persist. */
+    perToolThresholds?: Record<string, number>;
+    /** Chars to keep as preview in the replacement stub. Default: 2_000 */
+    previewChars?: number;
+    /** Per-message aggregate budget for all tool results. Default: 200_000 */
+    perMessageBudget?: number;
+}
+/**
+ * Tracks which tool results have been replaced, enabling deterministic
+ * resume — previously replaced results are re-applied from the stored
+ * replacement string without re-reading from disk.
+ */
+interface ContentReplacementState {
+    seenIds: Set<string>;
+    replacements: Map<string, string>;
+}
+interface ContentReplacementRecord {
+    toolUseId: string;
+    replacement: string;
+}
+declare function createContentReplacementState(): ContentReplacementState;
+/**
+ * Persist a single oversized tool result to disk and return a replacement stub.
+ * Returns null if the content is below threshold.
+ */
+declare function persistToolResult(fs: VirtualFs, sessionId: string, toolUseId: string, toolName: string, content: string, config: ToolResultStorageConfig): Promise<string | null>;
+interface ToolResultSpillResult {
+    messages: ChatMessage[];
+    state: ContentReplacementState;
+    tokensFreed: number;
+    spilledEntries: ContentReplacementRecord[];
+}
+/**
+ * Enforce per-message tool result budget by spilling the largest results to disk.
+ *
+ * For each assistant turn group, if the total tool result size exceeds
+ * `perMessageBudget`, the largest results are spilled first.
+ */
+declare function enforceToolResultStorageBudget(messages: ChatMessage[], config: ToolResultStorageConfig, fs: VirtualFs, sessionId: string, state?: ContentReplacementState): Promise<ToolResultSpillResult>;
+/**
+ * Reconstruct ContentReplacementState from persisted records (used during session resume).
+ */
+declare function reconstructContentReplacementState(records: ContentReplacementRecord[], messages?: ChatMessage[]): ContentReplacementState;
+/**
+ * Re-apply persisted replacements to loaded messages (for resume).
+ */
+declare function applyPersistedReplacements(messages: ChatMessage[], state: ContentReplacementState): ChatMessage[];
+
+/**
+ * History snip: remove middle ranges of conversation history.
+ *
+ * Unlike prefix compaction (which summarizes and removes the oldest
+ * messages), history snip removes specific message ranges from the middle
+ * of the conversation. The JSONL transcript stays append-only — snipped
+ * messages remain on disk but their UUIDs are recorded on a snip-boundary
+ * entry so they're filtered out on resume.
+ *
+ * Parent pointers are relinked across gaps using path compression so the
+ * conversation chain stays intact.
+ */
+
+interface SnipConfig {
+    enabled: boolean;
+}
+interface SnipResult {
+    messages: ChatMessage[];
+    removedCount: number;
+    relinkedCount: number;
+}
+/**
+ * Apply snip removals to a UUID-keyed message map.
+ *
+ * Ported from claude-code's `applySnipRemovals`. Walks entries looking
+ * for snip-boundary entries with `snipMetadata.removedUuids`, deletes
+ * those messages, and relinks parentUuid across gaps with path compression.
+ */
+declare function applySnipRemovals(entries: Entry[]): {
+    messages: ChatMessage[];
+    removedCount: number;
+    relinkedCount: number;
+};
+/**
+ * Snip specific messages from an in-memory message array by UUID.
+ *
+ * This is the in-memory operation — call this during a live thread to
+ * remove messages before the next model call. The caller is responsible
+ * for persisting a snip-boundary entry to the JSONL transcript.
+ */
+declare function snipMessagesByUuids(entries: Array<{
+    uuid: UUID;
+    parentUuid: UUID | null;
+    message: ChatMessage;
+}>, removedUuids: Set<UUID>): SnipResult;
+/**
+ * Project a "snipped view" of messages for the model.
+ *
+ * Filters out messages marked as snipped. Use the `includeSnipped` option
+ * to get the full scrollback for UI display.
+ */
+declare function projectSnippedView(messages: ChatMessage[], snippedIndices: Set<number>, opts?: {
+    includeSnipped?: boolean;
+}): ChatMessage[];
+
+type ContextScope = "managed" | "user" | "project" | "local";
+interface ContextFile {
+    path: string;
+    scope: ContextScope;
+    content: string;
+    /** Glob patterns from frontmatter `paths:` field. Undefined = unconditional. */
+    globs?: string[];
+    /** Files included via @ references. */
+    includes?: ContextFile[];
+}
+interface ProjectContextConfig {
+    /** Working directory (project root). Required. */
+    cwd: string;
+    /** User home directory. Pass explicitly for sandboxed environments. */
+    homeDir?: string;
+    /** Managed settings directory (enterprise/MDM). Optional. */
+    managedDir?: string;
+    /** Glob patterns to exclude context files (picomatch-style). */
+    excludes?: string[];
+    /** Maximum include depth for @ references. Default: 5. */
+    maxIncludeDepth?: number;
+    /** Whether to load .claude/ files in addition to .noumen/ files. Default: true. */
+    loadClaudeMd?: boolean;
+    /** Enable loading user-scope context from homeDir. Default: true. */
+    loadUserContext?: boolean;
+    /** Enable loading project-scope context from cwd ancestors. Default: true. */
+    loadProjectContext?: boolean;
+    /** Enable loading local-scope (.local.md) context. Default: true. */
+    loadLocalContext?: boolean;
+}
+
+interface StoredCostState {
+    byModel: Record<string, ModelUsageSummary>;
+    totalApiMs: number;
+    wallStartMs: number;
+}
+declare class CostTracker {
+    private pricing;
+    private byModel;
+    private totalApiMs;
+    private wallStartMs;
+    constructor(pricing?: Record<string, ModelPricing>);
+    addUsage(model: string, usage: UsageRecord, apiDurationMs?: number): CostSummary;
+    getSummary(): CostSummary;
+    reset(): void;
+    getState(): StoredCostState;
+    restore(state: StoredCostState): void;
+    formatSummary(): string;
+}
+
+interface AutoCompactConfig {
+    enabled: boolean;
+    /** Token threshold at which to trigger compaction. */
+    threshold: number;
+    /** Number of recent messages to keep uncompacted. */
+    tailMessagesToKeep?: number;
+}
+/**
+ * Tracks consecutive auto-compact failures to implement a circuit breaker.
+ * After `maxFailures` consecutive failures, auto-compact is skipped to
+ * avoid an infinite fail-retry loop.
+ */
+interface AutoCompactTrackingState {
+    consecutiveFailures: number;
+    maxFailures: number;
+}
+declare function createAutoCompactConfig(opts?: {
+    enabled?: boolean;
+    threshold?: number;
+    /** Model name — when provided, the threshold is computed from the model's
+     *  context window instead of the fixed default.  */
+    model?: string;
+    maxOutputTokens?: number;
+    tailMessagesToKeep?: number;
+}): AutoCompactConfig;
+declare function createAutoCompactTracking(maxFailures?: number): AutoCompactTrackingState;
+/**
+ * Determine whether auto-compaction should fire. Uses usage-grounded counting
+ * when a usage anchor is available, otherwise falls back to estimation.
+ *
+ * @param tokensFreed — tokens already reclaimed by microcompact/budget in
+ *   this turn; subtracted from the estimate so we don't over-eagerly compact.
+ * @param querySource — the source of the current query; prevents recursive
+ *   compaction when called from a compact or session_memory context.
+ */
+declare function shouldAutoCompact(messages: ChatMessage[], config: AutoCompactConfig, lastUsage?: ChatCompletionUsage, anchorMessageIndex?: number, tokensFreed?: number, querySource?: string): boolean;
+/**
+ * Check whether the circuit breaker allows another auto-compact attempt.
+ */
+declare function canAutoCompact(tracking: AutoCompactTrackingState): boolean;
+declare function recordAutoCompactSuccess(tracking: AutoCompactTrackingState): void;
+declare function recordAutoCompactFailure(tracking: AutoCompactTrackingState): void;
+
+interface ThreadOptions {
+    sessionId?: string;
+    resume?: boolean;
+    cwd?: string;
+    model?: string;
+    /** Override the permission handler for this thread (takes precedence over AgentOptions). */
+    permissionHandler?: PermissionHandler;
+    /** Override the user input handler for this thread (takes precedence over AgentOptions). */
+    userInputHandler?: (question: string) => Promise<string>;
+}
+interface ThreadConfig {
+    provider: AIProvider;
+    fs: VirtualFs;
+    computer: VirtualComputer;
+    sessionDir: string;
+    skills?: SkillDefinition[];
+    tools?: Tool[];
+    systemPrompt?: string;
+    model?: string;
+    maxTokens?: number;
+    autoCompact?: AutoCompactConfig;
+    microcompact?: MicrocompactConfig;
+    toolResultBudget?: ToolResultBudgetConfig;
+    reactiveCompact?: ReactiveCompactConfig;
+    permissions?: PermissionConfig;
+    hooks?: HookDefinition[];
+    spawnSubagent?: (config: SubagentConfig) => SubagentRun;
+    streamingToolExecution?: boolean;
+    /** Truncate individual tool results exceeding this character count. Default: 100000. */
+    maxResultChars?: number;
+    userInputHandler?: (question: string) => Promise<string>;
+    taskStore?: TaskStore;
+    lspManager?: LspServerManager;
+    thinking?: ThinkingConfig;
+    retry?: RetryConfig;
+    costTracker?: CostTracker;
+    tracer?: Tracer;
+    memory?: MemoryConfig;
+    toolSearchEnabled?: boolean;
+    checkpointManager?: FileCheckpointManager;
+    /** File state cache config for read-before-edit enforcement. */
+    fileStateCacheConfig?: FileStateCacheConfig;
+    /** Disk-backed tool result storage config. */
+    toolResultStorage?: ToolResultStorageConfig;
+    /** History snip: enable middle-range removal from conversation history. */
+    historySnip?: SnipConfig;
+    /** Enable deterministic tool ordering and CacheSafeParams tracking for prompt caching. */
+    promptCachingEnabled?: boolean;
+    /** When true, signal skipCacheWrite to the provider (for subagent forks). */
+    skipCacheWrite?: boolean;
+    /** Set of MCP tool names for cache-stable sorting (built-in first, then MCP). */
+    mcpToolNames?: ReadonlySet<string>;
+    /** Loaded project context files (NOUMEN.md / CLAUDE.md) for system prompt injection. */
+    projectContext?: ContextFile[];
+    /** Default structured output format for all runs on this thread. */
+    outputFormat?: OutputFormat;
+    /** Default structured output mode for all runs on this thread. */
+    structuredOutputMode?: "alongside_tools" | "final_response";
+    /** When true, assert normalization invariants after every API message preparation. */
+    debug?: boolean;
+}
+declare class Thread {
+    readonly sessionId: string;
+    private config;
+    private storage;
+    private toolRegistry;
+    private messages;
+    private loaded;
+    private abortController;
+    private cwd;
+    private model;
+    private activatedSkills;
+    private activatedContextRules;
+    private permissionContext;
+    private permissionHandler;
+    private hooks;
+    private lastUsage;
+    private anchorMessageIndex;
+    private prePlanMode;
+    private tracer;
+    private autoCompactTracking;
+    private budgetState;
+    private hasAttemptedReactiveCompact;
+    private microcompactTokensFreed;
+    private querySource;
+    private resumeRequested;
+    private fileStateCache;
+    private contentReplacementState;
+    private denialTracker;
+    /** Tracks file paths read by ReadFile for post-compact reinjection. */
+    private recentlyReadFiles;
+    constructor(config: ThreadConfig, opts?: ThreadOptions);
+    run(prompt: string | ContentPart[], opts?: RunOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * If tool result storage is enabled and the content exceeds the threshold,
+     * spill to disk and return the replacement stub. Otherwise return the original.
+     */
+    private maybeSpillToolResult;
+    private buildStreamingExecutorFn;
+    private buildPermissionOpts;
+    private buildCurrentSystemPromptAsync;
+    getMessages(): Promise<ChatMessage[]>;
+    compact(opts?: {
+        instructions?: string;
+    }): Promise<void>;
+    /**
+     * Remove specific messages from the middle of conversation history.
+     *
+     * Unlike `compact()` which summarizes a prefix, `snip()` removes
+     * specific messages by UUID. The JSONL transcript records the removed
+     * UUIDs so they're filtered on resume. Parent pointers are relinked
+     * across gaps.
+     *
+     * @param uuids - UUIDs of messages to remove
+     */
+    snip(uuids: string[]): Promise<void>;
+    setModel(model: string): void;
+    setProvider(provider: AIProvider, model?: string): void;
+    getModel(): string;
+    getCwd(): string;
+    abort(): void;
+}
+
+interface DiagnoseCheckResult {
+    ok: boolean;
+    latencyMs: number;
+    error?: string;
+    warning?: string;
+}
+interface DiagnoseResult {
+    overall: boolean;
+    provider: DiagnoseCheckResult & {
+        model?: string;
+    };
+    sandbox: {
+        fs: DiagnoseCheckResult;
+        computer: DiagnoseCheckResult;
+    };
+    sandboxRuntime: DiagnoseCheckResult & {
+        platform?: string;
+    };
+    mcp: Record<string, DiagnoseCheckResult & {
+        status?: string;
+        toolCount?: number;
+    }>;
+    lsp: Record<string, DiagnoseCheckResult & {
+        state?: string;
+    }>;
+    timestamp: string;
+}
+interface AgentOptions {
+    /**
+     * AI provider — either an `AIProvider` instance or a provider name string.
+     * When a string is passed (e.g. `"openai"`), the provider is resolved
+     * lazily using env-var auto-detection on the first call to `run()`,
+     * `createThread()`, or `init()`.
+     */
+    provider: AIProvider | ProviderName;
+    /**
+     * Working directory. When set without an explicit `sandbox`, an
+     * `UnsandboxedLocal({ cwd })` is created automatically.
+     */
+    cwd?: string;
+    /**
+     * Bundled sandbox providing both filesystem and shell execution.
+     * Use `LocalSandbox()` for OS-level sandboxing (requires
+     * `@anthropic-ai/sandbox-runtime`), `UnsandboxedLocal()` for raw host
+     * access, `SpritesSandbox()` for isolated remote containers, or pass
+     * any `{ fs: VirtualFs; computer: VirtualComputer }` for custom sandboxes.
+     *
+     * Defaults to `UnsandboxedLocal({ cwd })` when omitted — the library
+     * default is non-sandboxed for backward compatibility. The CLI defaults
+     * to `LocalSandbox()` when sandbox-runtime is available.
+     */
+    sandbox?: Sandbox;
+    options?: {
+        sessionDir?: string;
+        skills?: SkillDefinition[];
+        skillsPaths?: string[];
+        tools?: Tool[];
+        mcpServers?: Record<string, McpServerConfig>;
+        /** Token storage for MCP OAuth flows (defaults to in-memory). */
+        mcpTokenStorage?: TokenStorage;
+        /** Called when an MCP server requires OAuth and the user must visit a URL. */
+        mcpOnAuthorizationUrl?: (url: string) => void | Promise<void>;
+        systemPrompt?: string;
+        model?: string;
+        maxTokens?: number;
+        autoCompact?: boolean;
+        autoCompactThreshold?: number;
+        microcompact?: MicrocompactConfig;
+        toolResultBudget?: ToolResultBudgetConfig;
+        reactiveCompact?: ReactiveCompactConfig;
+        cwd?: string;
+        permissions?: PermissionConfig;
+        hooks?: HookDefinition[];
+        enableSubagents?: boolean;
+        enableTasks?: boolean;
+        tasksDir?: string;
+        enablePlanMode?: boolean;
+        enableWorktrees?: boolean;
+        lsp?: Record<string, LspServerConfig>;
+        streamingToolExecution?: boolean;
+        webSearch?: WebSearchConfig;
+        userInputHandler?: (question: string) => Promise<string>;
+        thinking?: ThinkingConfig;
+        retry?: RetryConfig | boolean;
+        costTracking?: {
+            enabled: boolean;
+            pricing?: Record<string, ModelPricing>;
+        };
+        tracing?: TracingConfig;
+        memory?: MemoryConfig;
+        /** Enable ToolSearch: deferred tools are hidden until the model discovers them. */
+        toolSearch?: boolean;
+        /** File checkpointing: snapshot files before edits for rollback. */
+        checkpoint?: CheckpointConfig;
+        /** Prompt caching: enable deterministic tool ordering and cache_control injection. */
+        promptCaching?: CacheControlConfig;
+        /** File state cache: track reads for read-before-edit enforcement. */
+        fileStateCache?: FileStateCacheConfig;
+        /** Disk-backed storage for oversized tool results. */
+        toolResultStorage?: ToolResultStorageConfig;
+        /** History snip: enable middle-range removal from conversation history. */
+        historySnip?: SnipConfig;
+        /** Project context loading (NOUMEN.md / CLAUDE.md). Pass true for defaults or a config object. */
+        projectContext?: ProjectContextConfig | boolean;
+        /** Default structured output format for all threads. */
+        outputFormat?: OutputFormat;
+        /** Default structured output mode for all threads. */
+        structuredOutputMode?: "alongside_tools" | "final_response";
+    };
+}
+interface RunCallbacks {
+    onText?: (text: string) => void;
+    onThinking?: (text: string) => void;
+    onToolUse?: (toolName: string, args: Record<string, unknown>) => void;
+    onToolResult?: (toolName: string, result: ToolResult) => void;
+    onError?: (error: Error) => void;
+    onComplete?: (result: RunResult) => void;
+}
+interface RunResult {
+    text: string;
+    toolCalls: number;
+    usage: ChatCompletionUsage;
+    sessionId: string;
+}
+declare class Agent {
+    private providerInput;
+    private resolvedProvider;
+    private fs;
+    private computer;
+    private sandbox;
+    private sessionDir;
+    private skills;
+    private skillsPaths;
+    private tools;
+    private systemPrompt?;
+    private model?;
+    private maxTokens?;
+    private autoCompactEnabled;
+    private autoCompactThreshold?;
+    private cwd;
+    private storage;
+    private resolvedSkills;
+    private mcpManager;
+    private mcpServerConfigs?;
+    private mcpTokenStorage?;
+    private mcpOnAuthorizationUrl?;
+    private mcpTools;
+    private mcpToolNames;
+    private mcpAuthTools;
+    private permissions?;
+    private hooks;
+    private enableSubagents;
+    private enableTasks;
+    private taskStore;
+    private enablePlanMode;
+    private enableWorktrees;
+    private lspManager;
+    private lspConfigs?;
+    private lspToolRef;
+    private streamingToolExecution;
+    private webSearchConfig?;
+    private userInputHandler?;
+    private thinkingConfig?;
+    private retryConfig?;
+    private costTracker;
+    private tracer?;
+    private memoryProvider?;
+    private memoryConfig?;
+    private microcompactConfig?;
+    private toolResultBudgetConfig?;
+    private reactiveCompactConfig?;
+    private toolSearchEnabled;
+    private projectContextConfig?;
+    private resolvedProjectContext;
+    private checkpointManager;
+    private promptCachingConfig;
+    private fileStateCacheConfig;
+    private toolResultStorageConfig;
+    private historySnipConfig;
+    private outputFormat;
+    private structuredOutputMode;
+    private providerPromise;
+    private initPromise;
+    constructor(opts: AgentOptions);
+    private ensureProvider;
+    private getProvider;
+    private getSkills;
+    private getAllTools;
+    private createSpawnSubagent;
+    createThread(opts?: ThreadOptions): Promise<Thread>;
+    listSessions(): Promise<SessionInfo[]>;
+    getCostSummary(): CostSummary | null;
+    /**
+     * Create a thread that resumes an existing session. Automatically restores
+     * messages (respecting compact boundaries), file checkpoint state, and
+     * cost tracking state from the persisted JSONL transcript.
+     */
+    resumeThread(sessionId: string, opts?: Omit<ThreadOptions, "sessionId" | "resume">): Promise<Thread>;
+    /**
+     * One-shot streaming: creates an ephemeral thread and yields events.
+     * Auto-resolves string providers on first call (no need to call `init()`).
+     *
+     * ```ts
+     * for await (const event of agent.run("Fix the bug")) {
+     *   if (event.type === "text_delta") process.stdout.write(event.text);
+     * }
+     * ```
+     */
+    run(prompt: string | ContentPart[], opts?: RunOptions & ThreadOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * One-shot execution: runs the prompt to completion and returns a result
+     * summary. Optional callbacks fire as events arrive.
+     *
+     * ```ts
+     * const result = await agent.execute("Fix the bug", {
+     *   onText: (text) => process.stdout.write(text),
+     * });
+     * console.log(`Done — ${result.toolCalls} tool calls`);
+     * ```
+     */
+    execute(prompt: string | ContentPart[], opts?: RunOptions & ThreadOptions & RunCallbacks): Promise<RunResult>;
+    /**
+     * Pre-resolve the provider (if string), skills, MCP servers, and LSP servers.
+     * Call this once after construction if using a string provider, skillsPaths,
+     * mcpServers, or lsp, so that createThread() has everything available synchronously.
+     */
+    init(): Promise<void>;
+    private doInit;
+    /**
+     * Run health checks on the provider, sandbox, MCP servers, and LSP servers.
+     * Returns a structured report — useful for debugging integration issues.
+     *
+     * @param timeoutMs Per-check timeout in milliseconds (default 10 000).
+     */
+    diagnose(timeoutMs?: number): Promise<DiagnoseResult>;
+    private get sandboxIndexPath();
+    private loadSandboxId;
+    private storeSandboxId;
+    /**
+     * Disconnect all MCP clients. Call when done with this Agent instance.
+     */
+    close(): Promise<void>;
+}
+
+export { type RunCallbacks as $, Agent as A, type BudgetState as B, type ContextFile as C, type DockerContainer as D, type E2BSandboxInstance as E, type FreestyleVmInstance as F, E2BComputer as G, type E2BComputerOptions as H, E2BSandbox as I, type E2BSandboxOptions as J, FreestyleComputer as K, type FreestyleComputerOptions as L, FreestyleSandbox as M, type FreestyleSandboxOptions as N, LocalSandbox as O, type ProjectContextConfig as P, type LocalSandboxOptions as Q, type RetryConfig as R, type Sandbox as S, type ThreadConfig as T, type MicrocompactConfig as U, type MicrocompactResult as V, type ProviderName as W, type ReactiveCompactConfig as X, type ReactiveCompactResult as Y, type ResolveProviderOptions as Z, type RetryEvent as _, type SkillDefinition as a, type RunResult as a0, SUPPORTED_PROVIDERS as a1, type SandboxConfig as a2, SandboxedLocalComputer as a3, type SandboxedLocalComputerOptions as a4, type SnipConfig as a5, type SnipResult as a6, SpritesSandbox as a7, type SpritesSandboxOptions as a8, Thread as a9, recordAutoCompactFailure as aA, recordAutoCompactSuccess as aB, resolveProvider as aC, shouldAutoCompact as aD, snipMessagesByUuids as aE, tryReactiveCompact as aF, webSearchToolPlaceholder as aG, type ThreadOptions as aa, type ToolResultBudgetConfig as ab, type ToolResultBudgetResult as ac, type ContentReplacementRecord as ad, type ToolResultSpillResult as ae, type ToolResultStorageConfig as af, type TracingConfig as ag, UnsandboxedLocal as ah, type UnsandboxedLocalOptions as ai, type WebSearchConfig as aj, type WebSearchResult as ak, applyPersistedReplacements as al, applySnipRemovals as am, canAutoCompact as an, createAutoCompactConfig as ao, createAutoCompactTracking as ap, createBudgetState as aq, createContentReplacementState as ar, createWebSearchTool as as, detectProvider as at, enforceToolResultBudget as au, enforceToolResultStorageBudget as av, microcompactMessages as aw, persistToolResult as ax, projectSnippedView as ay, reconstructContentReplacementState as az, SessionStorage as b, type ContextScope as c, type RetryContext as d, type RetryEngineOptions as e, type Span as f, type SpanAttributeValue as g, SpanStatusCode as h, type Tracer as i, type SpanOptions as j, type StoredCostState as k, type AgentOptions as l, type AutoCompactConfig as m, type AutoCompactTrackingState as n, CLEARED_PLACEHOLDER as o, COMPACTABLE_TOOLS as p, type ContentReplacementState as q, CostTracker as r, DEFAULT_MODELS as s, DEFAULT_RETRY_CONFIG as t, type DiagnoseCheckResult as u, type DiagnoseResult as v, DockerComputer as w, type DockerComputerOptions as x, DockerSandbox as y, type DockerSandboxOptions as z };