noumen 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,376 +1,80 @@
-type UUID = string & {
-    readonly __brand: unique symbol;
-};
-
-interface ToolCallContent {
-    id: string;
-    type: "function";
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-interface UserMessage {
-    role: "user";
-    content: string;
-}
-interface AssistantMessage {
-    role: "assistant";
-    content: string | null;
-    tool_calls?: ToolCallContent[];
-}
-interface ToolResultMessage {
-    role: "tool";
-    tool_call_id: string;
-    content: string;
-}
-interface SystemMessage {
-    role: "system";
-    content: string;
-}
-type ChatMessage = UserMessage | AssistantMessage | ToolResultMessage | SystemMessage;
-interface SerializedMessage {
-    uuid: UUID;
-    parentUuid: UUID | null;
-    sessionId: string;
-    timestamp: string;
-    message: ChatMessage;
-}
-interface MessageEntry {
-    type: "message";
-    uuid: UUID;
-    parentUuid: UUID | null;
-    sessionId: string;
-    timestamp: string;
-    message: ChatMessage;
-}
-interface CompactBoundaryEntry {
-    type: "compact-boundary";
-    uuid: UUID;
-    sessionId: string;
-    timestamp: string;
-}
-interface SummaryEntry {
-    type: "summary";
-    uuid: UUID;
-    parentUuid: UUID | null;
-    sessionId: string;
-    timestamp: string;
-    message: ChatMessage;
-}
-interface CustomTitleEntry {
-    type: "custom-title";
-    sessionId: string;
-    title: string;
-    timestamp: string;
-}
-interface MetadataEntry {
-    type: "metadata";
-    sessionId: string;
-    timestamp: string;
-    key: string;
-    value: unknown;
-}
-type Entry = MessageEntry | CompactBoundaryEntry | SummaryEntry | CustomTitleEntry | MetadataEntry;
-interface SessionInfo {
-    sessionId: string;
-    createdAt: string;
-    lastMessageAt: string;
-    title?: string;
-    messageCount: number;
-}
-interface ToolResult$1 {
-    content: string;
-    isError?: boolean;
-}
-type StreamEvent = {
-    type: "text_delta";
-    text: string;
-} | {
-    type: "tool_use_start";
-    toolName: string;
-    toolUseId: string;
-} | {
-    type: "tool_use_delta";
-    input: string;
-} | {
-    type: "tool_result";
-    toolUseId: string;
-    toolName: string;
-    result: ToolResult$1;
-} | {
-    type: "message_complete";
-    message: AssistantMessage;
-} | {
-    type: "compact_start";
-} | {
-    type: "compact_complete";
-} | {
-    type: "error";
-    error: Error;
-};
-interface RunOptions {
-    signal?: AbortSignal;
-}
-
-interface ToolParameterProperty$1 {
-    type: string;
-    description?: string;
-    enum?: string[];
-    default?: unknown;
-    minimum?: number;
-    maximum?: number;
-}
-interface ToolDefinition {
-    type: "function";
-    function: {
-        name: string;
-        description: string;
-        parameters: {
-            type: "object";
-            properties: Record<string, ToolParameterProperty$1>;
-            required?: string[];
-        };
-    };
-}
-interface ChatStreamDelta {
-    role?: "assistant";
-    content?: string | null;
-    tool_calls?: Array<{
-        index: number;
-        id?: string;
-        type?: "function";
-        function?: {
-            name?: string;
-            arguments?: string;
-        };
-    }>;
-}
-interface ChatStreamChoice {
-    index: number;
-    delta: ChatStreamDelta;
-    finish_reason: string | null;
-}
-interface ChatStreamChunk {
-    id: string;
-    choices: ChatStreamChoice[];
-    model: string;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-interface ChatCompletionUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-}
-interface ChatParams {
-    model: string;
-    messages: ChatMessage[];
-    tools?: ToolDefinition[];
-    max_tokens?: number;
-    system?: string;
-    temperature?: number;
-}
-interface AIProvider {
-    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
-}
-
-interface FileEntry {
-    name: string;
-    path: string;
-    isDirectory: boolean;
-    isFile: boolean;
-    size?: number;
-}
-interface FileStat {
-    size: number;
-    isDirectory: boolean;
-    isFile: boolean;
-    createdAt?: Date;
-    modifiedAt?: Date;
-}
-interface ReadOptions {
-    encoding?: BufferEncoding;
-}
-interface VirtualFs {
-    readFile(path: string, opts?: ReadOptions): Promise<string>;
-    writeFile(path: string, content: string): Promise<void>;
-    appendFile(path: string, content: string): Promise<void>;
-    deleteFile(path: string, opts?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    mkdir(path: string, opts?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    readdir(path: string, opts?: {
-        recursive?: boolean;
-    }): Promise<FileEntry[]>;
-    exists(path: string): Promise<boolean>;
-    stat(path: string): Promise<FileStat>;
-}
-
-interface ExecOptions {
-    timeout?: number;
-    cwd?: string;
-    env?: Record<string, string>;
-}
-interface CommandResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}
-interface VirtualComputer {
-    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
-}
-
-interface SkillDefinition {
-    name: string;
-    content: string;
-    path?: string;
-    description?: string;
-    /** Glob patterns for files this skill applies to */
-    globs?: string[];
-}
-
-interface AutoCompactConfig {
-    enabled: boolean;
-    /** Token threshold at which to trigger compaction */
-    threshold: number;
-}
-declare function createAutoCompactConfig(opts?: {
-    enabled?: boolean;
-    threshold?: number;
-}): AutoCompactConfig;
-declare function shouldAutoCompact(messages: ChatMessage[], config: AutoCompactConfig): boolean;
+import { S as Sandbox, A as Agent, D as DockerContainer, E as E2BSandboxInstance, F as FreestyleVmInstance, a as SkillDefinition, T as ThreadConfig, b as SessionStorage, C as ContextFile, P as ProjectContextConfig, c as ContextScope, R as RetryConfig, d as RetryContext, e as RetryEngineOptions, f as Span, g as SpanAttributeValue, h as SpanStatusCode, i as Tracer, j as SpanOptions, k as StoredCostState } from './agent-1nFVUP9E.js';
+export { l as AgentOptions, m as AutoCompactConfig, n as AutoCompactTrackingState, B as BudgetState, o as CLEARED_PLACEHOLDER, p as COMPACTABLE_TOOLS, q as ContentReplacementState, r as CostTracker, s as DEFAULT_MODELS, t as DEFAULT_RETRY_CONFIG, u as DiagnoseCheckResult, v as DiagnoseResult, w as DockerComputer, x as DockerComputerOptions, y as DockerSandbox, z as DockerSandboxOptions, G as E2BComputer, H as E2BComputerOptions, I as E2BSandbox, J as E2BSandboxOptions, K as FreestyleComputer, L as FreestyleComputerOptions, M as FreestyleSandbox, N as FreestyleSandboxOptions, O as LocalSandbox, Q as LocalSandboxOptions, U as MicrocompactConfig, V as MicrocompactResult, W as ProviderName, X as ReactiveCompactConfig, Y as ReactiveCompactResult, Z as ResolveProviderOptions, _ as RetryEvent, $ as RunCallbacks, a0 as RunResult, a1 as SUPPORTED_PROVIDERS, a2 as SandboxConfig, a3 as SandboxedLocalComputer, a4 as SandboxedLocalComputerOptions, a5 as SnipConfig, a6 as SnipResult, a7 as SpritesSandbox, a8 as SpritesSandboxOptions, a9 as Thread, aa as ThreadOptions, ab as ToolResultBudgetConfig, ac as ToolResultBudgetResult, ad as ToolResultReplacementRecord, ae as ToolResultSpillResult, af as ToolResultStorageConfig, ag as TracingConfig, ah as UnsandboxedLocal, ai as UnsandboxedLocalOptions, aj as WebSearchConfig, ak as WebSearchResult, al as applyPersistedReplacements, am as applySnipRemovals, an as canAutoCompact, ao as createAutoCompactConfig, ap as createAutoCompactTracking, aq as createBudgetState, ar as createContentReplacementState, as as createWebSearchTool, at as detectProvider, au as enforceToolResultBudget, av as enforceToolResultStorageBudget, aw as microcompactMessages, ax as persistToolResult, ay as projectSnippedView, az as reconstructContentReplacementState, aA as recordAutoCompactFailure, aB as recordAutoCompactSuccess, aC as resolveProvider, aD as shouldAutoCompact, aE as snipMessagesByUuids, aF as tryReactiveCompact, aG as webSearchToolPlaceholder } from './agent-1nFVUP9E.js';
+import { A as AIProvider, T as ToolDefinition, o as ToolCallContent, S as StreamEvent, e as ContentPart, b as ChatMessage, k as ChatCompletionUsage, M as ModelPricing, h as UsageRecord, a as ChatStreamChunk, p as MemoryProvider, q as MemoryEntry, l as ThinkingConfig, r as AssistantMessage, s as ToolResultMessage, d as FileCheckpointSnapshot, t as ToolResultOverflowEntry, f as ContentReplacementRecord, J as JsonSchemaOutputFormat } from './types-LrU4LRmX.js';
+export { C as ChatParams, u as ChatStreamChoice, v as ChatStreamDelta, w as ChatStreamError, c as CheckpointConfig, x as CompactBoundaryEntry, y as ContentReplacementEntry, i as CostSummary, z as CustomTitleEntry, D as DiffStats, E as Entry, B as FileCheckpointBackup, G as FileCheckpointEntry, F as FileCheckpointState, I as ImageContent, H as ImageUrlContent, K as JsonObjectOutputFormat, m as MemoryConfig, L as MemoryType, N as MessageEntry, P as MetadataEntry, j as ModelUsageSummary, O as OutputFormat, R as RunOptions, Q as SerializedMessage, g as SessionInfo, V as SnipBoundaryEntry, W as SummaryEntry, X as SystemMessage, Y as TextContent, Z as ToolDefParameterProperty, n as ToolResult, _ as UserMessage, $ as createCheckpointState } from './types-LrU4LRmX.js';
+import { H as HookDefinition, V as VirtualFs, R as ReadOptions, F as FileEntry, i as FileStat, j as VirtualComputer, E as ExecOptions, C as CommandResult, T as Tool, h as ToolContext, g as ToolResult, o as HookEvent, p as HookInput, P as PostToolUseFailureHookInput, q as PostToolUseFailureHookOutput, r as PostToolUseHookInput, s as PostToolUseHookOutput, t as PreToolUseHookInput, u as PreToolUseHookOutput } from './types-RPKUTu1k.js';
+export { m as FileCheckpointManager, v as FileState, w as FileStateCache, n as FileStateCacheConfig, x as FileWriteHookInput, y as HookOutput, J as JsonSchemaType, b as LspDiagnostic, c as LspLocation, d as LspOperation, L as LspServerConfig, a as LspServerState, f as LspSymbol, M as MemoryUpdateHookInput, z as ModelSwitchHookInput, N as NotificationHookInput, A as PermissionDeniedHookInput, B as PermissionRequestHookInput, G as RetryAttemptHookInput, I as SafeParseResult, K as SessionEndHookInput, O as SessionStartHookInput, S as SubagentConfig, k as SubagentRun, Q as SubagentStartHookInput, U as SubagentStopHookInput, W as Task, X as TaskCreateInput, Y as TaskStatus, l as TaskStore, Z as TaskUpdateInput, _ as ToolParameters, $ as ZodLikeSchema, a0 as formatZodValidationError, a1 as registerZodToJsonSchema, a2 as zodToJsonSchema } from './types-RPKUTu1k.js';
+import { M as McpServerConfig } from './types-2kTLUCnD.js';
+export { b as McpConfig, c as McpConnection, d as McpHttpServerConfig, e as McpOAuthConfig, f as McpSseServerConfig, g as McpStdioServerConfig, h as McpToolInfo, i as McpWebSocketServerConfig, a as OAuthProviderOptions, O as OAuthTokenData, T as TokenStorage } from './types-2kTLUCnD.js';
+export { OpenAIProviderOptions } from './providers/openai.js';
+export { AnthropicProviderOptions } from './providers/anthropic.js';
+export { GeminiProviderOptions } from './providers/gemini.js';
+export { OpenRouterProviderOptions } from './providers/openrouter.js';
+export { BedrockAnthropicProviderOptions } from './providers/bedrock.js';
+export { VertexAnthropicProviderOptions } from './providers/vertex.js';
+export { OllamaProviderOptions } from './providers/ollama.js';
+import { c as PermissionHandler, e as PermissionContext, f as PermissionBehavior, g as PermissionRule, A as AutoModeConfig, h as PermissionDecision, i as PermissionUpdate } from './types-CD0rUKKT.js';
+export { D as DenialTrackingConfig, j as PermissionAllowResult, k as PermissionAskResult, d as PermissionConfig, l as PermissionDenyResult, a as PermissionMode, m as PermissionPassthroughResult, n as PermissionRequest, P as PermissionResponse, b as PermissionResult, o as PermissionRuleSource, R as RULE_SOURCE_PRECEDENCE } from './types-CD0rUKKT.js';
+export { a as McpClientManagerOptions, b as McpServerOptions, c as buildMcpToolName, g as getMcpPrefix, n as normalizeNameForMCP, p as parseMcpToolName } from './server-CHMxuWKq.js';
+export { C as CacheControlConfig, a as CacheScope, g as getMessageCacheBreakpointIndex, s as sortToolDefinitionsForCache } from './cache-DsRqxx6v.js';
+export { JsonRpcErrorObject, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse } from './jsonrpc/index.js';
+export { b as AcpCapabilities, c as AcpInitializeParams, d as AcpInitializeResult, A as AcpTransport } from './types-QwfylltH.js';
+export { e as A2AArtifact, M as A2AMessage, P as A2APart, b as A2ATask, g as A2ATaskStatus, a as AgentCard, A as AgentSkill } from './types-NIyVwQ4h.js';
+export { OAuthClientInformation, OAuthClientInformationFull, OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+export { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+import '@modelcontextprotocol/sdk/client/index.js';
 
-interface ThreadOptions {
-    sessionId?: string;
-    resume?: boolean;
+interface PresetOptions {
+    /** The AI provider instance (e.g. `new OpenAIProvider({ apiKey })`) */
+    provider: AIProvider;
+    /** Working directory for the sandbox. Defaults to `process.cwd()`. */
     cwd?: string;
+    /** Model name override. Each preset has a sensible default. */
     model?: string;
-}
-interface ThreadConfig {
-    aiProvider: AIProvider;
-    fs: VirtualFs;
-    computer: VirtualComputer;
-    sessionDir: string;
-    skills?: SkillDefinition[];
+    /** Custom sandbox. Defaults to `UnsandboxedLocal({ cwd })`. */
+    sandbox?: Sandbox;
+    /** Extra hooks to attach. */
+    hooks?: HookDefinition[];
+    /** MCP servers to connect to during `init()`. */
+    mcpServers?: Record<string, McpServerConfig>;
+    /** Custom system prompt prepended to the built-in prompt. */
     systemPrompt?: string;
-    model?: string;
-    maxTokens?: number;
-    autoCompact?: AutoCompactConfig;
-}
-declare class Thread {
-    readonly sessionId: string;
-    private config;
-    private storage;
-    private toolRegistry;
-    private messages;
-    private loaded;
-    private abortController;
-    private cwd;
-    private model;
-    constructor(config: ThreadConfig, opts?: ThreadOptions);
-    run(prompt: string, opts?: RunOptions): AsyncGenerator<StreamEvent, void, unknown>;
-    getMessages(): Promise<ChatMessage[]>;
-    compact(opts?: {
-        instructions?: string;
-    }): Promise<void>;
-    abort(): void;
-}
-
-interface CodeOptions {
-    aiProvider: AIProvider;
-    virtualFs: VirtualFs;
-    virtualComputer: VirtualComputer;
-    options?: {
-        sessionDir?: string;
-        skills?: SkillDefinition[];
-        skillsPaths?: string[];
-        systemPrompt?: string;
-        model?: string;
-        maxTokens?: number;
-        autoCompact?: boolean;
-        autoCompactThreshold?: number;
-        cwd?: string;
-    };
-}
-declare class Code {
-    private aiProvider;
-    private fs;
-    private computer;
-    private sessionDir;
-    private skills;
-    private skillsPaths;
-    private systemPrompt?;
-    private model?;
-    private maxTokens?;
-    private autoCompactEnabled;
-    private autoCompactThreshold?;
-    private cwd;
-    private storage;
-    private resolvedSkills;
-    constructor(opts: CodeOptions);
-    private getSkills;
-    createThread(opts?: ThreadOptions): Thread;
-    listSessions(): Promise<SessionInfo[]>;
-    /**
-     * Pre-resolve skills from paths. Call this once after construction if using
-     * skillsPaths, so that createThread() has skills available synchronously.
-     */
-    init(): Promise<void>;
-}
-
-interface OpenAIProviderOptions {
-    apiKey: string;
-    baseURL?: string;
-    model?: string;
-}
-declare class OpenAIProvider implements AIProvider {
-    private client;
-    private defaultModel;
-    constructor(opts: OpenAIProviderOptions);
-    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
-    private buildMessages;
-}
-
-interface AnthropicProviderOptions {
-    apiKey: string;
-    baseURL?: string;
-    model?: string;
-}
-declare class AnthropicProvider implements AIProvider {
-    private client;
-    private defaultModel;
-    constructor(opts: AnthropicProviderOptions);
-    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
-    private makeChunk;
-    private convertMessages;
-}
-
-interface GeminiProviderOptions {
-    apiKey: string;
-    model?: string;
-}
-declare class GeminiProvider implements AIProvider {
-    private client;
-    private defaultModel;
-    constructor(opts: GeminiProviderOptions);
-    chat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
-    private convertMessages;
 }
+/**
+ * Full-featured coding agent with subagents, tasks, plan mode, auto-compact,
+ * retry, cost tracking, and project context enabled out of the box.
+ */
+declare function codingAgent(opts: PresetOptions): Agent;
+/**
+ * Read-only planning agent — can explore the codebase but cannot make changes.
+ * Useful for architecture analysis, code review prep, or scoping work.
+ */
+declare function planningAgent(opts: PresetOptions): Agent;
+/**
+ * Code review agent — read-only with web search enabled for looking up
+ * documentation, best practices, and security advisories.
+ */
+declare function reviewAgent(opts: PresetOptions): Agent;
 
 interface LocalFsOptions {
     basePath?: string;
 }
+/**
+ * Unsandboxed VirtualFs backed by `node:fs/promises` on the host machine.
+ * Paths resolve relative to `basePath`. Suitable for local development and
+ * trusted environments. For production or untrusted agents, use a sandboxed
+ * implementation like `SpritesFs` (remote container) or a custom
+ * Docker/E2B adapter instead.
+ */
 declare class LocalFs implements VirtualFs {
     private basePath;
+    private resolvedBasePath;
+    private realBasePathPromise;
     constructor(opts?: LocalFsOptions);
+    private getRealBasePath;
     private resolve;
     readFile(filePath: string, opts?: ReadOptions): Promise<string>;
+    readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
     writeFile(filePath: string, content: string): Promise<void>;
     appendFile(filePath: string, content: string): Promise<void>;
     deleteFile(filePath: string, opts?: {
@@ -390,6 +94,13 @@ interface LocalComputerOptions {
     defaultCwd?: string;
     defaultTimeout?: number;
 }
+/**
+ * Unsandboxed VirtualComputer that runs commands directly on the host via
+ * `node:child_process`. Suitable for local development and trusted
+ * environments. For production or untrusted agents, use a sandboxed
+ * implementation like `SpritesComputer` (remote container) or a custom
+ * Docker/E2B adapter instead.
+ */
 declare class LocalComputer implements VirtualComputer {
     private defaultCwd;
     private defaultTimeout;
@@ -407,6 +118,13 @@ interface SpritesFsOptions {
     /** Working directory inside the sprite (default: /home/sprite) */
     workingDir?: string;
 }
+/**
+ * Sandboxed VirtualFs backed by a remote sprites.dev container. All file
+ * operations are executed over the sprites.dev HTTP API — the agent has no
+ * access to the host filesystem. This is the recommended VirtualFs for
+ * production deployments and untrusted agents. See `LocalFs` for an
+ * unsandboxed local alternative.
+ */
 declare class SpritesFs implements VirtualFs {
     private token;
     private spriteName;
@@ -417,7 +135,12 @@ declare class SpritesFs implements VirtualFs {
     private resolvePath;
     private headers;
     readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
     writeFile(filePath: string, content: string): Promise<void>;
+    /**
+     * @warning Not atomic. Concurrent appends may lose data due to
+     * read-then-write TOCTOU. The Sprites API does not expose an append primitive.
+     */
     appendFile(filePath: string, content: string): Promise<void>;
     deleteFile(filePath: string, opts?: {
         recursive?: boolean;
@@ -443,12 +166,16 @@ interface SpritesComputerOptions {
     workingDir?: string;
 }
 /**
- * Executes commands inside a sprites.dev container via the exec REST endpoint.
+ * Sandboxed VirtualComputer that executes commands inside a remote
+ * sprites.dev container. All shell execution is fully isolated — the agent
+ * has no access to the host machine's processes, filesystem, or network.
+ *
+ * This is the recommended VirtualComputer for production deployments and
+ * untrusted agents. See `LocalComputer` for an unsandboxed local alternative.
  *
- * Uses the non-interactive exec mode: POST a command and get back
- * stdout/stderr/exit_code. For more complex use cases (streaming, TTY),
- * the WebSocket exec endpoint would be used, but for tool-call purposes
- * the REST endpoint is sufficient.
+ * Uses the non-interactive exec REST endpoint (POST command, receive
+ * stdout/stderr/exit_code). The WebSocket exec endpoint can be used for
+ * streaming/TTY use cases, but REST is sufficient for tool calls.
  */
 declare class SpritesComputer implements VirtualComputer {
     private token;
@@ -461,44 +188,147 @@ declare class SpritesComputer implements VirtualComputer {
     private shellEscape;
 }
 
-interface ToolResult {
-    content: string;
-    isError?: boolean;
-}
-interface ToolContext {
-    fs: VirtualFs;
-    computer: VirtualComputer;
-    cwd: string;
-}
-interface ToolParameterProperty {
-    type: string;
-    description?: string;
-    enum?: string[];
-    default?: unknown;
-    minimum?: number;
-    maximum?: number;
-}
-interface ToolParameters {
-    type: "object";
-    properties: Record<string, ToolParameterProperty>;
-    required?: string[];
-}
-interface Tool {
-    name: string;
-    description: string;
-    parameters: ToolParameters;
-    call(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+interface DockerFsOptions {
+    /** A dockerode Container instance for the target container. */
+    container: DockerContainer;
+    /** Working directory for relative path resolution (default: /). */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by file operations inside a Docker container.
+ *
+ * Uses `container.exec()` to run filesystem commands (cat, tee, rm, mkdir,
+ * stat, etc.) inside the container. File writes use exec + tee to avoid
+ * tar archive overhead for text content.
+ *
+ * Requires `dockerode` as an optional peer dependency.
+ * The user is responsible for container lifecycle.
+ */
+declare class DockerFs implements VirtualFs {
+    private container;
+    private workingDir;
+    constructor(opts: DockerFsOptions);
+    private resolvePath;
+    private exec;
+    readFile(path: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(path: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+}
+
+interface E2BFsOptions {
+    /** An E2B Sandbox instance created via `Sandbox.create()`. */
+    sandbox: E2BSandboxInstance;
+    /** Working directory for relative path resolution. */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by the E2B cloud sandbox filesystem.
+ *
+ * Requires `e2b` as an optional peer dependency.
+ * The user is responsible for sandbox lifecycle (create, close).
+ */
+declare class E2BFs implements VirtualFs {
+    private sandbox;
+    private workingDir;
+    constructor(opts: E2BFsOptions);
+    private resolvePath;
+    readFile(path: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(path: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * @warning Not atomic. Concurrent appends may lose data due to
+     * read-then-write TOCTOU. The E2B SDK does not expose an append primitive.
+     */
+    appendFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+}
+
+interface FreestyleFsOptions {
+    /** A Freestyle VM instance. */
+    vm: FreestyleVmInstance;
+    /** Working directory for relative path resolution. */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by a Freestyle VM.
+ *
+ * Uses `vm.fs.*` for operations with native SDK support (readTextFile,
+ * writeTextFile, readDir) and falls back to `vm.exec()` for the rest
+ * (stat, exists, mkdir, deleteFile, appendFile, readFileBytes).
+ *
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ * The user is responsible for VM lifecycle when using explicit mode.
+ */
+declare class FreestyleFs implements VirtualFs {
+    private vm;
+    private workingDir;
+    constructor(opts: FreestyleFsOptions);
+    private resolvePath;
+    readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(dirPath: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    stat(filePath: string): Promise<FileStat>;
 }
 
+/**
+ * Resolve a tool flag that can be a static boolean or a function of the input.
+ * Returns `defaultValue` when the flag is `undefined`.
+ */
+declare function resolveToolFlag(flag: boolean | ((args: Record<string, unknown>) => boolean) | undefined, args: Record<string, unknown>, defaultValue?: boolean): boolean;
 declare class ToolRegistry {
     private tools;
+    private _discoveredTools;
+    private _toolSearchEnabled;
     constructor(additionalTools?: Tool[]);
+    enableToolSearch(): void;
+    register(tool: Tool): void;
     get(name: string): Tool | undefined;
-    execute(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<{
-        content: string;
-        isError?: boolean;
-    }>;
+    execute(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
     toToolDefinitions(): ToolDefinition[];
+    /**
+     * Get tool definitions filtered by tool search. Eager tools (always sent)
+     * plus any deferred tools the model has discovered via ToolSearch.
+     * Falls back to all tools when tool search is not enabled.
+     */
+    getActiveToolDefinitions(): ToolDefinition[];
+    getEagerTools(): Tool[];
+    getDeferredTools(): Tool[];
+    getToolsByNames(names: string[]): Tool[];
+    markDiscovered(names: string[]): void;
+    get discoveredTools(): ReadonlySet<string>;
     listTools(): Tool[];
 }
 
@@ -510,42 +340,1249 @@ declare const editFileTool: Tool;
 
 declare const bashTool: Tool;
 
+/**
+ * Edit utilities: fuzzy matching and quote normalization.
+ *
+ * When the model produces an `old_string` with smart/curly quotes that
+ * don't literally match the file (or vice versa), these helpers find the
+ * actual on-disk string and rewrite the replacement to preserve the file's
+ * quote style.
+ */
+/**
+ * Replace curly/smart quotes with their ASCII equivalents.
+ */
+declare function normalizeQuotes(str: string): string;
+/**
+ * Find the actual substring in `fileContent` that matches `searchString`,
+ * allowing for quote-normalization differences.
+ *
+ * Returns the literal bytes from the file that match (which may contain
+ * curly quotes even though `searchString` used straight quotes), or null
+ * if no match is found even after normalization.
+ */
+declare function findActualString(fileContent: string, searchString: string): string | null;
+/**
+ * Count occurrences of `needle` in `haystack` using the same fuzzy matching
+ * as `findActualString` — normalizes quotes before counting.
+ */
+declare function countOccurrences(haystack: string, needle: string): number;
+/**
+ * When the file uses curly quotes but the model provided straight quotes
+ * (or vice versa), rewrite `newString` to match the file's quote style.
+ *
+ * If `oldString === actualOldString`, no normalization happened and the
+ * replacement is returned unchanged.
+ */
+declare function preserveQuoteStyle(oldString: string, actualOldString: string, newString: string): string;
+/**
+ * Strip trailing whitespace (spaces/tabs) from each line, preserving
+ * the line-ending style (CRLF, LF, CR).
+ */
+declare function stripTrailingWhitespace(str: string): string;
+
 declare const globTool: Tool;
 
 declare const grepTool: Tool;
 
 /**
- * Load skill definitions from SKILL.md files found at the given paths on the VirtualFs.
- * Each path can be a directory (scanned for SKILL.md files) or a direct file.
+ * Create a Skill tool that lets the model invoke skills by name.
+ * Skill content is expanded inline with $ARGUMENTS substitution.
  */
-declare function loadSkills(fs: VirtualFs, paths: string[]): Promise<SkillDefinition[]>;
+declare function createSkillTool(getSkills: () => SkillDefinition[]): Tool;
 
-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>;
-    loadMessages(sessionId: string): Promise<ChatMessage[]>;
-    loadAllEntries(sessionId: string): Promise<Entry[]>;
-    sessionExists(sessionId: string): Promise<boolean>;
-    listSessions(): Promise<SessionInfo[]>;
+declare const agentTool: Tool;
+
+declare const webFetchTool: Tool;
+
+declare const notebookEditTool: Tool;
+
+type UserInputHandler = (question: string) => Promise<string>;
+declare const askUserTool: Tool;
+
+declare const TOOL_SEARCH_NAME = "ToolSearch";
+/**
+ * Check if a tool should be deferred (requires ToolSearch to load).
+ *
+ * A tool is deferred if:
+ * - It has `shouldDefer: true`
+ * - It's an MCP tool (has `mcpInfo`) and doesn't have `alwaysLoad: true`
+ *
+ * A tool is never deferred if it has `alwaysLoad: true`, or if it IS
+ * the ToolSearch tool itself.
+ */
+declare function isDeferredTool(tool: Tool): boolean;
+/**
+ * Format a single deferred tool as a one-line reference for the system prompt.
+ */
+declare function formatDeferredToolLine(tool: Tool): string;
+/**
+ * Keyword search over tool names and descriptions.
+ */
+declare function searchToolsWithKeywords(query: string, deferredTools: Tool[], allTools: Tool[], maxResults: number): string[];
+/**
+ * Extended Tool interface with deferral properties.
+ */
+interface ToolWithDeferral extends Tool {
+    shouldDefer?: boolean;
+    alwaysLoad?: boolean;
 }
+/**
+ * Create the ToolSearch tool. Requires access to the tool registry for
+ * looking up deferred tools and their schemas.
+ */
+declare function createToolSearchTool(getDeferredTools: () => Tool[], getAllTools: () => Tool[], getToolsByNames: (names: string[]) => Tool[], onDiscovered: (names: string[]) => void): Tool;
 
-interface CompactOptions {
-    customInstructions?: string;
+interface ToolCallExecResult {
+    toolCall: ToolCallContent;
+    parsedArgs: Record<string, unknown>;
+    result: ToolResult;
+    /** When true, the result came from a permission denial — not actual tool execution */
+    permissionDenied?: boolean;
+    /** When true, the turn loop should stop after processing this batch */
+    preventContinuation?: boolean;
+    /** Permission and lifecycle events emitted during execution */
+    events?: StreamEvent[];
+    /**
+     * Optional context modifier to apply after a concurrent batch completes.
+     * Applied in original tool_call order (not completion order) so state
+     * transitions are deterministic.
+     */
+    contextModifier?: () => void | Promise<void>;
+}
+type ToolCallExecutor = (toolCall: ToolCallContent, parsedArgs: Record<string, unknown>) => Promise<ToolCallExecResult>;
+interface Batch {
+    isConcurrencySafe: boolean;
+    items: Array<{
+        toolCall: ToolCallContent;
+        parsedArgs: Record<string, unknown>;
+    }>;
+}
+/**
+ * Partition tool calls into batches: consecutive concurrency-safe tools
+ * are grouped together; each non-safe tool gets its own batch.
+ */
+declare function partitionToolCalls(toolCalls: ToolCallContent[], getTool: (name: string) => Tool | undefined): Batch[];
+/**
+ * Execute tool calls with optimal concurrency: safe tools run in parallel,
+ * unsafe tools run one at a time.
+ */
+declare function runToolsBatched(toolCalls: ToolCallContent[], getTool: (name: string) => Tool | undefined, executor: ToolCallExecutor, concurrencyCap?: number): AsyncGenerator<ToolCallExecResult, void>;
+
+interface StreamingExecResult {
+    toolCall: ToolCallContent;
+    parsedArgs: Record<string, unknown>;
+    result: ToolResult;
+    permissionDenied?: boolean;
+    preventContinuation?: boolean;
+    events: StreamEvent[];
+}
+type StreamingToolExecutorFn = (toolCall: ToolCallContent, parsedArgs: Record<string, unknown>, signal?: AbortSignal) => Promise<{
+    result: ToolResult;
+    permissionDenied?: boolean;
+    preventContinuation?: boolean;
+    events: StreamEvent[];
+}>;
+/**
+ * Executes tools as they arrive during model streaming.
+ * Concurrency-safe tools run in parallel; unsafe tools wait for all prior
+ * executions to finish before starting.
+ *
+ * Supports abort propagation: a parent signal aborts all tools, and a
+ * Bash tool error aborts sibling tools via siblingAbortController.
+ */
+declare class StreamingToolExecutor {
+    private readonly getTool;
+    private readonly executeFn;
+    private readonly parentSignal?;
+    private tools;
+    private progressResolve?;
+    private discarded;
+    private siblingAbortController;
+    private hasErrored;
+    private processingQueue;
+    constructor(getTool: (name: string) => Tool | undefined, executeFn: StreamingToolExecutorFn, parentSignal?: AbortSignal | undefined);
+    discard(): void;
+    isDiscarded(): boolean;
+    addTool(toolCall: ToolCallContent, parsedArgs: Record<string, unknown>): void;
+    private canExecute;
+    private processQueue;
+    private createToolAbortController;
+    private executeTool;
+    getCompletedResults(): Generator<StreamingExecResult, void>;
+    getRemainingResults(): AsyncGenerator<StreamingExecResult, void>;
+    private hasUnfinished;
+    private hasExecuting;
+    private hasCompleted;
 }
-declare function compactConversation(aiProvider: AIProvider, model: string, messages: ChatMessage[], storage: SessionStorage, sessionId: string, opts?: CompactOptions): Promise<ChatMessage[]>;
 
-declare function buildSystemPrompt(opts: {
-    customPrompt?: string;
-    skills?: SkillDefinition[];
-    tools?: Tool[];
-    date?: string;
-}): string;
+interface CommandClassification {
+    /** True when every sub-command in the pipeline is read-only. */
+    isReadOnly: boolean;
+    /** True when any sub-command matches a destructive pattern. */
+    isDestructive: boolean;
+    /** Human-readable explanation of the classification. */
+    reason?: string;
+}
+interface ShellSafetyConfig {
+    /** Extra commands to treat as read-only (merged with built-in list). */
+    extraReadOnlyCommands?: string[];
+    /** Extra regex patterns to treat as destructive. */
+    extraDestructivePatterns?: RegExp[];
+}
+
+/**
+ * Shell command safety classification.
+ *
+ * Classifies bash commands as read-only or potentially destructive so the
+ * permission pipeline can make informed decisions without explicit per-command
+ * rules.
+ */
+
+declare function extractCommandName(command: string): string;
+/**
+ * Classify a shell command (potentially compound with pipes/chains).
+ *
+ * - A compound command is read-only only if ALL sub-commands are read-only.
+ * - A compound command is destructive if ANY sub-command is destructive.
+ */
+declare function classifyCommand(command: string, config?: ShellSafetyConfig): CommandClassification;
+
+/**
+ * Git-specific safety checks.
+ *
+ * Detects bare repositories, git-internal path writes, and other
+ * attack vectors (e.g. hook injection via .git/hooks/). Adapted from
+ * claude-code's gitSafety.ts and git.ts.
+ */
+/**
+ * Returns true if `path` targets a file inside `.git/` internals.
+ * Used to detect attempts to write hooks, alter config, etc.
+ */
+declare function isGitInternalPath(path: string): boolean;
+/**
+ * Heuristic: does `dirEntries` (a list of filenames/dirnames in a
+ * directory) look like a bare git repository?
+ *
+ * Returns true when all three markers (HEAD, objects/, refs/) are
+ * present *and* there is no `.git` entry (which would indicate a
+ * normal working tree).
+ */
+declare function looksLikeBareRepo(dirEntries: string[]): boolean;
+/**
+ * Check if a shell command targets git-internal paths for writes.
+ * Scans for redirect operators (`>`, `>>`, `tee`) whose target is
+ * inside `.git/` or matches a bare repo internal path.
+ */
+declare function commandWritesGitInternals(command: string): boolean;
+
+/**
+ * Git operation tracking.
+ *
+ * Parses shell command + output to detect high-level git operations
+ * (commits, pushes, PR creation, merges, rebases). Adapted from
+ * claude-code's gitOperationTracking.ts.
+ */
+type GitOperationType = "commit" | "push" | "pr_create" | "merge" | "rebase";
+interface GitOperationEvent {
+    type: GitOperationType;
+    details: string;
+}
+/**
+ * Detect git operations from a command string and its stdout output.
+ * Returns an array of events (most commands produce 0 or 1).
+ * Only detects on success — caller should check exit code first.
+ */
+declare function detectGitOperations(command: string, stdout: string): GitOperationEvent[];
+/**
+ * Check if command output indicates a git index.lock error.
+ * This commonly occurs when another git process is running.
+ */
+declare function hasGitIndexLockError(output: string): boolean;
+
+declare const taskCreateTool: Tool;
+
+declare const taskListTool: Tool;
+
+declare const taskGetTool: Tool;
+
+declare const taskUpdateTool: Tool;
+
+declare const enterPlanModeTool: Tool;
+declare const exitPlanModeTool: Tool;
+
+declare const enterWorktreeTool: Tool;
+declare const exitWorktreeTool: Tool;
+
+interface WorktreeInfo {
+    path: string;
+    branch: string;
+    head?: string;
+}
+/**
+ * Find the git root directory from a given cwd.
+ */
+declare function findGitRoot(computer: VirtualComputer, cwd: string): Promise<string | null>;
+/**
+ * Create a git worktree at the given path with the given branch name.
+ */
+declare function createWorktree(computer: VirtualComputer, repoRoot: string, worktreePath: string, branchName: string, baseBranch?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Remove a git worktree.
+ */
+declare function removeWorktree(computer: VirtualComputer, repoRoot: string, worktreePath: string, branchName?: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * List existing git worktrees.
+ */
+declare function listWorktrees(computer: VirtualComputer, cwd: string): Promise<WorktreeInfo[]>;
+/**
+ * Check if a worktree has uncommitted changes or unpushed commits.
+ */
+declare function getWorktreeChanges(computer: VirtualComputer, worktreePath: string): Promise<{
+    hasChanges: boolean;
+    uncommittedFiles: number;
+    unpushedCommits: number;
+}>;
+/**
+ * Sanitize a name for use as a worktree slug/branch name.
+ */
+declare function sanitizeWorktreeSlug(name: string): string;
+
+type SwarmMemberStatus = "pending" | "running" | "completed" | "failed" | "killed";
+interface SwarmMemberConfig {
+    name: string;
+    prompt: string;
+    systemPrompt?: string;
+    allowedTools?: string[];
+    model?: string;
+}
+interface SwarmMember {
+    id: string;
+    name: string;
+    status: SwarmMemberStatus;
+    sessionId?: string;
+    result?: string;
+    error?: Error;
+}
+interface SwarmMessage {
+    from: string;
+    to: string;
+    content: string;
+    timestamp: string;
+}
+interface SwarmConfig {
+    /** Maximum number of concurrent members (default: 4). */
+    maxConcurrent?: number;
+    /**
+     * When a swarm member hits an 'ask' permission, forward to this handler.
+     * If not set, members use bypassPermissions mode.
+     */
+    permissionHandler?: PermissionHandler;
+}
+interface SwarmStatus {
+    members: SwarmMember[];
+    messages: SwarmMessage[];
+}
+interface SwarmEvents {
+    type: "swarm_member_start" | "swarm_member_complete" | "swarm_member_failed" | "swarm_message";
+    memberId: string;
+    memberName: string;
+    content?: string;
+    error?: Error;
+}
+
+/**
+ * Backend interface for executing swarm members.
+ * The in-process backend runs Thread instances concurrently.
+ * Custom backends can spawn external processes, containers, etc.
+ */
+interface SwarmBackend {
+    spawn(config: SwarmMemberConfig, member: SwarmMember): AsyncGenerator<StreamEvent, string, unknown>;
+    kill(memberId: string): Promise<void>;
+}
+
+/**
+ * In-memory message queue for communication between swarm members.
+ */
+declare class Mailbox {
+    private messages;
+    private listeners;
+    /**
+     * Send a message from one member to another.
+     */
+    send(from: string, to: string, content: string): void;
+    /**
+     * Broadcast a message to all members except the sender.
+     */
+    broadcast(from: string, content: string, memberNames: string[]): void;
+    /**
+     * Get all messages sent to a specific member.
+     */
+    getMessagesFor(memberName: string): SwarmMessage[];
+    /**
+     * Get all unread messages for a member since the last check.
+     */
+    getNewMessagesFor(memberName: string, since: string): SwarmMessage[];
+    /**
+     * Register a listener for incoming messages to a member.
+     */
+    onMessage(memberName: string, handler: (msg: SwarmMessage) => void): () => void;
+    /**
+     * Get all messages in the mailbox.
+     */
+    getAllMessages(): SwarmMessage[];
+}
+
+/**
+ * Orchestrates multiple agent threads running in parallel.
+ */
+declare class SwarmManager {
+    private members;
+    private backend;
+    private mailbox;
+    private config;
+    private runningTasks;
+    private eventHandlers;
+    constructor(backend: SwarmBackend, config?: SwarmConfig);
+    /**
+     * Register a handler for swarm lifecycle events.
+     */
+    onEvent(handler: (event: SwarmEvents) => void): () => void;
+    private emit;
+    /**
+     * Spawn a new swarm member. Returns the member ID.
+     */
+    spawn(config: SwarmMemberConfig): Promise<string>;
+    private runMember;
+    /**
+     * Spawn multiple members concurrently. Returns their IDs.
+     */
+    spawnAll(configs: SwarmMemberConfig[]): Promise<string[]>;
+    /**
+     * Send a message between swarm members.
+     */
+    sendMessage(from: string, to: string, content: string): void;
+    /**
+     * Kill a running member.
+     */
+    kill(memberId: string): Promise<void>;
+    /**
+     * Wait for all running members to complete.
+     */
+    waitForAll(): Promise<void>;
+    /**
+     * Get current swarm status.
+     */
+    getStatus(): SwarmStatus;
+    /**
+     * Get a specific member.
+     */
+    getMember(id: string): SwarmMember | undefined;
+    /**
+     * Get the mailbox for direct access.
+     */
+    getMailbox(): Mailbox;
+    private getMemberName;
+    private waitForSlot;
+}
+
+/**
+ * In-process backend: runs each swarm member as a concurrent Thread.
+ */
+declare class InProcessBackend implements SwarmBackend {
+    private threadConfig;
+    private abortControllers;
+    constructor(threadConfig: Omit<ThreadConfig, "systemPrompt" | "model">);
+    spawn(config: SwarmMemberConfig, member: SwarmMember): AsyncGenerator<StreamEvent, string, unknown>;
+    kill(memberId: string): Promise<void>;
+}
+
+/**
+ * Normalize content to a uniform ContentPart[] representation.
+ * Strings are wrapped as a single TextContent block.
+ */
+declare function normalizeContent(content: string | ContentPart[]): ContentPart[];
+/**
+ * Extract the text representation of content. Image blocks are omitted;
+ * only text parts are concatenated.
+ */
+declare function contentToString(content: string | ContentPart[]): string;
+/**
+ * Returns true if the content contains at least one image block.
+ */
+declare function hasImageContent(content: string | ContentPart[]): boolean;
+/**
+ * Strip image blocks from content, replacing them with a text placeholder.
+ * Returns a plain string when the result contains only text.
+ */
+declare function stripImageContent(content: string | ContentPart[], placeholder?: string): string | ContentPart[];
+
+/**
+ * Run multiple async generators concurrently up to a concurrency cap,
+ * yielding values as they become available. Generators beyond the cap
+ * are started as earlier ones finish.
+ */
+declare function all<A>(generators: AsyncGenerator<A, void>[], concurrencyCap?: number): AsyncGenerator<A, void>;
+
+/**
+ * Load skill definitions from SKILL.md files found at the given paths on the VirtualFs.
+ * Each path can be a directory (scanned for SKILL.md files) or a direct file.
+ */
+declare function loadSkills(fs: VirtualFs, paths: string[]): Promise<SkillDefinition[]>;
+
+interface FrontmatterData {
+    "allowed-tools"?: string | string[] | null;
+    description?: string | null;
+    paths?: string | string[] | null;
+    context?: "inline" | "fork" | null;
+    "argument-hint"?: string | null;
+    [key: string]: unknown;
+}
+interface ParsedFrontmatter {
+    frontmatter: FrontmatterData;
+    body: string;
+}
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Returns the parsed frontmatter fields and the body after the closing ---.
+ * If no frontmatter is found, returns empty frontmatter and the full content as body.
+ */
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+/**
+ * Parse the allowed-tools field from frontmatter.
+ * Accepts a string (comma/space separated), string[], or null/undefined.
+ */
+declare function parseAllowedTools(value: string | string[] | null | undefined): string[];
+/**
+ * Parse the paths field from frontmatter into glob patterns.
+ */
+declare function parsePaths(value: string | string[] | null | undefined): string[];
+
+/**
+ * Check which skills should be activated based on file paths the agent touched.
+ * Skills with `globs` are conditional -- they only activate when a matching file is touched.
+ * Skills without `globs` are always active.
+ *
+ * Returns the names of newly-activated conditional skills.
+ */
+declare function activateSkillsForPaths(allSkills: SkillDefinition[], filePaths: string[], cwd: string, alreadyActivated: Set<string>): string[];
+/**
+ * Get all currently active skills: unconditional ones + activated conditional ones.
+ */
+declare function getActiveSkills(allSkills: SkillDefinition[], activatedNames: Set<string>): SkillDefinition[];
+
+interface CompactOptions {
+    customInstructions?: string;
+    /** Number of recent messages to keep uncompacted (default: 0 = summarize all). */
+    tailMessagesToKeep?: number;
+    /** Strip binary/image content from messages before sending to the summarizer. */
+    stripBinaryContent?: boolean;
+    /** Abort signal — if fired, the partial summary is discarded instead of persisted. */
+    signal?: AbortSignal;
+    /**
+     * Recently-read file contents to reinject after compaction so the model
+     * doesn't lose awareness of files that were only in the compacted portion.
+     * Map of file path -> file content. At most 5 files are reinjected, capped
+     * at 50 KB total.
+     */
+    recentlyReadFiles?: Map<string, string>;
+}
+declare function compactConversation(provider: AIProvider, model: string, messages: ChatMessage[], storage: SessionStorage, sessionId: string, opts?: CompactOptions): Promise<ChatMessage[]>;
+/**
+ * Estimate the token savings from a potential compaction.
+ */
+declare function estimateCompactionSavings(messages: ChatMessage[], tailMessagesToKeep: number): {
+    currentTokens: number;
+    estimatedAfter: number;
+};
+
+/**
+ * Model context window sizes and effective window calculations.
+ */
+/**
+ * Register custom context window sizes for models not in the built-in table.
+ */
+declare function registerContextWindows(windows: Record<string, number>): void;
+/**
+ * Get the context window size for a model. Checks custom overrides first,
+ * then built-in table, then prefix-matches, then falls back to default.
+ */
+declare function getContextWindowForModel(model: string): number;
+/**
+ * Effective context window = total window minus space reserved for the
+ * model's output during a compaction/summary request.
+ */
+declare function getEffectiveContextWindow(model: string, maxOutputTokens?: number): number;
+/**
+ * Auto-compact threshold: effective window minus a buffer to ensure we
+ * compact before we're at the hard limit.
+ */
+declare function getAutoCompactThreshold(model: string, maxOutputTokens?: number): number;
+
+/**
+ * Rough token estimation: ~4 chars per token for English text.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate tokens across an array of messages (pure estimation, no API anchor).
+ */
+declare function estimateMessagesTokens(messages: Array<{
+    role: string;
+    content: string | unknown;
+}>): number;
+/**
+ * Usage-grounded token counting. Uses the last API response's prompt_tokens
+ * as an anchor and only estimates delta messages added since.
+ *
+ * If no usage anchor is available, falls back to pure estimation.
+ */
+declare function tokenCountWithEstimation(messages: ChatMessage[], lastUsage?: ChatCompletionUsage, anchorMessageIndex?: number): number;
+/**
+ * Group messages into API-round groups. A new group starts at each
+ * assistant boundary (after tool results) or user message. This gives
+ * finer-grained groups than splitting on user messages alone, enabling
+ * PTL recovery in agentic sessions with many tool-use rounds.
+ */
+declare function groupMessagesByTurn(messages: ChatMessage[]): ChatMessage[][];
+interface PTLRetryOptions {
+    /** Tokens the server reported we need to shed, or undefined if unknown. */
+    tokenGap?: number;
+    /** Effective context window for this model (fallback when gap unknown). */
+    targetTokens: number;
+}
+/**
+ * Drop the oldest turn groups to fit within the context window.
+ *
+ * If `tokenGap` is provided (parsed from the server error), use it to
+ * determine exactly how many tokens to shed. Otherwise fall back to
+ * dropping 20% of groups (more conservative than the heuristic target).
+ */
+declare function truncateHeadForPTLRetry(messages: ChatMessage[], targetOrOpts: number | PTLRetryOptions): ChatMessage[];
+
+declare function buildSystemPrompt(opts: {
+    customPrompt?: string;
+    skills?: SkillDefinition[];
+    tools?: Tool[];
+    date?: string;
+    projectContext?: string;
+    memorySection?: string;
+    deferredTools?: {
+        name: string;
+        description: string;
+    }[];
+}): string;
+
+/**
+ * Load project context files from the hierarchical NOUMEN.md / CLAUDE.md
+ * convention. Returns files ordered lowest-to-highest priority:
+ * managed -> user -> project (root first, cwd last) -> local.
+ */
+declare function loadProjectContext(fs: VirtualFs, config: ProjectContextConfig): Promise<ContextFile[]>;
+/**
+ * Filter context files to only those whose globs match at least one
+ * of the given file paths. Files without globs (unconditional) always pass.
+ */
+declare function filterActiveContextFiles(files: ContextFile[], touchedPaths: string[], cwd: string): ContextFile[];
+/**
+ * Check which conditional context files are newly activated by the given
+ * touched paths. Returns the paths of newly activated files.
+ */
+declare function activateContextForPaths(allFiles: ContextFile[], touchedPaths: string[], cwd: string, alreadyActivated: Set<string>): string[];
+
+/**
+ * Format loaded context files into a system prompt section.
+ *
+ * Files are rendered in array order (lowest to highest priority).
+ * Included sub-files are inlined immediately after their parent.
+ */
+declare function buildProjectContextSection(files: ContextFile[], filter?: ContextScope[]): string;
+
+/**
+ * Check whether a tool name matches a rule's `toolName` field.
+ *
+ * Supports:
+ *  - Exact match: `"Bash"` matches `"Bash"`
+ *  - MCP server-level wildcard: rule `"mcp__myserver"` matches any tool
+ *    on that server (e.g. `"mcp__myserver__sometool"`)
+ */
+declare function toolMatchesRule(toolName: string, rule: PermissionRule, mcpInfo?: {
+    serverName: string;
+    toolName: string;
+}): boolean;
+/**
+ * Match a content string against a rule's `ruleContent`.
+ *
+ * Three match modes (following claude-code's bash/filesystem patterns):
+ *  - **exact**: `ruleContent === content`
+ *  - **prefix**: `ruleContent` ends with `:*` → prefix match
+ *  - **glob**: `ruleContent` contains `*` or `**` → simple glob match
+ *
+ * For deny/ask rules, also tries matching after stripping env vars and
+ * safe wrapper commands from the content.
+ */
+declare function contentMatchesRule(content: string, ruleContent: string): boolean;
+/**
+ * Minimal glob matching for file-path rules.
+ *
+ * Supports `*` (any non-separator chars) and `**` (any chars including `/`).
+ * Anchored: the entire string must match.
+ */
+declare function matchSimpleGlob(pattern: string, value: string): boolean;
+/**
+ * Return all rules in `context` that match the given tool and behavior,
+ * optionally filtered by content.
+ */
+declare function getMatchingRules(context: PermissionContext, toolName: string, behavior: PermissionBehavior, content?: string, mcpInfo?: {
+    serverName: string;
+    toolName: string;
+}): PermissionRule[];
+/**
+ * Check whether a file path falls within any of the configured working directories.
+ */
+declare function isPathInWorkingDirectories(filePath: string, workingDirectories: string[]): boolean;
+
+interface DenialLimits {
+    maxConsecutive: number;
+    maxTotal: number;
+}
+interface DenialState {
+    consecutiveDenials: number;
+    totalDenials: number;
+}
+type FallbackCheck = {
+    triggered: false;
+} | {
+    triggered: true;
+    reason: "consecutive" | "total" | "repeated_consecutive";
+};
+/**
+ * Tracks permission denials and determines when limits are exceeded.
+ * When limits are hit, the system should fall back to prompting or abort.
+ */
+declare class DenialTracker {
+    private state;
+    private limits;
+    private consecutiveFallbacksWithoutSuccess;
+    constructor(limits?: Partial<DenialLimits>);
+    recordDenial(): void;
+    recordSuccess(): void;
+    shouldFallback(): FallbackCheck;
+    /**
+     * Reset counters after a fallback. Only resets totalDenials when the
+     * total limit was the trigger — consecutive-only fallbacks preserve
+     * the total counter so the session-wide safety net stays effective.
+     *
+     * Tracks repeated consecutive fallbacks: if `resetAfterFallback("consecutive")`
+     * is called again without an intervening `recordSuccess()`, the next
+     * `shouldFallback()` returns `"repeated_consecutive"` to signal escalation.
+     */
+    resetAfterFallback(trigger: "consecutive" | "total"): void;
+    getState(): Readonly<DenialState>;
+    reset(): void;
+}
+
+/**
+ * Resolve the permission decision for a tool invocation.
+ *
+ * Pipeline mirrors claude-code's `hasPermissionsToUseToolInner`:
+ *  1. Deny rules for the whole tool
+ *  2. Ask rules for the whole tool
+ *  3. Tool's own `checkPermissions` (if defined)
+ *  4. Mode-based bypass / enforcement
+ *  5. Content-specific allow rules
+ *  6. Fallback: passthrough → ask
+ */
+interface ResolvePermissionOptions {
+    provider?: AIProvider;
+    model?: string;
+    recentMessages?: ChatMessage[];
+    autoModeConfig?: AutoModeConfig;
+    signal?: AbortSignal;
+    denialTracker?: DenialTracker;
+}
+declare function resolvePermission(tool: Tool, input: Record<string, unknown>, ctx: ToolContext, permCtx: PermissionContext, opts?: ResolvePermissionOptions): Promise<PermissionDecision>;
+
+/**
+ * Apply a permission update to an in-memory context.
+ * Returns the mutated context (same reference).
+ */
+declare function applyPermissionUpdate(ctx: PermissionContext, update: PermissionUpdate): PermissionContext;
+/**
+ * Apply multiple permission updates in order.
+ */
+declare function applyPermissionUpdates(ctx: PermissionContext, updates: PermissionUpdate[]): PermissionContext;
+
+interface ClassifierResult {
+    shouldBlock: boolean;
+    reason: string;
+}
+/**
+ * Run a side-query to classify whether a tool call should be auto-approved.
+ */
+declare function classifyPermission(toolName: string, args: Record<string, unknown>, recentMessages: ChatMessage[], provider: AIProvider, opts?: {
+    classifierPrompt?: string;
+    classifierModel?: string;
+    model?: string;
+    signal?: AbortSignal;
+}): Promise<ClassifierResult>;
+
+/**
+ * Default pricing table for common models. Keys are matched as substrings
+ * against the model ID so versioned model strings (e.g. `claude-sonnet-4`)
+ * resolve correctly.
+ */
+declare const DEFAULT_PRICING: Record<string, ModelPricing>;
+/**
+ * Find pricing for a model by checking if the model string contains any
+ * known pricing key as a substring. More specific keys (longer) are
+ * checked first to ensure e.g. "gpt-4o-mini" matches before "gpt-4o".
+ */
+declare function findModelPricing(model: string, pricing: Record<string, ModelPricing>): ModelPricing | null;
+/**
+ * Calculate USD cost for a usage record using the given pricing table.
+ * Returns 0 if the model is not found in the pricing table and logs a
+ * one-time warning per unknown model.
+ */
+declare function calculateCost(model: string, usage: UsageRecord, pricing?: Record<string, ModelPricing>): number;
+
+/**
+ * Provider-agnostic error classification for retry decisions.
+ * Extracts status codes and retry hints from common SDK error shapes
+ * without depending on any specific provider's types.
+ */
+interface ClassifiedError {
+    originalError: unknown;
+    message: string;
+    status?: number;
+    retryAfter?: string;
+    isOverloaded: boolean;
+    isContextOverflow: boolean;
+    contextOverflowData?: {
+        inputTokens: number;
+        maxTokens: number;
+        contextLimit: number;
+    };
+}
+/**
+ * Classify an unknown error into retry-relevant metadata.
+ * Works across OpenAI, Anthropic, and Gemini SDK error shapes by
+ * duck-typing common properties (`.status`, `.headers`, `.message`).
+ */
+declare function classifyError(error: unknown): ClassifiedError;
+declare function isRetryable(classified: ClassifiedError, config: RetryConfig): boolean;
+
+/**
+ * Compute retry delay with exponential backoff and jitter.
+ * If a Retry-After header value is provided (seconds), it takes precedence.
+ * Ported from claude-code's getRetryDelay with the same formula.
+ */
+declare function getRetryDelay(attempt: number, retryAfterHeader?: string | null, maxDelayMs?: number, baseDelayMs?: number): number;
+
+declare class CannotRetryError extends Error {
+    readonly originalError: unknown;
+    readonly retryContext: RetryContext;
+    constructor(originalError: unknown, retryContext: RetryContext);
+}
+/**
+ * Retry engine that wraps a stream-creating operation.
+ * Yields retry_attempt events while waiting, then returns the stream on success.
+ *
+ * The operation receives a RetryContext that may include a maxTokensOverride
+ * (after context overflow) or a different model (after fallback).
+ */
+declare function withRetry(operation: (ctx: RetryContext) => AsyncIterable<ChatStreamChunk>, options: RetryEngineOptions): AsyncGenerator<StreamEvent, AsyncIterable<ChatStreamChunk>>;
+
+/**
+ * Run pre-tool-use hooks. Returns a merged output where later hooks override
+ * earlier ones. A 'deny' decision from any hook short-circuits.
+ */
+declare function runPreToolUseHooks(hooks: HookDefinition[], input: PreToolUseHookInput): Promise<PreToolUseHookOutput>;
+/**
+ * Run post-tool-use hooks. Returns merged output.
+ */
+declare function runPostToolUseHooks(hooks: HookDefinition[], input: PostToolUseHookInput): Promise<PostToolUseHookOutput>;
+/**
+ * Run post-tool-use-failure hooks. Same shape as post-tool-use hooks but
+ * triggers on the PostToolUseFailure event, fired only when `isError` is true.
+ */
+declare function runPostToolUseFailureHooks(hooks: HookDefinition[], input: PostToolUseFailureHookInput): Promise<PostToolUseFailureHookOutput>;
+/**
+ * Run notification hooks concurrently (fire-and-forget, no return value).
+ */
+declare function runNotificationHooks(hooks: HookDefinition[], event: HookEvent, input: HookInput): Promise<void>;
+
+declare class NoopSpan implements Span {
+    readonly name: string;
+    constructor(name: string);
+    setAttribute(_key: string, _value: SpanAttributeValue): void;
+    addEvent(_name: string, _attributes?: Record<string, SpanAttributeValue>): void;
+    setStatus(_code: SpanStatusCode, _message?: string): void;
+    end(): void;
+}
+declare class NoopTracer implements Tracer {
+    startSpan(name: string, _options?: SpanOptions): Span;
+}
+
+/**
+ * Adapter that bridges noumen's `Tracer` interface to an OpenTelemetry
+ * `TracerProvider`. The `@opentelemetry/api` package is loaded lazily via
+ * dynamic `import()` so it remains an optional peer dependency.
+ *
+ * Call `OTelTracer.create()` (async factory) to obtain an instance.
+ * If `@opentelemetry/api` is not installed, the factory returns a `NoopTracer`.
+ */
+declare class OTelTracer implements Tracer {
+    private otelTracer;
+    private api;
+    private constructor();
+    /**
+     * Create an `OTelTracer`. Falls back to `NoopTracer` if
+     * `@opentelemetry/api` is not available at runtime.
+     */
+    static create(serviceName?: string, version?: string): Promise<Tracer>;
+    startSpan(name: string, options?: SpanOptions): Span;
+}
+
+interface IndexTruncation {
+    content: string;
+    lineCount: number;
+    byteCount: number;
+    wasLineTruncated: boolean;
+    wasByteTruncated: boolean;
+}
+declare function truncateIndex(raw: string, maxLines?: number, maxBytes?: number): IndexTruncation;
+/**
+ * Default `MemoryProvider` that stores memories as individual `.md` files
+ * with YAML frontmatter, plus a `MEMORY.md` index. All I/O goes through
+ * `VirtualFs` so it works with any sandbox backend.
+ */
+declare class FileMemoryProvider implements MemoryProvider {
+    private fs;
+    private dir;
+    private maxIndexLines;
+    constructor(fs: VirtualFs, memoryDir: string, maxIndexLines?: number);
+    private indexPath;
+    private ensureDir;
+    loadIndex(): Promise<string>;
+    loadEntry(path: string): Promise<MemoryEntry | null>;
+    saveEntry(entry: MemoryEntry): Promise<void>;
+    removeEntry(path: string): Promise<void>;
+    listEntries(): Promise<MemoryEntry[]>;
+    search(query: string): Promise<MemoryEntry[]>;
+    private rebuildIndex;
+}
+
+/**
+ * Prompt helpers for the memory system.
+ *
+ * `buildMemorySystemPromptSection` generates the instruction block injected
+ * into the system prompt that teaches the model about the four-type memory
+ * taxonomy and how to read/write memories.
+ *
+ * `buildExtractionPrompt` generates the user message sent to the LLM when
+ * auto-extracting memories from a completed conversation turn.
+ *
+ * Both are adapted from claude-code's memdir/memoryTypes prompt helpers,
+ * stripped of analytics, team memory, and Anthropic-specific concerns.
+ */
+/**
+ * Build the system-prompt section that teaches the model about its persistent
+ * memory directory.
+ *
+ * @param indexContent - The current contents of MEMORY.md (may be empty).
+ * @param memoryDir   - Absolute path to the memory directory.
+ */
+declare function buildMemorySystemPromptSection(indexContent: string, memoryDir: string): string;
+/**
+ * Build the prompt sent to the LLM to extract durable memories from a
+ * conversation. The response should be a JSON object with a `memories` array.
+ */
+declare function buildExtractionPrompt(conversationSummary: string, existingIndex: string): string;
+
+interface ExtractMemoriesResult {
+    created: MemoryEntry[];
+    updated: MemoryEntry[];
+    deleted: string[];
+}
+/**
+ * Extract durable memories from a conversation by making a single
+ * structured-output LLM call. Applies the returned actions to the
+ * `MemoryProvider` and returns a summary of changes.
+ */
+declare function extractMemories(llmProvider: AIProvider, model: string, messages: ChatMessage[], provider: MemoryProvider): Promise<ExtractMemoriesResult>;
+
+/**
+ * Cache-safe parameters for subagent prompt cache sharing.
+ *
+ * When a subagent (fork) shares the same system prompt, model, tools, and
+ * thinking config as its parent, both can share the same prompt cache
+ * prefix. CacheSafeParams captures these values so the child thread can
+ * inherit them and avoid cache breaks.
+ */
+
+interface CacheSafeParams {
+    systemPrompt: string;
+    model: string;
+    tools: ToolDefinition[];
+    thinking?: ThinkingConfig;
+}
+declare function saveCacheSafeParams(params: CacheSafeParams | null, sessionId?: string): void;
+declare function getLastCacheSafeParams(sessionId?: string): CacheSafeParams | null;
+declare function createCacheSafeParams(opts: {
+    systemPrompt: string;
+    model: string;
+    tools: ToolDefinition[];
+    thinking?: ThinkingConfig;
+}): CacheSafeParams;
+
+/**
+ * Centralized message normalization for API calls.
+ *
+ * Ensures a ChatMessage[] is structurally valid before being sent to any
+ * provider. Handles duplicate tool IDs, orphaned results, missing pairing,
+ * empty assistants, consecutive same-role messages, and other corruption
+ * from error/abort/compaction paths.
+ *
+ * Pure function: returns a new array, never mutates the input.
+ */
+
+/**
+ * Normalize a message array so it is structurally valid for any LLM API.
+ *
+ * Transformations applied (order matters):
+ *  1. Drop system messages (system prompt is a separate param)
+ *  2. Deduplicate tool_use IDs across assistants
+ *  3. Strip orphaned tool_results with no matching tool_use
+ *  4. Deduplicate tool_results with the same tool_call_id
+ *  5. Insert synthetic error results for unpaired tool_uses
+ *  6. Filter orphaned thinking-only assistants (null/undefined content)
+ *  7. Filter whitespace-only assistant messages
+ *  8. Merge consecutive same-role messages
+ *  9. Ensure every assistant has non-null content
+ * 10. Strip thinking-only trailing assistant (after merge — merge can
+ *     create new trailing messages with only thinking content)
+ * 11. Ensure array starts with a user message
+ */
+declare function normalizeMessagesForAPI(messages: ChatMessage[]): ChatMessage[];
+
+/**
+ * Conversation recovery and message sanitization.
+ *
+ * Cleans up persisted messages before resuming a session so the API
+ * receives a structurally valid conversation. Handles crashes, streaming
+ * interruptions, orphaned tool calls, and whitespace-only messages.
+ *
+ * Shared normalization primitives (merge, filter, pairing) live in
+ * `src/messages/normalize.ts` and are re-exported here for backward
+ * compatibility.
+ */
+
+type TurnInterruption = {
+    kind: "none";
+} | {
+    kind: "interrupted_tool";
+} | {
+    kind: "interrupted_prompt";
+};
+interface SanitizeResult {
+    messages: ChatMessage[];
+    interruption: TurnInterruption;
+    /** Number of messages removed by each filter (for diagnostics). */
+    removals: {
+        unresolvedToolUses: number;
+        whitespaceOnly: number;
+        orphanedThinking: number;
+    };
+}
+/**
+ * Drop assistant messages where *every* tool_call has no matching tool
+ * result message. Keeps assistants that have at least one resolved call
+ * or no tool_calls at all.
+ */
+declare function filterUnresolvedToolUses(messages: ChatMessage[]): {
+    messages: ChatMessage[];
+    removed: number;
+};
+/**
+ * Drop assistant messages that are whitespace-only text with no
+ * tool_calls (API-invalid). After removal, merge consecutive user
+ * messages to restore role alternation.
+ */
+declare function filterWhitespaceOnlyAssistantMessages(messages: ChatMessage[]): {
+    messages: ChatMessage[];
+    removed: number;
+};
+/**
+ * Drop assistant messages that contain only thinking content (no
+ * real text and no tool_calls). These are artifacts of streaming
+ * interruptions where a thinking block was streamed but the model
+ * never produced a real response.
+ */
+declare function filterOrphanedThinkingMessages(messages: ChatMessage[]): {
+    messages: ChatMessage[];
+    removed: number;
+};
+/**
+ * Detect whether the conversation was interrupted mid-turn.
+ *
+ * Walks backward from the end skipping system messages to find the
+ * last significant message. Returns `interrupted_tool` when the last
+ * message is a tool result (agent got results but model never replied),
+ * `interrupted_prompt` when the last message is a user prompt (model
+ * never started), or `none` otherwise.
+ */
+declare function detectTurnInterruption(messages: ChatMessage[]): TurnInterruption;
+/**
+ * Run the full sanitization pipeline on a set of persisted messages.
+ *
+ * Order matters:
+ * 1. Remove unresolved tool uses (structural — fixes orphan tool_calls)
+ * 2. Remove orphaned thinking messages (streaming artifacts)
+ * 3. Remove whitespace-only assistants (API validity)
+ * 4. Detect turn interruption (must happen last, on clean messages)
+ */
+declare function sanitizeForResume(messages: ChatMessage[]): SanitizeResult;
+/**
+ * Generate synthetic tool result messages for tool_calls in an
+ * assistant message that have no matching result yet. Used to
+ * prevent orphaned tool_calls from corrupting the conversation
+ * when streaming is interrupted or provider errors occur.
+ */
+declare function generateMissingToolResults(assistantMsg: AssistantMessage, existingResults: ChatMessage[], reason: string): ToolResultMessage[];
+
+/**
+ * Session resume / restore.
+ *
+ * Parses a persisted JSONL session and extracts everything needed to
+ * reconstruct thread state: messages (respecting compact boundaries),
+ * file checkpoint snapshots, metadata, and tool result overflow entries.
+ */
+
+interface ResumePayload {
+    messages: ChatMessage[];
+    checkpointSnapshots: FileCheckpointSnapshot[];
+    metadata: Record<string, unknown>;
+    costState?: StoredCostState;
+    overflowEntries: ToolResultOverflowEntry[];
+    /** Persisted content replacement records for disk-spilled tool results. */
+    contentReplacements: ContentReplacementRecord[];
+    /** Detected turn interruption state after sanitization. */
+    interruption: TurnInterruption;
+    /** Number of messages removed per sanitization filter. */
+    recoveryRemovals: {
+        unresolvedToolUses: number;
+        whitespaceOnly: number;
+        orphanedThinking: number;
+    };
+}
+/**
+ * Restore a session from its persisted JSONL transcript.
+ *
+ * Returns everything needed to reconstruct Thread state:
+ * - Messages after the last compact boundary
+ * - File checkpoint snapshot chain
+ * - Session metadata (title, custom keys)
+ * - Tool result overflow entries
+ */
+declare function restoreSession(storage: SessionStorage, sessionId: string): Promise<ResumePayload>;
+
+/**
+ * Runtime invariant assertions for normalized message sequences.
+ *
+ * `assertValidMessageSequence` throws an `InvariantViolation` error
+ * when a ChatMessage[] violates the structural rules that every LLM
+ * provider expects. Wire it behind a `debug` flag in thread.ts to
+ * catch normalization regressions during development and testing.
+ */
+
+declare class InvariantViolation extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert that `messages` is a structurally valid sequence for the LLM API.
+ *
+ * Checks:
+ *  1. Non-empty (at least one message)
+ *  2. First message has role "user"
+ *  3. No system messages
+ *  4. No consecutive same-role (non-tool) messages
+ *  5. Every tool_use has exactly one matching tool result
+ *  6. No orphaned tool results (no matching tool_use)
+ *  7. No duplicate tool_use IDs
+ *  8. No duplicate tool_result IDs
+ *  9. No assistant with null/undefined content
+ * 10. No whitespace-only assistant without tool_calls or thinking_content
+ * 11. Trailing assistant must not be thinking-only (no text, no tool_calls)
+ * 12. Tool results appear in a contiguous block after their owning assistant
+ */
+declare function assertValidMessageSequence(messages: ChatMessage[]): void;
+
+declare const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+/**
+ * Creates a synthetic tool whose input schema matches the user's desired
+ * output schema. When the model calls this tool, the agent loop treats it
+ * as the final structured response and terminates.
+ *
+ * This is the "final_response" pattern: the model reasons freely (using
+ * tools), and signals completion by calling StructuredOutput with data
+ * that conforms to the schema.
+ */
+declare function createStructuredOutputTool(format: JsonSchemaOutputFormat): Tool;
+
+/**
+ * Image resize / compress pipeline.
+ *
+ * Ported from claude-code's imageResizer.ts. Uses `sharp` (optional peer
+ * dependency) for dimension caps, iterative quality reduction, and API
+ * base64 size guards. Gracefully degrades when sharp is not installed.
+ */
+/** Maximum base64-encoded image size (API enforced by most providers). */
+declare const API_IMAGE_MAX_BASE64_SIZE: number;
+declare const IMAGE_MAX_WIDTH = 8000;
+declare const IMAGE_MAX_HEIGHT = 8000;
+interface ImageDimensions {
+    width: number;
+    height: number;
+}
+interface ResizedImage {
+    buffer: Buffer;
+    mediaType: string;
+    dimensions?: ImageDimensions;
+}
+interface CompressedImageResult {
+    base64: string;
+    mediaType: string;
+}
+/**
+ * Resize and downsample an image buffer if it exceeds dimension or size
+ * limits. Returns the (possibly unchanged) buffer with mediaType info.
+ */
+declare function maybeResizeAndDownsampleImageBuffer(imageBuffer: Buffer, originalSize: number, ext: string): Promise<ResizedImage>;
+/**
+ * Decode base64 image block, resize, re-encode.
+ */
+declare function maybeResizeAndDownsampleImageBlock(imageBlock: {
+    data: string;
+    media_type: string;
+}): Promise<{
+    data: string;
+    media_type: string;
+    dimensions?: ImageDimensions;
+}>;
+/**
+ * Compress an image to fit within a token budget.
+ * Token formula: tokens ≈ base64_chars × 0.125
+ */
+declare function compressImageBufferWithTokenLimit(imageBuffer: Buffer, maxTokens: number, originalMediaType?: string): Promise<CompressedImageResult>;
+declare const IMAGE_EXTENSIONS: Set<string>;
+/**
+ * Create dimension metadata text for the model (helps with coordinate reasoning).
+ */
+declare function createImageMetadataText(dims: ImageDimensions): string;
 
-export { type AIProvider, AnthropicProvider, type AnthropicProviderOptions, type AssistantMessage, type AutoCompactConfig, type ChatCompletionUsage, type ChatMessage, type ChatParams, type ChatStreamChoice, type ChatStreamChunk, type ChatStreamDelta, Code, type CodeOptions, type CommandResult, type CompactBoundaryEntry, type CustomTitleEntry, type Entry, type ExecOptions, type FileEntry, type FileStat, GeminiProvider, type GeminiProviderOptions, LocalComputer, type LocalComputerOptions, LocalFs, type LocalFsOptions, type MessageEntry, type MetadataEntry, OpenAIProvider, type OpenAIProviderOptions, type ReadOptions, type RunOptions, type SerializedMessage, type SessionInfo, type SkillDefinition, SpritesComputer, type SpritesComputerOptions, SpritesFs, type SpritesFsOptions, type StreamEvent, type SummaryEntry, type SystemMessage, Thread, type ThreadConfig, type ThreadOptions, type Tool, type ToolCallContent, type ToolResult as ToolCallResult, type ToolContext, type ToolParameterProperty$1 as ToolDefParameterProperty, type ToolDefinition, type ToolParameters, ToolRegistry, type ToolResult$1 as ToolResult, type ToolResultMessage, type UserMessage, type VirtualComputer, type VirtualFs, bashTool, buildSystemPrompt, compactConversation, createAutoCompactConfig, editFileTool, globTool, grepTool, loadSkills, readFileTool, shouldAutoCompact, writeFileTool };
+export { AIProvider, API_IMAGE_MAX_BASE64_SIZE, Agent, AssistantMessage, AutoModeConfig, type CacheSafeParams, CannotRetryError, ChatCompletionUsage, ChatMessage, ChatStreamChunk, type ClassifiedError, type ClassifierResult, type CommandClassification, CommandResult, type CompactOptions, type CompressedImageResult, ContentPart, ContentReplacementRecord, ContextFile, ContextScope, DEFAULT_PRICING, type DenialLimits, type DenialState, DenialTracker, DockerContainer, DockerFs, type DockerFsOptions, E2BFs, type E2BFsOptions, E2BSandboxInstance, ExecOptions, type ExtractMemoriesResult, FileCheckpointSnapshot, FileEntry, FileMemoryProvider, FileStat, FreestyleFs, type FreestyleFsOptions, FreestyleVmInstance, type FrontmatterData, type GitOperationEvent, type GitOperationType, HookDefinition, HookEvent, HookInput, IMAGE_EXTENSIONS, IMAGE_MAX_HEIGHT, IMAGE_MAX_WIDTH, type ImageDimensions, InProcessBackend, type IndexTruncation, InvariantViolation, JsonSchemaOutputFormat, LocalComputer, type LocalComputerOptions, LocalFs, type LocalFsOptions, Mailbox, McpServerConfig, MemoryEntry, MemoryProvider, ModelPricing, NoopSpan, NoopTracer, OTelTracer, type ParsedFrontmatter, PermissionBehavior, PermissionContext, PermissionDecision, PermissionHandler, PermissionRule, PermissionUpdate, PostToolUseFailureHookInput, PostToolUseFailureHookOutput, PostToolUseHookInput, PostToolUseHookOutput, PreToolUseHookInput, PreToolUseHookOutput, type PresetOptions, ProjectContextConfig, ReadOptions, type ResizedImage, type ResolvePermissionOptions, type ResumePayload, RetryConfig, RetryContext, RetryEngineOptions, STRUCTURED_OUTPUT_TOOL_NAME, Sandbox, type SanitizeResult, type ShellSafetyConfig, SkillDefinition, Span, SpanAttributeValue, SpanOptions, SpanStatusCode, SpritesComputer, type SpritesComputerOptions, SpritesFs, type SpritesFsOptions, StoredCostState, StreamEvent, type StreamingExecResult, StreamingToolExecutor, type StreamingToolExecutorFn, type SwarmBackend, type SwarmConfig, type SwarmEvents, SwarmManager, type SwarmMember, type SwarmMemberConfig, type SwarmMemberStatus, type SwarmMessage, type SwarmStatus, TOOL_SEARCH_NAME, ThinkingConfig, ThreadConfig, Tool, ToolCallContent, type ToolCallExecResult, type ToolCallExecutor, ToolResult as ToolCallResult, ToolContext, ToolDefinition, ToolRegistry, ToolResultMessage, ToolResultOverflowEntry, type ToolWithDeferral, Tracer, type TurnInterruption, UsageRecord, type UserInputHandler, VirtualComputer, VirtualFs, type WorktreeInfo, activateContextForPaths, activateSkillsForPaths, agentTool, all, applyPermissionUpdate, applyPermissionUpdates, askUserTool, assertValidMessageSequence, bashTool, buildExtractionPrompt, buildMemorySystemPromptSection, buildProjectContextSection, buildSystemPrompt, calculateCost, classifyCommand, classifyError, classifyPermission, codingAgent, commandWritesGitInternals, compactConversation, compressImageBufferWithTokenLimit, contentMatchesRule, contentToString, countOccurrences, createCacheSafeParams, createImageMetadataText, createSkillTool, createStructuredOutputTool, createToolSearchTool, createWorktree, detectGitOperations, detectTurnInterruption, editFileTool, enterPlanModeTool, enterWorktreeTool, estimateCompactionSavings, estimateMessagesTokens, estimateTokens, exitPlanModeTool, exitWorktreeTool, extractCommandName, extractMemories, filterActiveContextFiles, filterOrphanedThinkingMessages, filterUnresolvedToolUses, filterWhitespaceOnlyAssistantMessages, findActualString, findGitRoot, findModelPricing, formatDeferredToolLine, generateMissingToolResults, getActiveSkills, getAutoCompactThreshold, getContextWindowForModel, getEffectiveContextWindow, getLastCacheSafeParams, getMatchingRules, getRetryDelay, getWorktreeChanges, globTool, grepTool, groupMessagesByTurn, hasGitIndexLockError, hasImageContent, isDeferredTool, isGitInternalPath, isPathInWorkingDirectories, isRetryable, listWorktrees, loadProjectContext, loadSkills, looksLikeBareRepo, matchSimpleGlob, maybeResizeAndDownsampleImageBlock, maybeResizeAndDownsampleImageBuffer, normalizeContent, normalizeMessagesForAPI, normalizeQuotes, notebookEditTool, parseAllowedTools, parseFrontmatter, parsePaths, partitionToolCalls, planningAgent, preserveQuoteStyle, readFileTool, registerContextWindows, removeWorktree, resolvePermission, resolveToolFlag, restoreSession, reviewAgent, runNotificationHooks, runPostToolUseFailureHooks, runPostToolUseHooks, runPreToolUseHooks, runToolsBatched, sanitizeForResume, sanitizeWorktreeSlug, saveCacheSafeParams, searchToolsWithKeywords, stripImageContent, stripTrailingWhitespace, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, tokenCountWithEstimation, toolMatchesRule, truncateHeadForPTLRetry, truncateIndex, webFetchTool, withRetry, writeFileTool };