noumen 0.1.0 → 0.2.0

package/dist/agent-BrkbZyOT.d.ts

@@ -0,0 +1,1028 @@
+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-3c88cRKH.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-CwKKucOF.js';
+import { C as CacheControlConfig } from './cache-DVqaCX8v.js';
+import { M as McpServerConfig, T as TokenStorage } from './types-2kTLUCnD.js';
+import { c as PermissionHandler, d as PermissionConfig } from './types-DwdzmXfs.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>;
+}
+
+/**
+ * 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;
+}
+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 the sprite container. */
+    spriteName: string;
+    /** Base URL for sprites API (default: https://api.sprites.dev). */
+    baseURL?: string;
+    /** Working directory inside the sprite (default: /home/sprite). */
+    workingDir?: string;
+}
+/**
+ * Create a `Sandbox` backed by a remote sprites.dev container.
+ * Full isolation — the agent has no access to the host machine.
+ */
+declare function SpritesSandbox(opts: SpritesSandboxOptions): Sandbox;
+interface DockerSandboxOptions {
+    /** A dockerode Container instance for the target container. */
+    container: DockerContainer;
+    /** 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.
+ */
+declare function DockerSandbox(opts: DockerSandboxOptions): Sandbox;
+interface E2BSandboxOptions {
+    /** An E2B Sandbox instance created via `Sandbox.create()`. */
+    sandbox: E2BSandboxInstance;
+    /** 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.
+ */
+declare function E2BSandbox(opts: E2BSandboxOptions): 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;
+    constructor(fs: VirtualFs, sessionDir: string);
+    private getTranscriptPath;
+    ensureDir(): Promise<void>;
+    appendEntry(sessionId: string, entry: 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>;
+    loadMessages(sessionId: string): Promise<ChatMessage[]>;
+    loadAllEntries(sessionId: string): Promise<Entry[]>;
+    sessionExists(sessionId: string): Promise<boolean>;
+    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): 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.
+ */
+declare function shouldAutoCompact(messages: ChatMessage[], config: AutoCompactConfig, lastUsage?: ChatCompletionUsage, anchorMessageIndex?: number, tokensFreed?: number): 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;
+    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";
+}
+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 resumeRequested;
+    private fileStateCache;
+    private contentReplacementState;
+    private denialTracker;
+    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;
+    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 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;
+    constructor(opts: AgentOptions);
+    private ensureProvider;
+    private getProvider;
+    private getSkills;
+    private getAllTools;
+    private createSpawnSubagent;
+    createThread(opts?: ThreadOptions): 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">): 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>;
+    /**
+     * 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>;
+    /**
+     * Disconnect all MCP clients. Call when done with this Agent instance.
+     */
+    close(): Promise<void>;
+}
+
+export { type SandboxedLocalComputerOptions as $, Agent as A, type BudgetState as B, type ContextFile as C, type DockerContainer as D, type E2BSandboxInstance as E, E2BComputer as F, type E2BComputerOptions as G, E2BSandbox as H, type E2BSandboxOptions as I, type LocalSandboxOptions as J, type MicrocompactResult as K, LocalSandbox as L, type MicrocompactConfig as M, type ProviderName as N, type ReactiveCompactConfig as O, type ProjectContextConfig as P, type ReactiveCompactResult as Q, type RetryConfig as R, type Sandbox as S, type ThreadConfig as T, type ResolveProviderOptions as U, type RetryEvent as V, type RunCallbacks as W, type RunResult as X, SUPPORTED_PROVIDERS as Y, type SandboxConfig as Z, SandboxedLocalComputer as _, type SkillDefinition as a, type SnipConfig as a0, type SnipResult as a1, SpritesSandbox as a2, type SpritesSandboxOptions as a3, Thread as a4, type ThreadOptions as a5, type ToolResultBudgetConfig as a6, type ToolResultBudgetResult as a7, type ContentReplacementRecord as a8, type ToolResultSpillResult as a9, tryReactiveCompact as aA, webSearchToolPlaceholder as aB, type ToolResultStorageConfig as aa, type TracingConfig as ab, UnsandboxedLocal as ac, type UnsandboxedLocalOptions as ad, type WebSearchConfig as ae, type WebSearchResult as af, applyPersistedReplacements as ag, applySnipRemovals as ah, canAutoCompact as ai, createAutoCompactConfig as aj, createAutoCompactTracking as ak, createBudgetState as al, createContentReplacementState as am, createWebSearchTool as an, detectProvider as ao, enforceToolResultBudget as ap, enforceToolResultStorageBudget as aq, microcompactMessages as ar, persistToolResult as as, projectSnippedView as at, reconstructContentReplacementState as au, recordAutoCompactFailure as av, recordAutoCompactSuccess as aw, resolveProvider as ax, shouldAutoCompact as ay, snipMessagesByUuids 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 };