noumen 0.4.0 → 0.6.0

package/dist/{agent-1nFVUP9E.d.ts → agent-DWE4_P5X.d.ts}

@@ -1,8 +1,10 @@
-import { A as AIProvider, S as StreamEvent, b as ChatMessage, E as Entry, U as UUID, d as FileCheckpointSnapshot, f as ContentReplacementRecord$1, g as SessionInfo, M as ModelPricing, h as UsageRecord, i as CostSummary, j as ModelUsageSummary, k as ChatCompletionUsage, l as ThinkingConfig, m as MemoryConfig, O as OutputFormat, e as ContentPart, R as RunOptions, c as CheckpointConfig, n as ToolResult } from './types-LrU4LRmX.js';
-import { j as VirtualComputer, E as ExecOptions, C as CommandResult, V as VirtualFs, T as Tool, H as HookDefinition, S as SubagentConfig, k as SubagentRun, l as TaskStore, e as LspServerManager, m as FileCheckpointManager, n as FileStateCacheConfig, L as LspServerConfig } from './types-RPKUTu1k.js';
-import { C as CacheControlConfig } from './cache-DsRqxx6v.js';
+import { A as AIProvider, b as ChatMessage, S as StreamEvent, 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-kiGBF35b.js';
+import { S as Sandbox } from './sandbox-9qeMTNrD.js';
+import { T as Tool, H as HookDefinition, S as SubagentConfig, i as SubagentRun, j as TaskStore, e as LspServerManager, F as FileCheckpointManager, k as FileStateCacheConfig, L as LspServerConfig } from './types-DhXwOQwD.js';
+import { C as CacheControlConfig } from './cache-BlBwXXPS.js';
 import { M as McpServerConfig, T as TokenStorage } from './types-2kTLUCnD.js';
 import { c as PermissionHandler, d as PermissionConfig } from './types-CD0rUKKT.js';
+import { a as VirtualFs, V as VirtualComputer } from './computer-BPdxSo6X.js';
 
 type ProviderName = "openai" | "anthropic" | "gemini" | "openrouter" | "bedrock" | "vertex" | "ollama";
 declare const DEFAULT_MODELS: Record<string, string>;
@@ -26,506 +28,89 @@ declare function resolveProvider(input: AIProvider | ProviderName, opts?: Resolv
 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.
+ * AI-generated session title helper.
  *
- * 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.
+ * Given a short prompt sourced from recent messages, ask a provider to
+ * produce a 3–7 word sentence-case title suitable for a session list.
  *
- * Requires `e2b` as an optional peer dependency.
- * The user is responsible for sandbox lifecycle (create, close).
+ * This is a pure helper: it never touches the filesystem and never knows
+ * about `SessionStorage`. Callers (e.g. `Agent.autoTitleIfMissing`) own
+ * persistence and event emission.
  */
-declare class E2BComputer implements VirtualComputer {
-    private sandbox;
-    private defaultCwd;
-    private defaultTimeout;
-    constructor(opts: E2BComputerOptions);
-    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
-}
 
 /**
- * Minimal subset of the Freestyle VM interface used by FreestyleComputer and
- * FreestyleFs. Avoids a hard import of `freestyle-sandboxes` at the module
- * level — the real SDK is only loaded dynamically during `FreestyleSandbox`
- * auto-creation.
- */
-interface FreestyleVmInstance {
-    exec(command: string, opts?: {
-        cwd?: string;
-        timeout?: number;
-    }): Promise<{
-        stdout: string | null;
-        stderr: string | null;
-        statusCode: number | null;
-    }>;
-    fs: {
-        readTextFile(path: string): Promise<string>;
-        writeTextFile(path: string, content: string): Promise<void>;
-        readDir(path: string): Promise<Array<{
-            name: string;
-            kind: string;
-        }>>;
-    };
-    suspend(): Promise<unknown>;
-    start(): Promise<unknown>;
-}
-interface FreestyleComputerOptions {
-    /** A Freestyle VM instance. */
-    vm: FreestyleVmInstance;
-    /** Default working directory for commands. */
-    defaultCwd?: string;
-    /** Default timeout in ms for commands (default: 30000). */
-    defaultTimeout?: number;
-}
-/**
- * VirtualComputer backed by command execution in a Freestyle VM.
+ * Config for the Agent's opt-in auto-title feature.
  *
- * Requires `freestyle-sandboxes` as an optional peer dependency.
- * The user is responsible for VM lifecycle when using explicit mode.
+ * Pass `true` for defaults (use the Agent's own provider + its
+ * `defaultModel`). Pass an object to customise the provider, model,
+ * system prompt, or input cap.
  */
-declare class FreestyleComputer implements VirtualComputer {
-    private vm;
-    private defaultCwd;
-    private defaultTimeout;
-    constructor(opts: FreestyleComputerOptions);
-    executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
-}
-
-/**
- * Bundled sandbox: a `VirtualFs` and `VirtualComputer` paired together.
- *
- * Use one of the built-in factories (`LocalSandbox`, `UnsandboxedLocal`,
- * `SpritesSandbox`) or supply any object that satisfies this shape for
- * custom sandboxes (Docker, E2B, Daytona, in-memory, etc.).
- */
-interface Sandbox {
-    fs: VirtualFs;
-    computer: VirtualComputer;
-    /** Optional cleanup — called by Agent.close() to tear down OS-level sandbox state. */
-    dispose?(): Promise<void>;
+interface AutoTitleConfig {
+    /** Master switch. Default false on `AgentOptions.autoTitle`. */
+    enabled?: boolean;
     /**
-     * Lazily provision the underlying sandbox resource. Idempotent — repeated
-     * calls return the same single-flight promise.
-     *
-     * When `sandboxId` is provided the sandbox reconnects to an existing
-     * resource instead of creating a new one. This is used during session
-     * resume: the stored sandbox identifier is read from session metadata
-     * and passed here so the agent reattaches to its previous container.
-     *
-     * When omitted a fresh resource is provisioned (for factories that
-     * support auto-creation) or the call is a no-op (for factories that
-     * were given a pre-created resource up front).
+     * Override provider used for title generation. Falls back to the
+     * Agent's main provider.
      */
-    init?(sandboxId?: string): Promise<void>;
+    provider?: AIProvider;
     /**
-     * Return the opaque identifier for this sandbox instance so it can be
-     * persisted in session metadata and used to reconnect later via `init()`.
-     * Returns `undefined` before `init()` has resolved or for sandboxes
-     * that don't support reconnection.
+     * Override model (e.g. `"claude-haiku-4-5"`). Falls back to the
+     * provider's `defaultModel`.
      */
-    sandboxId?(): string | undefined;
-}
-interface UnsandboxedLocalOptions {
-    /** Working directory for both file resolution and command execution. */
-    cwd?: string;
-    /** Default timeout (ms) for shell commands. */
-    defaultTimeout?: number;
+    model?: string;
+    /** Override system prompt. */
+    systemPrompt?: string;
+    /** Cap on seed-text characters. Defaults to 2 000. */
+    maxInputChars?: number;
 }
+/** Default cap on characters fed to the title model. */
+declare const DEFAULT_AUTO_TITLE_MAX_INPUT_CHARS = 2000;
 /**
- * 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`).
+ * System prompt for the auto-title generator. Mirrors the shape used by
+ * Claude Code so that output quality is familiar.
  */
-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;
+declare const DEFAULT_AUTO_TITLE_SYSTEM_PROMPT = "Generate a concise, sentence-case title (3-7 words) that captures the main topic or goal of this coding session. The title should be clear enough that the user recognizes the session in a list. Use sentence case: capitalize only the first word and proper nouns.\n\nReturn JSON with a single \"title\" field.\n\nGood examples:\n{\"title\": \"Fix login button on mobile\"}\n{\"title\": \"Add OAuth authentication\"}\n{\"title\": \"Debug failing CI tests\"}\n{\"title\": \"Refactor API client error handling\"}\n\nBad (too vague): {\"title\": \"Code changes\"}\nBad (too long): {\"title\": \"Investigate and fix the issue where the login button does not respond on mobile devices\"}\nBad (wrong case): {\"title\": \"Fix Login Button On Mobile\"}";
+interface GenerateAutoTitleOptions {
+    provider: AIProvider;
+    /** Model override. When omitted, uses `provider.defaultModel`. */
+    model?: string;
+    /** System prompt override. Falls back to the built-in prompt. */
+    systemPrompt?: string;
+    /** Character cap on the flattened input. Defaults to 2 000. */
+    maxInputChars?: number;
+    signal?: AbortSignal;
 }
 /**
- * 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.
+ * Flatten recent user + assistant text into a single block of plain text
+ * suitable for the title model. Tool results are skipped; image parts
+ * are skipped; only the tail of the concatenated text is kept when long
+ * so the most recent context wins.
  */
-declare function LocalSandbox(opts?: LocalSandboxOptions): Sandbox;
-interface SpritesSandboxOptions {
-    /** sprites.dev API token. */
-    token: string;
-    /**
-     * Name of an existing sprite container. When provided the sandbox
-     * attaches to this sprite directly — no auto-creation occurs and
-     * `dispose()` will **not** delete it (lifecycle is yours to manage).
-     *
-     * When omitted a new sprite is provisioned on the first `init()` call
-     * (via `POST /v1/sprites`). The auto-created sprite is deleted when
-     * `dispose()` is called, and its name is available via `sandboxId()`
-     * for session persistence.
-     */
-    spriteName?: string;
-    /** Base URL for sprites API (default: https://api.sprites.dev). */
-    baseURL?: string;
-    /** Working directory inside the sprite (default: /home/sprite). */
-    workingDir?: string;
-    /**
-     * Optional prefix for auto-generated sprite names (default: "noumen-").
-     * Only used when `spriteName` is omitted.
-     */
-    namePrefix?: string;
-}
+declare function extractTitleSeedText(messages: ChatMessage[], maxChars?: number): string;
 /**
- * Create a `Sandbox` backed by a remote sprites.dev container.
- * Full isolation — the agent has no access to the host machine.
- *
- * **Auto-creation:** When `spriteName` is omitted the sandbox is created
- * lazily on the first `init()` call via the Sprites REST API. The sprite
- * name is available through `sandboxId()` so callers can persist it in
- * session metadata for reconnection on resume. Pass the stored name back
- * through `init(storedId)` to reattach instead of creating a new sprite.
- *
- * **Explicit ID:** When `spriteName` is provided the sandbox attaches to
- * that sprite immediately on `init()`. `dispose()` is a no-op in this
- * case — the caller owns the sprite's lifecycle.
+ * Attempt to pull a title out of a free-form model response.
  *
- * @example
- * ```ts
- * // Auto-create — sprite provisioned on first init()
- * const sandbox = SpritesSandbox({ token: process.env.SPRITES_TOKEN! });
+ * Strategy, cheapest-first:
+ *   1. Parse the whole string as JSON; return `.title` if present.
+ *   2. Slice out the first `{...}` block and `JSON.parse` that.
+ *   3. Fall back to the first bare quoted substring in the response.
  *
- * // Explicit — attach to pre-existing sprite, no auto-lifecycle
- * const sandbox = SpritesSandbox({
- *   token: process.env.SPRITES_TOKEN!,
- *   spriteName: "my-sprite",
- * });
- * ```
+ * Going through `JSON.parse` (instead of a bespoke regex-unescape) means
+ * `\n`, `\\`, `\uXXXX`, and any other valid JSON string escapes round-trip
+ * correctly — the previous regex only handled `\"`.
  */
-declare function SpritesSandbox(opts: SpritesSandboxOptions): Sandbox;
-interface DockerSandboxOptions {
-    /**
-     * A pre-existing dockerode Container instance. When provided the sandbox
-     * attaches to this container directly — no auto-creation occurs and
-     * `dispose()` will **not** stop or remove it.
-     *
-     * When omitted, a new container is created from `image` on the first
-     * `init()` call via a dynamic import of `dockerode`. The auto-created
-     * container is stopped and removed when `dispose()` is called.
-     */
-    container?: DockerContainer;
-    /**
-     * Docker image to use for auto-creation (e.g. `"ubuntu:22.04"`).
-     * Required when `container` is omitted; ignored when `container` is provided.
-     */
-    image?: string;
-    /** Command to run in the auto-created container (default: `["sleep", "infinity"]`). */
-    cmd?: string[];
-    /** Environment variables for the auto-created container. */
-    env?: string[];
-    /** Extra options passed to dockerode `createContainer`. */
-    dockerOptions?: Record<string, unknown>;
-    /** Working directory inside the container. */
-    cwd?: string;
-    /** Default timeout (ms) for shell commands. */
-    defaultTimeout?: number;
-}
-/**
- * Create a `Sandbox` backed by a Docker container.
- * Requires `dockerode` as an optional peer dependency.
- *
- * **Auto-creation:** When `container` is omitted and `image` is provided,
- * the container is created and started lazily on the first `init()` call.
- * The container ID is available through `sandboxId()` for session
- * persistence. Pass the stored ID back through `init(storedId)` to
- * reattach to an existing container on resume.
- *
- * **Explicit container:** When `container` is provided, `init()` binds
- * it immediately. `dispose()` is a no-op — the caller owns the
- * container's lifecycle.
- *
- * @example
- * ```ts
- * // Auto-create from image
- * const sandbox = DockerSandbox({ image: "ubuntu:22.04", cwd: "/workspace" });
- *
- * // Explicit container (lifecycle managed externally)
- * const sandbox = DockerSandbox({ container: myDockerodeContainer });
- * ```
- */
-declare function DockerSandbox(opts: DockerSandboxOptions): Sandbox;
-interface E2BSandboxOptions {
-    /**
-     * A pre-existing E2B Sandbox instance (e.g. from `Sandbox.create()`).
-     * When provided the sandbox attaches to this instance — no auto-creation
-     * occurs and `dispose()` will **not** kill it.
-     *
-     * When omitted, a new E2B sandbox is created on the first `init()` call
-     * via a dynamic import of the `e2b` package. The auto-created sandbox
-     * is killed when `dispose()` is called.
-     */
-    sandbox?: E2BSandboxInstance;
-    /**
-     * E2B template to use for auto-creation (default: `"base"`).
-     * Only used when `sandbox` is omitted.
-     */
-    template?: string;
-    /**
-     * E2B API key. Falls back to the `E2B_API_KEY` environment variable
-     * when omitted. Only used during auto-creation.
-     */
-    apiKey?: string;
-    /** Timeout (ms) for the auto-created E2B sandbox (default: E2B SDK default). */
-    timeoutMs?: number;
-    /** Working directory inside the sandbox. */
-    cwd?: string;
-    /** Default timeout (ms) for shell commands. */
-    defaultTimeout?: number;
-}
+declare function extractTitleFromResponse(raw: string): string | null;
 /**
- * Create a `Sandbox` backed by an E2B cloud sandbox.
- * Requires `e2b` as an optional peer dependency.
- *
- * **Auto-creation:** When `sandbox` is omitted the E2B sandbox is
- * provisioned lazily on the first `init()` call via the E2B SDK.
- * The sandbox ID is available through `sandboxId()` for session
- * persistence. Pass the stored ID back through `init(storedId)` to
- * reconnect to the same sandbox on resume (via `Sandbox.connect()`).
- *
- * **Explicit instance:** When `sandbox` is provided, `init()` binds
- * it immediately. `dispose()` is a no-op — the caller owns the
- * sandbox's lifecycle.
- *
- * @example
- * ```ts
- * // Auto-create — sandbox provisioned on first init()
- * const sandbox = E2BSandbox({ template: "base" });
- *
- * // Explicit — attach to pre-existing instance
- * const sandbox = E2BSandbox({ sandbox: await E2BSdk.Sandbox.create() });
- * ```
+ * Drive the provider once to produce a session title. Returns null on
+ * empty seed text, empty model output, or provider errors (callers decide
+ * whether to retry — this helper never throws).
  */
-declare function E2BSandbox(opts: E2BSandboxOptions): Sandbox;
-interface FreestyleSandboxOptions {
-    /**
-     * A pre-existing Freestyle VM instance. When provided the sandbox
-     * attaches to this VM directly — no auto-creation occurs and
-     * `dispose()` will **not** suspend or delete it.
-     *
-     * When omitted, a new VM is created on the first `init()` call via
-     * a dynamic import of the `freestyle-sandboxes` package.
-     */
-    vm?: FreestyleVmInstance;
-    /**
-     * Freestyle API key. Falls back to the `FREESTYLE_API_KEY` environment
-     * variable when omitted. Only used during auto-creation.
-     */
-    apiKey?: string;
-    /** Snapshot ID to create the VM from. Only used during auto-creation. */
-    snapshotId?: string;
-    /**
-     * A `VmSpec` instance or configuration object passed through to
-     * `freestyle.vms.create()`. Only used during auto-creation.
-     */
-    spec?: unknown;
-    /**
-     * Idle timeout in seconds for the auto-created VM (default: 600).
-     * The VM auto-suspends after this many seconds of network inactivity.
-     */
-    idleTimeoutSeconds?: number;
-    /** Working directory inside the VM. */
-    cwd?: string;
-    /** Default timeout (ms) for shell commands. */
-    defaultTimeout?: number;
-    /** Files to provision at creation time. */
-    additionalFiles?: Record<string, {
-        content: string;
-        encoding?: string;
-    }>;
-    /** Git repos to clone at creation time. */
-    gitRepos?: Array<{
-        repo: string;
-        path: string;
-        rev?: string;
-    }>;
-    /**
-     * What to do with auto-created VMs on `dispose()`:
-     * - `"suspend"` (default) — suspends the VM, preserving full memory
-     *   state for near-instant resume on reconnect.
-     * - `"delete"` — permanently deletes the VM and frees all resources.
-     */
-    disposeStrategy?: "suspend" | "delete";
-}
+declare function generateAutoTitle(messages: ChatMessage[], opts: GenerateAutoTitleOptions): Promise<string | null>;
 /**
- * Create a `Sandbox` backed by a Freestyle VM.
- * Requires `freestyle-sandboxes` as an optional peer dependency.
- *
- * **Auto-creation:** When `vm` is omitted a new Freestyle VM is
- * provisioned lazily on the first `init()` call. The VM ID is available
- * through `sandboxId()` for session persistence. Pass the stored ID back
- * through `init(storedId)` to reconnect (this also wakes suspended VMs).
- *
- * By default, auto-created VMs are **suspended** on `dispose()` rather
- * than deleted. This preserves full memory state and allows near-instant
- * resume. Set `disposeStrategy: "delete"` for full cleanup.
- *
- * **Explicit instance:** When `vm` is provided, `init()` binds it
- * immediately. `dispose()` is a no-op — the caller owns the VM's
- * lifecycle.
- *
- * @example
- * ```ts
- * // Auto-create — VM provisioned on first init()
- * const sandbox = FreestyleSandbox({ cwd: "/workspace" });
- *
- * // Auto-create from a snapshot
- * const sandbox = FreestyleSandbox({
- *   snapshotId: "abc123",
- *   cwd: "/workspace",
- * });
- *
- * // Explicit — attach to pre-existing VM
- * const sandbox = FreestyleSandbox({ vm: existingVm });
- * ```
+ * Trim, collapse whitespace, strip wrapping quotes, clamp length.
+ * Returns null if the cleaned string would be empty.
  */
-declare function FreestyleSandbox(opts: FreestyleSandboxOptions): Sandbox;
+declare function normalizeTitle(raw: string): string | null;
 
 interface SkillDefinition {
     name: string;
@@ -719,13 +304,36 @@ declare class SessionStorage {
     appendContentReplacement(sessionId: string, replacements: ContentReplacementRecord$1[]): Promise<void>;
     appendMetadata(sessionId: string, key: string, value: unknown): Promise<void>;
     /**
-     * Re-append custom-title and key metadata entries after a compact boundary
-     * so they remain discoverable in the active-entries window.
+     * Append a user-set session title. Wins over any `ai-title` when read.
+     * Idempotent-ish: callers may append as many as they like; the last one
+     * wins according to file order.
+     */
+    appendCustomTitle(sessionId: string, title: string): Promise<void>;
+    /**
+     * Append an AI-generated session title. A `custom-title` (if present)
+     * always takes precedence on read.
+     */
+    appendAiTitle(sessionId: string, title: string): Promise<void>;
+    /**
+     * Re-append custom-title, ai-title, and key metadata entries after a
+     * compact boundary so they remain discoverable in the active-entries
+     * window. Written as a single batched append so a crash mid-write can't
+     * leave the transcript with only a subset of the re-emitted entries.
      */
     reAppendMetadataAfterCompact(sessionId: string): Promise<void>;
     loadMessages(sessionId: string): Promise<ChatMessage[]>;
     loadAllEntries(sessionId: string): Promise<Entry[]>;
     sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Return the currently persisted titles for a session. `title` reflects
+     * the display preference (custom > ai). Returns all-undefined if the
+     * session file doesn't exist.
+     */
+    getSessionTitles(sessionId: string): Promise<{
+        title?: string;
+        customTitle?: string;
+        aiTitle?: string;
+    }>;
     deleteSession(sessionId: string): Promise<void>;
     listSessions(): Promise<SessionInfo[]>;
 }
@@ -1127,10 +735,21 @@ interface AgentOptions {
     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.
+     *
+     * Local backends live on the root barrel:
+     * - `LocalSandbox()` — OS-level sandboxing (requires `@anthropic-ai/sandbox-runtime`).
+     * - `UnsandboxedLocal()` — raw host access.
+     *
+     * Remote backends are subpath imports so their optional peer deps do
+     * not enter the module graph unless opted into:
+     * - `import { DockerSandbox }    from "noumen/docker"`
+     * - `import { E2BSandbox }       from "noumen/e2b"`
+     * - `import { FreestyleSandbox } from "noumen/freestyle"`
+     * - `import { SshSandbox }       from "noumen/ssh"`
+     * - `import { SpritesSandbox }   from "noumen/sprites"`
+     *
+     * You can also 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
@@ -1193,6 +812,17 @@ interface AgentOptions {
         outputFormat?: OutputFormat;
         /** Default structured output mode for all threads. */
         structuredOutputMode?: "alongside_tools" | "final_response";
+        /**
+         * Opt-in AI-generated session titles. When enabled, callers can invoke
+         * `agent.autoTitleIfMissing(sessionId)` (typically once per session,
+         * e.g. after the first assistant turn) to produce a short title and
+         * persist it as an `ai-title` JSONL entry. User-set `custom-title`
+         * entries (see `agent.setCustomTitle`) always take precedence on read.
+         *
+         * Pass `true` for defaults (same provider as the Agent, provider's
+         * default model, built-in prompt) or an object to customise.
+         */
+        autoTitle?: AutoTitleConfig | boolean;
     };
 }
 interface RunCallbacks {
@@ -1266,6 +896,14 @@ declare class Agent {
     private historySnipConfig;
     private outputFormat;
     private structuredOutputMode;
+    private autoTitleConfig;
+    /**
+     * Keyed by `${sessionId}:${force ? "force" : "normal"}`. Parallel calls
+     * that pass the same `force` mode coalesce to one in-flight request; a
+     * `force: true` call arriving during a normal in-flight request runs its
+     * own pass so the caller's intent isn't silently dropped.
+     */
+    private autoTitleInFlight;
     private providerPromise;
     private initPromise;
     constructor(opts: AgentOptions);
@@ -1276,6 +914,52 @@ declare class Agent {
     private createSpawnSubagent;
     createThread(opts?: ThreadOptions): Promise<Thread>;
     listSessions(): Promise<SessionInfo[]>;
+    /**
+     * Load the message history for a stored session, respecting compact
+     * boundaries and history snips. Returns `[]` when the session does
+     * not exist. Use this to rehydrate a UI — resuming a Thread for
+     * further execution should go through `resumeThread()` instead.
+     */
+    getMessages(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Persist a user-set title for a session. Takes precedence over any
+     * AI-generated title on read. No-op on empty / whitespace-only input.
+     */
+    setCustomTitle(sessionId: string, title: string): Promise<void>;
+    /**
+     * Persist an AI-generated title for a session. A user-set title
+     * (see `setCustomTitle`) always wins on read, so writing this after a
+     * user has renamed the session is harmless.
+     */
+    setAiTitle(sessionId: string, title: string): Promise<void>;
+    /**
+     * Delete a session's persisted transcript. Does not affect any
+     * currently-running `Thread` reading from the same session id.
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Return the currently persisted titles for a session.
+     * `title` reflects the display preference (custom > ai).
+     */
+    getSessionTitles(sessionId: string): Promise<{
+        title?: string;
+        customTitle?: string;
+        aiTitle?: string;
+    }>;
+    /**
+     * When `autoTitle` is enabled and the session has no title yet,
+     * generate one via the configured provider + model and persist it
+     * as an `ai-title` entry. Returns the new title on success, or `null`
+     * when skipped (feature disabled, title already present, empty seed,
+     * or provider error).
+     *
+     * Concurrency-safe: parallel calls for the same session coalesce to
+     * a single in-flight request.
+     */
+    autoTitleIfMissing(sessionId: string, opts?: {
+        signal?: AbortSignal;
+        force?: boolean;
+    }): Promise<string | null>;
     getCostSummary(): CostSummary | null;
     /**
      * Create a thread that resumes an existing session. Automatically restores
@@ -1329,4 +1013,4 @@ declare class Agent {
     close(): Promise<void>;
 }
 
-export { type RunCallbacks as $, Agent as A, type BudgetState as B, type ContextFile as C, type DockerContainer as D, type E2BSandboxInstance as E, type FreestyleVmInstance as F, E2BComputer as G, type E2BComputerOptions as H, E2BSandbox as I, type E2BSandboxOptions as J, FreestyleComputer as K, type FreestyleComputerOptions as L, FreestyleSandbox as M, type FreestyleSandboxOptions as N, LocalSandbox as O, type ProjectContextConfig as P, type LocalSandboxOptions as Q, type RetryConfig as R, type Sandbox as S, type ThreadConfig as T, type MicrocompactConfig as U, type MicrocompactResult as V, type ProviderName as W, type ReactiveCompactConfig as X, type ReactiveCompactResult as Y, type ResolveProviderOptions as Z, type RetryEvent as _, type SkillDefinition as a, type RunResult as a0, SUPPORTED_PROVIDERS as a1, type SandboxConfig as a2, SandboxedLocalComputer as a3, type SandboxedLocalComputerOptions as a4, type SnipConfig as a5, type SnipResult as a6, SpritesSandbox as a7, type SpritesSandboxOptions as a8, Thread as a9, recordAutoCompactFailure as aA, recordAutoCompactSuccess as aB, resolveProvider as aC, shouldAutoCompact as aD, snipMessagesByUuids as aE, tryReactiveCompact as aF, webSearchToolPlaceholder as aG, type ThreadOptions as aa, type ToolResultBudgetConfig as ab, type ToolResultBudgetResult as ac, type ContentReplacementRecord as ad, type ToolResultSpillResult as ae, type ToolResultStorageConfig as af, type TracingConfig as ag, UnsandboxedLocal as ah, type UnsandboxedLocalOptions as ai, type WebSearchConfig as aj, type WebSearchResult as ak, applyPersistedReplacements as al, applySnipRemovals as am, canAutoCompact as an, createAutoCompactConfig as ao, createAutoCompactTracking as ap, createBudgetState as aq, createContentReplacementState as ar, createWebSearchTool as as, detectProvider as at, enforceToolResultBudget as au, enforceToolResultStorageBudget as av, microcompactMessages as aw, persistToolResult as ax, projectSnippedView as ay, reconstructContentReplacementState as az, SessionStorage as b, type ContextScope as c, type RetryContext as d, type RetryEngineOptions as e, type Span as f, type SpanAttributeValue as g, SpanStatusCode as h, type Tracer as i, type SpanOptions as j, type StoredCostState as k, type AgentOptions as l, type AutoCompactConfig as m, type AutoCompactTrackingState as n, CLEARED_PLACEHOLDER as o, COMPACTABLE_TOOLS as p, type ContentReplacementState as q, CostTracker as r, DEFAULT_MODELS as s, DEFAULT_RETRY_CONFIG as t, type DiagnoseCheckResult as u, type DiagnoseResult as v, DockerComputer as w, type DockerComputerOptions as x, DockerSandbox as y, type DockerSandboxOptions as z };
+export { type WebSearchResult as $, Agent as A, type BudgetState as B, type ContextFile as C, DEFAULT_AUTO_TITLE_MAX_INPUT_CHARS as D, type ReactiveCompactResult as E, type ResolveProviderOptions as F, type GenerateAutoTitleOptions as G, type RetryEvent as H, type RunCallbacks as I, type RunResult as J, SUPPORTED_PROVIDERS as K, type SnipConfig as L, type MicrocompactConfig as M, type SnipResult as N, Thread as O, type ProjectContextConfig as P, type ThreadOptions as Q, type RetryConfig as R, type SkillDefinition as S, type ThreadConfig as T, type ToolResultBudgetConfig as U, type ToolResultBudgetResult as V, type ContentReplacementRecord as W, type ToolResultSpillResult as X, type ToolResultStorageConfig as Y, type TracingConfig as Z, type WebSearchConfig as _, type AutoTitleConfig as a, applyPersistedReplacements as a0, applySnipRemovals as a1, canAutoCompact as a2, createAutoCompactConfig as a3, createAutoCompactTracking as a4, createBudgetState as a5, createContentReplacementState as a6, createWebSearchTool as a7, detectProvider as a8, enforceToolResultBudget as a9, enforceToolResultStorageBudget as aa, extractTitleFromResponse as ab, extractTitleSeedText as ac, generateAutoTitle as ad, microcompactMessages as ae, normalizeTitle as af, persistToolResult as ag, projectSnippedView as ah, reconstructContentReplacementState as ai, recordAutoCompactFailure as aj, recordAutoCompactSuccess as ak, resolveProvider as al, shouldAutoCompact as am, snipMessagesByUuids as an, tryReactiveCompact as ao, webSearchToolPlaceholder as ap, 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_AUTO_TITLE_SYSTEM_PROMPT as s, DEFAULT_MODELS as t, DEFAULT_RETRY_CONFIG as u, type DiagnoseCheckResult as v, type DiagnoseResult as w, type MicrocompactResult as x, type ProviderName as y, type ReactiveCompactConfig as z };