@livx.cc/agentx 0.94.38

package/dist/index.d.ts

@@ -0,0 +1,1319 @@
+import { a as AgentOptions, H as Hooks, h as RunResult, A as Agent } from './Agent-1DRfsYaK.js';
+export { C as ChatFragment, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as ReasoningEffort, f as RecordingHooks, g as RecordingLifecycle, T as ToolUse, i as ToolUseMeta, j as composeHooks, p as planMode, r as reasoningToChatFragment } from './Agent-1DRfsYaK.js';
+import { IFilesystem, FileMetadata } from '@livx.cc/wcli/core';
+export { CommandExecutor, FileMetadata, IFilesystem, IndexedDbFilesystem, MemFilesystem, registerHeadlessCommands } from '@livx.cc/wcli/core';
+import { BodDB } from '@bod.ee/db';
+import { A as AgentTool, C as ChatLike, a as ChatOptions, b as ChatResponse, h as ToolCall, H as HostBridge, U as UserQuestion, e as MessageContent } from './tools-DtpN8Agv.js';
+export { c as ContentPart, d as HostEvent, M as Message, R as Role, S as SandboxJobRegistry, f as StreamChunk, T as TodoItem, g as Tool, i as ToolContext, j as bashTool, k as contentText, l as defaultTools, m as editTool, n as exitSessionTool, o as imagePart, p as makeContext, q as makeJobTools, r as readTool, t as toWireTools, s as todoWriteTool, u as toolRegistry, v as toolsByName } from './tools-DtpN8Agv.js';
+export { M as McpCall, a as McpImage, b as McpRoute, c as McpRouteResolver, d as McpToolResult, e as McpToolSearchOptions, f as McpToolSpec, g as MountedMcpLike, h as buildMcpCatalog, m as makeLazyMcpToolSearch, i as makeMcpToolSearch, j as makeMcpToolSearchFromMounted, k as mcpToolToAgentTool, l as mcpToolsToAgentTools } from './mcp-CnzmQ8JE.js';
+import * as libx_js_src_modules_log from 'libx.js/src/modules/log';
+export { log } from 'libx.js/src/modules/log';
+
+/**
+ * Real-disk backend implementing wcli's IFilesystem, rooted at `baseDir`.
+ * The VFS path space ('/...') maps under baseDir, so the same agent/tools/commands
+ * run unchanged against disk or memory — complete mem↔disk interchangeability.
+ * Semantics mirror MemFilesystem (throws on missing parent / existing dir / etc.).
+ */
+declare class NodeDiskFilesystem implements IFilesystem {
+    private baseDir;
+    private cwd;
+    private opts;
+    constructor(baseDir: string, opts?: {
+        denySymlinks?: boolean;
+    });
+    /** Ensure the root dir exists. */
+    init(): Promise<void>;
+    private real;
+    private verified;
+    private static VERIFY_TTL_MS;
+    /** Throw if any existing component of `real` is a symlink (escape vector). */
+    private assertNoSymlink;
+    resolvePath(path: string, cwd?: string): string;
+    getCwd(): string;
+    setCwd(path: string): void;
+    readFile(path: string): Promise<string>;
+    /** Read raw bytes (for binary files like images). Not on the base IFilesystem (which is utf8-only) — an
+     *  optional capability the Read tool duck-types to return image blocks. Same symlink/jail guards as readFile. */
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    readDir(path: string): Promise<string[]>;
+    createDir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileMetadata>;
+    isDirectory(path: string): Promise<boolean>;
+    isFile(path: string): Promise<boolean>;
+}
+
+/**
+ * Database-backed `IFilesystem` over bod-db's VFS — the normalization thesis realized: the agent
+ * operates on a file tree that lives in a database, yet the same tools/commands run unchanged
+ * (semantics mirror MemFilesystem/NodeDiskFilesystem: throw on missing parent / existing dir /
+ * non-empty dir / missing file). bod-db's VFS is path-based and async, so the adapter is thin.
+ *
+ * Construct with no args for an in-memory DB (great for tests), or pass a configured `BodDB`
+ * (with VFS enabled) backed by real/cloud storage for persistence. Call `close()` when done to
+ * release the DB's timers (the in-memory default uses `sweepInterval: 0`, so there's nothing to sweep).
+ */
+declare class BodDbFilesystem implements IFilesystem {
+    private cwd;
+    private db;
+    private vfs;
+    private owns;
+    constructor(db?: BodDB);
+    /** Release the underlying DB's timers/handles. Closes only a DB we created (a passed-in DB is the caller's). */
+    close(): void;
+    resolvePath(path: string, cwd?: string): string;
+    getCwd(): string;
+    setCwd(path: string): void;
+    /** Parent dir of an absolute VFS path ('/a/b.txt' -> '/a'; '/a' -> '/'). */
+    private parentOf;
+    /** Throw (matching the other backends) unless the parent directory exists. Root is always a dir. */
+    private assertParentDir;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    readDir(path: string): Promise<string[]>;
+    createDir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileMetadata>;
+    isDirectory(path: string): Promise<boolean>;
+    isFile(path: string): Promise<boolean>;
+}
+
+/**
+ * Containment boundary A — a policy decorator over ANY IFilesystem.
+ *
+ * The agent only ever sees an IFilesystem, so what it can touch is exactly what we
+ * mount. This jail:
+ *   - hides + blocks `deny` paths entirely (secrets: .env, keys, .git, …) — invisible
+ *     to read/stat/exists/readDir, unwritable;
+ *   - makes `readonly` paths readable but unwritable (the "constitution": pinned
+ *     grader/suite/criteria the self-evolve agent must never edit);
+ *   - optionally `confineTo` a set of subtrees (anything outside is denied);
+ *   - normalizes paths first, so `..` traversal (`/src/../.env`) is caught after resolution;
+ *   - reports every violation via `onViolation` (audit trail / circuit-breaker hook).
+ *
+ * Crucial limitation: this guards what the AGENT'S TOOLS touch. It does NOT contain
+ * code executed against the real disk at eval time (the grader imports agent-written
+ * code) — that is boundary B (a sandboxed subprocess). See mind/08-self-evolve.md.
+ */
+declare class JailedFilesystem implements IFilesystem {
+    private inner;
+    options: JailOptions;
+    private denyRe;
+    private roRe;
+    private confineRe?;
+    constructor(inner: IFilesystem, options?: Partial<JailOptions>);
+    private abs;
+    /** Throw if reading `path` is not permitted (denied or out of confinement). */
+    private guardRead;
+    /** Throw if writing/deleting `path` is not permitted (denied, readonly, or out of confinement). */
+    private guardWrite;
+    private violate;
+    /** Fire the audit hook without throwing (for boolean probes that must still return false). */
+    private note;
+    /** Is `abs` (already-resolved) visible? If not, fire the audit hook (op given) and return false. */
+    private visible;
+    readFile(path: string): Promise<string>;
+    /** Forward the optional binary-read capability (if the inner fs has it), jailed like readFile. */
+    readFileBytes(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    createDir(path: string): Promise<void>;
+    stat(path: string): Promise<FileMetadata>;
+    exists(path: string): Promise<boolean>;
+    isDirectory(path: string): Promise<boolean>;
+    isFile(path: string): Promise<boolean>;
+    /** List a directory, filtering out entries the policy hides. */
+    readDir(path: string): Promise<string[]>;
+    resolvePath(path: string, cwd?: string): string;
+    getCwd(): string;
+    /** Guard cwd too: the jail must never be able to "stand" on a denied/out-of-confine dir. */
+    setCwd(path: string): void;
+}
+/** Default denylist: secrets and VCS internals that must never be read or written.
+ *  Patterns are matched case-insensitively (so /.ENV is covered too). */
+declare const DEFAULT_DENY: string[];
+declare class JailOptions {
+    /** Globs that are invisible and unwritable (secrets). */
+    deny: string[];
+    /** Globs readable but not writable/deletable (the pinned constitution). */
+    readonly: string[];
+    /** If set, only paths matching these globs are accessible at all. */
+    confineTo?: string[];
+    /** Audit hook fired on every blocked operation (drives the circuit breaker). */
+    onViolation?: (v: {
+        op: string;
+        path: string;
+        rule: string;
+    }) => void;
+}
+
+declare class OverlayFilesystem implements IFilesystem {
+    private base;
+    private st;
+    private snapshots;
+    private seq;
+    constructor(base: IFilesystem);
+    resolvePath(path: string, cwd?: string): string;
+    getCwd(): string;
+    setCwd(path: string): void;
+    private abs;
+    private parent;
+    private name;
+    readFile(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    isFile(path: string): Promise<boolean>;
+    isDirectory(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileMetadata>;
+    /** Merge base entries (minus tombstones) with overlay-created children of `path`. */
+    readDir(path: string): Promise<string[]>;
+    writeFile(path: string, content: string): Promise<void>;
+    createDir(path: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    private clone;
+    /** Capture the current overlay; returns a token to `rollback(token)` to. */
+    snapshot(label?: string): string;
+    /** Discard all changes since the named snapshot (or the most recent if omitted). */
+    rollback(token?: string): void;
+    /** Paths changed vs the base since this overlay was created (added = not in base, modified = was). */
+    diff(): Promise<{
+        added: string[];
+        modified: string[];
+        deleted: string[];
+    }>;
+    /** Flush the overlay into the base (writes, mkdirs, deletes), then clear the overlay. */
+    commit(): Promise<void>;
+}
+/** `Checkpoint` tool — snapshot the VFS before a risky multi-step change. */
+declare const checkpointTool: AgentTool;
+/** `Rollback` tool — undo all VFS changes since a Checkpoint. */
+declare const rollbackTool: AgentTool;
+declare const checkpointTools: () => AgentTool[];
+
+interface Mount {
+    prefix: string;
+    fs: IFilesystem;
+}
+declare class MountFilesystem implements IFilesystem {
+    private root;
+    private mounts;
+    constructor(root: IFilesystem, mounts?: Mount[]);
+    resolvePath(path: string, cwd?: string): string;
+    getCwd(): string;
+    setCwd(path: string): void;
+    private abs;
+    /** Route an absolute VFS path to a backend + its path within that backend. */
+    private route;
+    /** Is `abs` strictly ABOVE a mount point (a synthesized dir the root may not have)? */
+    private isMountAncestor;
+    /** Immediate child segment names of `abs` that come from mounts (for readDir merge). */
+    private mountChildrenOf;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    createDir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    isDirectory(path: string): Promise<boolean>;
+    isFile(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileMetadata>;
+    readDir(path: string): Promise<string[]>;
+}
+
+/**
+ * Speculative parallel attempts — a primitive uniquely cheap on a SWAPPABLE VFS.
+ *
+ * Fork the workspace into N copy-on-write overlays of the same `base`, run an attempt in
+ * each (independently — writes stay in each overlay, the base is untouched), score them,
+ * then COMMIT the best overlay into the base and DISCARD the losers (they leave no trace).
+ * Use it to race several approaches/seeds for a flaky or multi-path task and keep only the
+ * winner — something agents on a real, non-forkable filesystem can't do without copying the
+ * whole tree. Pairs naturally with subagents (each attempt is a child Agent over its overlay).
+ *
+ * `score` returns a higher-is-better number, or null to disqualify (e.g. failed grading).
+ */
+interface Attempt<R> {
+    index: number;
+    fs: OverlayFilesystem;
+    result: R;
+    score: number | null;
+}
+declare function raceAttempts<R>(base: IFilesystem, n: number, run: (fs: IFilesystem, index: number) => Promise<R>, score: (a: {
+    fs: OverlayFilesystem;
+    result: R;
+    index: number;
+}) => Promise<number | null> | number | null): Promise<{
+    winner: Attempt<R> | null;
+    attempts: Attempt<R>[];
+}>;
+
+/**
+ * Tool synthesis — compile a NEW agent tool from a spec the model authored. The unbounded
+ * frontier of self-evolution: the agent invents its own capabilities.
+ *
+ * SAFETY (this is the load-bearing part). A synthesized tool's `code` is arbitrary JS that
+ * runs IN-PROCESS over the agent's filesystem, so before compiling we statically REJECT a
+ * denylist of escape vectors (process/require/import/eval/Function/constructor/__proto__/
+ * globalThis/Bun/fetch/network/timers/WebAssembly/infinite-loops/…). A compiled tool sees
+ * ONLY its `args` and `ctx` (whose fs is the JailedFilesystem — boundary A); combined with
+ * the Agent's timeout/tool-call kill-switches this is defensible. Residual risk remains for
+ * a determined denylist bypass, so synthesized tools are OPT-IN and should additionally be
+ * self-tested in the sandbox (boundary B) before being trusted in a live loop. See mind/08.
+ */
+interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: object;
+    /** body of `async (args, ctx) => { … return <string> }` — may use args + ctx.fs ONLY. */
+    code: string;
+}
+/** Static safety gate. Returns the matched escape vectors (empty = code is allowed). */
+declare function validateToolCode(code: string): {
+    ok: boolean;
+    violations: string[];
+};
+/**
+ * Compile a spec into an AgentTool — THROWS if the code fails the static safety gate.
+ * The body runs as `async (args, ctx) => { <code> }`; only `args` and `ctx` are in scope.
+ */
+declare function compileSynthesizedTool(spec: ToolSpec): AgentTool;
+
+/**
+ * Deterministic test/dev double for an ai.libx.js AIClient. Plays a scripted
+ * queue of ChatResponses (tool_calls then a final answer). Records each
+ * ChatOptions it saw so tests can assert tools were advertised and tool
+ * results were threaded back. No network, no API key.
+ */
+declare class FakeAIClient implements ChatLike {
+    seen: ChatOptions[];
+    private script;
+    constructor(script: ChatResponse[]);
+    chat(options: ChatOptions): Promise<ChatResponse>;
+}
+/** Build a tool_call block (arguments JSON-stringified, matching the wire format). */
+declare const toolCall: (id: string, name: string, args: object) => ToolCall;
+
+/**
+ * In-process scheduler — timers that fire prompts into the agent loop while the session is alive.
+ * Three trigger modes: one-off ({at}), interval ({everyMs}), cron ({cron}).
+ * The scheduler never calls `turn()` itself — it invokes an IoC `fire` callback with due jobs,
+ * keeping it testable and host-agnostic. Persistence is the host's responsibility (serialize jobs
+ * into the session and re-arm on resume).
+ *
+ * Survives --resume (host reloads); does NOT survive process exit (no daemon, no launchd).
+ */
+type TriggerOneOff = {
+    at: number;
+};
+type TriggerInterval = {
+    everyMs: number;
+};
+type TriggerCron = {
+    cron: string;
+};
+type Trigger = TriggerOneOff | TriggerInterval | TriggerCron;
+type ScheduledJobStatus = 'active' | 'done';
+interface ScheduledJob {
+    id: string;
+    prompt: string;
+    trigger: Trigger;
+    status: ScheduledJobStatus;
+    created: number;
+    lastRun?: number;
+    runs: number;
+    /** Optional label for display (e.g. footer, /schedule list). */
+    label?: string;
+}
+/** Serializable snapshot for session persistence (same shape — kept as an alias for clarity at call sites). */
+type ScheduledJobSnapshot = ScheduledJob;
+interface SchedulerOptions {
+    /** Called when a job is due. Must not throw — the scheduler logs errors and continues. */
+    fire: (job: ScheduledJob) => Promise<void> | void;
+    /** Monotonic clock override for testing (default: Date.now). */
+    now?: () => number;
+    /** Tick interval in ms (default: 15_000 — 15s). */
+    tickMs?: number;
+    /** If true, suppress the setInterval (for unit tests that call tick() manually). */
+    manual?: boolean;
+}
+interface CronFields {
+    minute: number[];
+    hour: number[];
+    dom: number[];
+    month: number[];
+    dow: number[];
+}
+declare function parseCron(expr: string): CronFields;
+declare function cronMatches(fields: CronFields, date: Date): boolean;
+/** Next occurrence of `cron` after `after` (epoch ms). Returns epoch ms, or null if >366 days out (guard). */
+declare function nextCronAfter(cron: string, after: number): number | null;
+declare class Scheduler {
+    private jobs;
+    private seq;
+    private timer;
+    private firing;
+    private readonly fire;
+    private readonly now;
+    private readonly tickMs;
+    constructor(opts: SchedulerOptions);
+    /** Start the tick timer. Idempotent. */
+    start(): void;
+    /** Stop the tick timer. Does not clear jobs. */
+    stop(): void;
+    /** Add a scheduled job. Returns the job id. */
+    add(opts: {
+        prompt: string;
+        trigger: Trigger;
+        label?: string;
+    }): string;
+    /** Cancel a job. Returns false if not found. */
+    cancel(id: string): boolean;
+    get(id: string): ScheduledJob | undefined;
+    list(): ScheduledJob[];
+    active(): ScheduledJob[];
+    /** Compute when a job next fires (epoch ms), or null if done/unknown. */
+    nextFire(job: ScheduledJob): number | null;
+    /** Check all active jobs and fire any that are due. Reentrant-safe. */
+    tick(): Promise<void>;
+    /** Export all jobs for session persistence. */
+    snapshot(): ScheduledJobSnapshot[];
+    /** Restore jobs from a snapshot (e.g. on --resume). Clears existing jobs first. */
+    restore(snapshots: ScheduledJobSnapshot[]): void;
+    /** Number of active jobs. */
+    get size(): number;
+    destroy(): void;
+}
+
+/** Narrow seam to an OS-level scheduler backend (jobs that survive quit/reboot). Node hosts wire
+ *  the CLI's `OsScheduler` (launchd/cron/at); absent => everything stays in-process. Edge-safe:
+ *  this module only sees the interface. */
+interface OsBackend {
+    sessionId: string;
+    cwd: string;
+    /** 'os' when the trigger should outlive the session (per hint/heuristic). */
+    route(trigger: Trigger, backendHint?: string): 'session' | 'os';
+    /** Register with the OS. Returns a mechanism description (e.g. 'launchd:…'). Throws on failure. */
+    schedule(spec: {
+        id: string;
+        prompt: string;
+        sessionId: string;
+        cwd: string;
+        trigger: Trigger;
+        label?: string;
+    }): string;
+    cancel(id: string): boolean;
+    list(): Array<{
+        id: string;
+        label?: string;
+        mechanism: string;
+        trigger: Trigger;
+    }>;
+}
+declare function makeScheduleTools(scheduler: Scheduler, os?: OsBackend): AgentTool[];
+
+/** Sandbox mode: an in-memory VFS — the real disk is never read or written. Edge/browser/test/dry-run. */
+declare function sandboxAgentOptions(opts?: Partial<AgentOptions>): Partial<AgentOptions>;
+/** Disk mode (the default): operate on the real filesystem, jailed to cwd (secrets hidden by DEFAULT_DENY).
+ *  Omitting `fs` lets the Agent lazily resolve the jailed disk — this preset just makes the intent explicit
+ *  (and is where you'd thread overrides). Pass an explicit `fs` to use a different backend. */
+declare function diskAgentOptions(opts?: Partial<AgentOptions>): Partial<AgentOptions>;
+/** Full mode: disk + a real `/bin/sh` tool (run installed binaries — git, bun, node, …) plus its
+ *  background-job companions. NODE-ONLY: the real-shell module is dynamic-imported so this file stays
+ *  edge-safe to import. `cwd` defaults to `process.cwd()`; secret env is scrubbed from spawned children. */
+declare function fullAgentOptions(opts?: Partial<AgentOptions> & {
+    cwd?: string;
+}): Promise<Partial<AgentOptions>>;
+
+/** List paths matching a glob, sorted — the structured alternative to `find`. */
+declare const globTool: AgentTool;
+/** Search file contents by regex, returning typed `path:line:text` hits with optional context. */
+declare const grepTool: AgentTool;
+/**
+ * Compact map of a VFS — code signatures and/or doc outlines. Edge-safe (pure IFilesystem walk).
+ * `mode`: "code" (default) = top-level signatures; "docs" = heading outlines; "all" = both.
+ */
+declare function repoIndex(fs: IFilesystem, glob?: string, mode?: 'code' | 'docs' | 'all', signal?: AbortSignal): Promise<string>;
+/** Compact map of the codebase or document workspace — orient in ONE call, not many. */
+declare const repoMapTool: AgentTool;
+/** Create or overwrite a file, creating parent directories as needed (mkdir -p). */
+declare const writeTool: AgentTool;
+/** Apply an ordered list of exact-substring edits to one file in a single call. */
+declare const multiEditTool: AgentTool;
+/**
+ * Cross-file batch edit — the multi-file refactor primitive. One call edits MANY files:
+ * each entry with an `old_string` replaces that exact, UNIQUE substring (read fresh + verified,
+ * so NO prior Read is needed — locate the sites with Grep, whose output is the text to match);
+ * each entry WITHOUT `old_string` writes `new_string` as the whole file (creates it + parent dirs).
+ * Validate-all-before-write → atomic across files. Collapses "Grep + N×(Read+Edit)" into "Grep + ApplyEdits".
+ */
+declare const applyEditsTool: AgentTool;
+/** mkdir -p over the VFS (idempotent, top-down). */
+declare function mkdirp(fs: IFilesystem, dir: string): Promise<void>;
+
+/** Strip HTML to readable text — dependency-free: drop script/style/comments, block tags → newlines, decode common entities. */
+declare function htmlToText(html: string): string;
+interface WebFetchOptions {
+    /** Override the global fetch (tests inject a mock; edge runtimes can supply their own). */
+    fetch?: typeof globalThis.fetch;
+    maxBytes?: number;
+    maxChars?: number;
+    timeoutMs?: number;
+    /** Allow fetching private/loopback/link-local hosts (default false — blocks basic SSRF). */
+    allowPrivateHosts?: boolean;
+}
+/** Build a WebFetch tool. */
+declare function makeWebFetchTool(options?: WebFetchOptions): AgentTool;
+interface WebSearchOptions {
+    fetch?: typeof globalThis.fetch;
+    /** Provider: 'auto' (default) uses Tavily if an API key is present, else keyless DuckDuckGo. */
+    provider?: 'auto' | 'tavily' | 'duckduckgo';
+    /** API key for Tavily (default: process.env.TAVILY_API_KEY). */
+    apiKey?: string;
+    /** Tavily endpoint override. */
+    endpoint?: string;
+    maxResults?: number;
+    timeoutMs?: number;
+}
+interface SearchHit {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** Decode a DuckDuckGo HTML result href: results are `//duckduckgo.com/l/?uddg=<encoded-target>` redirects. */
+declare function decodeDdgUrl(href: string): string;
+/** Parse DuckDuckGo's HTML results page into hits (title/url/snippet) — dependency-free, zips anchors to snippets in order. */
+declare function parseDdgHtml(html: string, max: number): SearchHit[];
+/**
+ * Build a WebSearch tool. Keyless by default (DuckDuckGo HTML) so it works in any deployment with
+ * no setup; auto-upgrades to Tavily (better, agent-oriented results) when TAVILY_API_KEY is present.
+ */
+declare function makeWebSearchTool(options?: WebSearchOptions): AgentTool;
+/** Default instances (registered in the tool registry; opt-in by name). */
+declare const webFetchTool: AgentTool;
+declare const webSearchTool: AgentTool;
+
+/**
+ * Scratch — keep large tool/subagent outputs OUT of the main context, but queryable AS FILES.
+ *
+ * Pattern: many-tool / many-subagent engines bloat context with raw outputs (search results, big
+ * file reads, subagent reports) that are mostly noise once a gist is taken. Here, a tool wrapped with
+ * `Scratch.capture` writes any oversized result to an ephemeral scratch filesystem (a real VFS) and
+ * returns a compact stub (path + preview) to context. To recover a buried detail later you do NOT
+ * re-bloat context — you peek with the FILE tools already on hand:
+ *   • Grep/Glob/Read over the scratch dir — returns matching lines, not the blob (a free, light peek).
+ *   • Ask({question, over?}) — a CHEAP child agent over the scratch FS that greps/reads and returns
+ *     just the answer; its reasoning tokens never touch the caller's context.
+ * Two-tier division of labour: cheap RETRIEVE/EXTRACT, strong caller SYNTHESIZE.
+ *
+ * The scratch FS is injected (IoC): pass a MemFilesystem for ephemeral, or a disk-backed one under the
+ * session dir to persist across resume (CC's lesson: the filesystem is the durable store). Segregated
+ * module — zero Agent-core changes.
+ */
+
+/** Default scratch dir (a path in the injected scratch FS). */
+declare const SCRATCH_DIR = "/scratch";
+interface ScratchOptions {
+    /** Min result length (chars) to capture; smaller results pass through untouched. Default 1500. */
+    threshold?: number;
+    /** Dir within the scratch FS to write captures. Default SCRATCH_DIR. */
+    dir?: string;
+    /** Chars of the captured output to preview in the stub. Default 320. */
+    previewChars?: number;
+}
+/**
+ * Owns an (injected) scratch filesystem + a capture counter. `capture(tool)` wraps a tool so its
+ * oversized string results spill to a scratch file and are replaced in context with a stub.
+ */
+declare class Scratch {
+    fs: IFilesystem;
+    options: Required<ScratchOptions>;
+    private seq;
+    private dirReady?;
+    constructor(fs: IFilesystem, options?: ScratchOptions);
+    /** Number of captures so far. */
+    get count(): number;
+    /** Wrap a tool: oversized STRING results spill to a scratch file; everything else passes through. */
+    capture(tool: AgentTool): AgentTool;
+    /** Wrap many tools at once. */
+    captureAll(tools: AgentTool[]): AgentTool[];
+    /**
+     * Spill an oversized tool result to a scratch file and return PAGE 1 + a recoverable, paginated stub.
+     * Drop-in for `Agent.capToolResult`: the agent sees usable content immediately and knows how to get
+     * the rest (refine the query, Read the file in pages with offset/limit, or Ask to extract specifics).
+     * Lossless — unlike a plain crop, the full output stays available on the scratch FS.
+     */
+    spill(full: string, info: {
+        tool: string;
+        args: any;
+    }, pageBytes?: number): Promise<string>;
+}
+interface AskOptions {
+    /** The scratch filesystem to peek into (dedicated VFS holding only scratch files). */
+    fs: IFilesystem;
+    ai: ChatLike;
+    /** Model for the peek — intentionally a CHEAP model; the caller synthesizes. */
+    model: string;
+    /** Step budget for the peek child (default 6). */
+    maxSteps?: number;
+    /** Scratch dir to search when `over` is omitted. Default SCRATCH_DIR. */
+    dir?: string;
+}
+/**
+ * `Ask` — peek into the scratch FS to answer a question WITHOUT loading raw data into the caller's
+ * context. Spawns a cheap child agent (Read/Grep/Glob over scratch) that greps/reads and returns just
+ * the answer. Pass `over` (a path) for a targeted peek, or omit to grep-discover.
+ */
+declare function makeAskTool(o: AskOptions): AgentTool;
+
+/**
+ * `AskUserQuestion` tool — lets the model pose a structured choice to a human.
+ * Delegates to `ctx.host.ask`. Registered only when a HostBridge is provided
+ * (autonomous runs don't see it), so it never dead-ends a headless agent.
+ */
+declare const askUserQuestionTool: AgentTool;
+/** Deterministic HostBridge for tests/dev: scripts answers + records what was asked. */
+declare class ScriptedHostBridge implements HostBridge {
+    private answers;
+    private confirmDefault;
+    asked: UserQuestion[];
+    confirms: string[];
+    events: Array<{
+        kind: string;
+        message: string;
+        data?: unknown;
+    }>;
+    constructor(answers?: string[], confirmDefault?: boolean);
+    ask(q: UserQuestion): Promise<string>;
+    confirm(prompt: string): Promise<boolean>;
+    notify(event: {
+        kind: string;
+        message: string;
+        data?: unknown;
+    }): void;
+}
+/** Node CLI HostBridge: prompts on stdin. (node-only host adapter; not edge-safe by design.) */
+declare class ConsoleHostBridge implements HostBridge {
+    ask(q: UserQuestion): Promise<string>;
+    confirm(prompt: string): Promise<boolean>;
+    notify(event: {
+        kind: string;
+        message: string;
+    }): void;
+}
+
+interface CommandInfo {
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * Resolves a name in the *other* half of the merged slash namespace (CC parity: `/x` is one
+ * namespace whether `x` is a `commands/x.md` or a `skills/x/SKILL.md`). On a miss in its own
+ * registry, a tool calls this to find the sibling and learn how to expand it. Injected by the
+ * caller (Agent.prepare) so commands.ts and skills.ts stay mutually decoupled (no circular import).
+ */
+type SiblingResolver = (name: string) => Promise<{
+    path: string;
+    stripFrontmatter: boolean;
+} | undefined>;
+/**
+ * Expand a command template's argument placeholders:
+ *  - `$ARGUMENTS` → all args (every occurrence)
+ *  - `$1`…`$9`    → positional args (whitespace-split; missing → empty)
+ * If the body has neither placeholder, `args` is appended as a trailing block (back-compat).
+ */
+declare function expandTemplate(body: string, args: string): string;
+/**
+ * Read a slash entry's file and return its expanded text: arg placeholders filled, then `@file`
+ * refs embedded. `stripFrontmatter` drops the YAML head (commands feed only their body); skills
+ * feed the whole SKILL.md (frontmatter is part of the instructions). Shared by commands + skills
+ * so both halves of the merged namespace expand identically (CC parity).
+ */
+declare function expandEntry(fs: IFilesystem, path: string, args: string, opts?: {
+    stripFrontmatter?: boolean;
+}): Promise<string>;
+/** Read a command file and return its expanded body: arg placeholders filled, then `@file` refs embedded. */
+declare function expandCommand(fs: IFilesystem, cmd: CommandInfo, args: string): Promise<string>;
+/**
+ * Discover slash commands under `dir` (each `<dir>/<name>.md`) and produce:
+ *  - `catalog`: a names+descriptions block for the system prompt,
+ *  - `tool`: a `SlashCommand` tool that returns a command's expanded template body.
+ *
+ * Commands are reusable prompt templates (like Claude Code slash commands) — just
+ * VFS files. The template body is returned (user args appended, and `$ARGUMENTS`
+ * substituted if present) so the model can act on it. Mirrors loadSkills.
+ */
+/** Scan `dir`(s) for `<dir>/<name>.md` command templates (first dir wins on duplicate names). */
+declare function scanCommands(fs: IFilesystem, dir: string | string[]): Promise<CommandInfo[]>;
+declare function loadCommands(fs: IFilesystem, dir: string | string[], opts?: {
+    relevanceHint?: string;
+    max?: number;
+    sibling?: SiblingResolver;
+}): Promise<{
+    commands: CommandInfo[];
+    catalog: string;
+    tool?: AgentTool;
+}>;
+
+interface SkillInfo {
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * Discover skills under `dir` (each `<dir>/<id>/SKILL.md`) and produce:
+ *  - `catalog`: a names+descriptions block for the system prompt,
+ *  - `tool`: a `Skill` tool that returns a skill's full SKILL.md (progressive disclosure).
+ *
+ * Skills are just VFS files — the Read tool already gives progressive disclosure; this
+ * adds the catalog + a convenience tool. (Executable skills can be `bash`-exec'd: wcli
+ * runs JS files from the VFS as commands.)
+ */
+/** Scan `dir`(s) for `<dir>/<id>/SKILL.md` entries (first dir wins on duplicate ids). */
+declare function scanSkills(fs: IFilesystem, dir: string | string[]): Promise<SkillInfo[]>;
+declare function loadSkills(fs: IFilesystem, dir: string | string[], opts?: {
+    relevanceHint?: string;
+    max?: number;
+    sibling?: SiblingResolver;
+}): Promise<{
+    skills: SkillInfo[];
+    catalog: string;
+    tool?: AgentTool;
+}>;
+
+/**
+ * Lexical relevance — no deps, deterministic, edge-safe. Ranks catalog entries (skills,
+ * commands, memories, docs) by a task hint so a LARGE catalog doesn't dump every entry into
+ * the prompt. TF-IDF weighted: rare terms in the corpus score higher than common ones.
+ */
+/** Lowercased alphanumeric tokens of length ≥ 3, minus a few stopwords. */
+declare function tokenize(s: string): Set<string>;
+/** Build IDF weights from a corpus of texts. Rare terms get higher weight. */
+declare function idfWeights(corpus: string[]): Map<string, number>;
+/** TF-IDF weighted relevance score. Without IDF, falls back to flat token overlap (backward-compatible). */
+declare function relevanceScore(text: string, queryTokens: Set<string>, idf?: Map<string, number>): number;
+/**
+ * Split `items` into the `k` most relevant to `query` (by TF-IDF overlap with `text(item)`)
+ * and the rest, preserving each item's original order within its group. Returns everything in
+ * `kept` (empty `rest`) when `items.length <= k` or `query` is blank — so it's a no-op for
+ * small lists. When `corpus` is provided, builds IDF weights for better ranking.
+ */
+declare function topByRelevance<T>(items: T[], query: string, text: (x: T) => string, k: number, corpus?: string[]): {
+    kept: T[];
+    rest: T[];
+};
+
+/** Behavioral guidance injected alongside the memory index — adapted from CC's battle-tuned prose, for our tool-based workflow. */
+declare const MEMORY_PROMPT: string;
+/** Voice-specific memory guidance — shorter, spoken-interaction tuned. */
+declare const VOICE_MEMORY_PROMPT: string;
+/**
+ * Load memory for injection at run start (the recall step), with progressive disclosure:
+ *  - `index`: the compact `<dir>/MEMORY.md` index, injected into the system prompt — cheap,
+ *    always-hot. Each line points at a fact file the agent can pull on demand.
+ *  - `tools`: `Recall` (load one fact body on demand — keeps facts COLD until needed) and
+ *    `Remember` (persist a durable fact + index pointer mid-run — the WRITE half that closes
+ *    the learning loop: what the agent learns now steers future sessions).
+ *
+ * Persistence is the BACKEND's job, for free: NodeDiskFilesystem → disk,
+ * IndexedDbFilesystem → browser, (planned) BodDbFilesystem → database. The same
+ * memory mechanism therefore works in node, a browser tab, or on edge.
+ */
+interface LoadMemoryOpts {
+    relevanceHint?: string;
+    max?: number;
+    /** Max Remember calls per session (default 25). Prevents runaway memory writes. */
+    maxWritesPerSession?: number;
+    /** Called after each successful memory write (auditing, UI indicators). */
+    onMemorySaved?: (slug: string, type?: string) => void;
+    /** User-scope dir for global memories (type=user/feedback). If set, Remember routes by type:
+     *  user/feedback → userDir (global, survives across projects), project/reference → writeDir. */
+    userDir?: string;
+}
+declare function loadMemory(fs: IFilesystem, dir: string | string[], opts?: LoadMemoryOpts): Promise<{
+    index: string;
+    tools: AgentTool[];
+}>;
+/** Slugify free text into a safe kebab filename stem (no separators, bounded). */
+declare function slugify(s: string, fallback?: string): string;
+/**
+ * Persist a durable fact: write `<dir>/<slug>.md` and ensure a one-line pointer exists in
+ * `<dir>/MEMORY.md` (created if missing). Idempotent on the index (won't duplicate a pointer).
+ * This is the shared write path behind the `Remember` tool and automatic lesson capture.
+ */
+declare function writeFact(fs: IFilesystem, dir: string, slug: string, body: string, opts?: {
+    type?: string;
+    description?: string;
+}): Promise<void>;
+
+/**
+ * Automatic mistake → lesson → steer loop. Closes the within-run learning gap: the agent
+ * reacting to an error string is transient, but a RECURRING failure is a signal worth keeping.
+ * This hook watches tool results for known failure patterns; once the SAME pattern recurs
+ * `minRepeats` times in a run, it persists a corrective lesson to memory (deduped) — so the
+ * NEXT session's `loadMemory` injects it as steering. Deterministic, edge-safe, no LLM call.
+ *
+ * Writes immediately on crossing the threshold (not on a clean stop), so a loop/budget kill —
+ * exactly the runs that wasted effort — still leaves a lesson behind.
+ */
+interface LessonOptions {
+    fs: IFilesystem;
+    /** Memory dir to persist lessons into (same dir loadMemory reads). */
+    dir: string;
+    /** How many times a pattern must recur before it's worth remembering. */
+    minRepeats: number;
+}
+declare class LessonOptionsDefaults implements Partial<LessonOptions> {
+    minRepeats: number;
+}
+/**
+ * Build a Hooks object that auto-captures recurring failures as memory lessons.
+ * Compose it with the host's own hooks via `composeHooks`.
+ */
+declare function lessonCapture(options: LessonOptions): Hooks;
+
+/**
+ * One-shot LLM reflection on a finished run. The deterministic `lessonCapture` hook only
+ * knows OUR pre-mapped failure patterns; reflection catches NOVEL mistakes — it reads a digest
+ * of what the run actually did and, if there's a durable lesson, persists it to memory so the
+ * next session is steered. Costs exactly ONE model call, so it's meant for runs that went badly
+ * (loop / budget / max_steps), not every run. Opt-in. Returns the slug written, or null.
+ */
+interface ReflectOptions {
+    ai: ChatLike;
+    model: string;
+    /** Filesystem + memory dir to persist the lesson into (same dir loadMemory reads). */
+    fs: IFilesystem;
+    dir: string;
+    /** The finished run to reflect on. */
+    result: RunResult;
+    /** Bound the reflection prompt (chars of run digest). */
+    maxDigestChars?: number;
+}
+declare function reflectOnRun(o: ReflectOptions): Promise<string | null>;
+
+/**
+ * Walk the VFS directory tree from `/` down, collecting instruction files
+ * (AGENT.md, AGENTS.md, CLAUDE.md, .claude/<name>) at each level.
+ * Merges all found files general-first → specific-last (mirrors Claude Code's
+ * hierarchical CLAUDE.md discovery). First matching filename per directory wins
+ * (no duplicates from the same level). Edge-portable: works over any IFilesystem.
+ */
+declare function loadInstructions(fs: IFilesystem, names?: string[]): Promise<string>;
+
+/**
+ * DuplexAgent — voice-optimized three-tier conversational engine, composed on top of `Agent`.
+ *
+ * Three cognitive tiers (like a human brain):
+ *   REFLEX — fast voice agent (streams instant replies, owns THE transcript, the only voice the
+ *            user hears). Handles simple questions, routes complex work to Act or Think.
+ *   ACT    — standard worker (Sonnet-class). Full tools, file access, shell. The hands.
+ *   THINK  — premium reasoning (Opus-class). Deep analysis, architecture, hard problems. The brain.
+ *
+ * Workers are spawned per escalation via `Act`/`Think` tools. Results are pushed back as
+ * `[task <id> completed] …` events and re-voiced by the reflex — push, not poll.
+ *
+ * Host events (via the open HostEvent union): the voice agent's standard `text_delta` stream,
+ * plus `task_started` / `task_progress` / `task_done` / `task_error` / `task_cancelled`.
+ */
+
+type DuplexTaskStatus = 'running' | 'done' | 'error' | 'cancelled';
+interface TaskRecord {
+    id: string;
+    label: string;
+    status: DuplexTaskStatus;
+    controller: AbortController;
+    /** Settles when the worker finished AND its completion was processed. Never rejects. */
+    promise: Promise<void>;
+    /** Rolling activity tail (tool calls + last-result previews, capped) — feeds task inspection UIs. */
+    tail: string[];
+    /** Final report text (or error message) once the task settled. */
+    result?: string;
+}
+type WorkerTier = 'act' | 'think';
+declare class DuplexAgentOptions {
+    /** Any ai.libx.js AIClient — shared by all tiers (routed by model). */
+    ai: ChatLike;
+    /** The WORKER's filesystem (act + think). If omitted the worker keeps Agent's jailed-disk-at-cwd default. */
+    fs?: IFilesystem;
+    reflexModel: string;
+    actModel: string;
+    /** Premium reasoning model. Set to `false` to disable the Think tier entirely. */
+    thinkModel: string | false;
+    /** Per-worker providerOptions, derived from the worker's actual model at spawn time (IoC — keeps duplex
+     *  provider-agnostic). Workers override the reflex/main model, so provider-specific options (e.g. cursor's
+     *  cwd/cursorSession) must be recomputed for the worker's model, never inherited from the main template —
+     *  leaking cursor options to an anthropic worker is a hard 400. Returns undefined → no providerOptions. */
+    providerOptionsFor?: (model: string) => Record<string, unknown> | undefined;
+    /** Escape hatches merged over the derived per-agent options. */
+    reflexOptions?: Partial<AgentOptions>;
+    actOptions?: Partial<AgentOptions>;
+    thinkOptions?: Partial<AgentOptions>;
+    /** Fresh-context check on each successful Act task: a NEW agent (no self-confirmation bias) re-reads
+     *  the file state against the brief and fixes any gap before the result is re-voiced. Bounded to one
+     *  pass; ~2x Act cost so default OFF. The self-verify FOOTER (same context) was measured ineffective —
+     *  this is the structural fix (see mind/10). Think tasks are pure reasoning, never checked. */
+    verifyActTasks: boolean;
+    /** Receives the voice text_delta stream + task lifecycle events. */
+    host?: HostBridge;
+    /** How many recent transcript messages are rendered into a worker's brief. */
+    excerptTurns: number;
+    /** Voice register: 'neutral' = clean spoken style; 'conversational' = human-like — fillers,
+     *  backchannels, impulsive first reactions before content (mimics real duplex conversation). */
+    voiceStyle: 'neutral' | 'conversational';
+    /** Awaited BEFORE a worker spawns — open a per-task checkpoint frame, audit, etc.
+     *  (post-spawn would race the worker's first edits). */
+    onTaskStart?: (id: string, label: string) => void | Promise<void>;
+    /** Re-voice throttled worker progress asides ('[task t1 progress] …') so long tasks aren't dead
+     *  air. Off by default — each update costs a voice turn (LLM call + speech). */
+    progressUpdates: boolean;
+    /** Min ms between progress re-voices per task. */
+    progressIntervalMs: number;
+    /** Relay worker questions (AskUserQuestion + permission asks via parkQuestion) through the VOICE:
+     *  the question re-voices as '[task <id> asks] …', the user answers conversationally, and the
+     *  voice model resolves it with the AnswerTask tool. Off → host.ask passthrough (text menus). */
+    askRelay: boolean;
+    /** Parked questions auto-resolve empty after this long (callers map '' to deny/best-judgment). */
+    askTimeoutMs: number;
+    /** Max retained task records: oldest SETTLED tasks (and their activity tails) are evicted past this,
+     *  bounding memory over a long-lived session. Running tasks are never evicted. */
+    maxTaskRecords: number;
+    /** Host overrides for QuickLook lookups (keyed by `what`). The engine's defaults go through the
+     *  (possibly jailed) fs — e.g. `.git/**` is deny-listed, so the CLI supplies 'branch' itself. */
+    quickLook?: Record<string, (path?: string) => string | Promise<string>>;
+    /** Memory directory/directories on the WORKER fs. If set, the voice agent gets Remember + Recall
+     *  tools directly (no delegation needed) and implicit capture guidance. */
+    memoryDir?: string | string[];
+    /** User-scope memory dir for global facts (type=user/feedback). Forwarded to Remember's routing. */
+    memoryUserDir?: string;
+}
+declare const VOICE_SYSTEM_PROMPT: string;
+/**
+ * The duplex orchestrator. `send()` enqueues a user turn on the reflex agent; `Act`/`Think`
+ * spawn detached workers whose completions enqueue re-voice turns. A promise-chain
+ * mutex serializes all voice turns so streams never interleave, and completions that
+ * pile up while the voice is busy are coalesced into a single re-voice turn.
+ */
+declare class DuplexAgent {
+    options: DuplexAgentOptions;
+    readonly voice: Agent;
+    readonly tasks: Map<string, TaskRecord>;
+    private queue;
+    private seq;
+    private pendingEvents;
+    private flushQueued;
+    /** Per-voice-turn guards (reset by resetTurn at each turn's start). The reflex is a weak model:
+     *  left unguarded it polls TaskStatus after a dispatch and/or dispatches silently (dead air).
+     *  Like CC's Task tool, a dispatch is "said my piece, now wait for the push" — these enforce that. */
+    private turnDispatched;
+    private turnBriefs;
+    private spokeThisTurn;
+    private nudging;
+    private reflexBuf;
+    private reflexForwarded;
+    private fabricationCut;
+    /** Parked worker questions awaiting a (voice-relayed) user answer, keyed by ask id. */
+    readonly pendingAsks: Map<string, {
+        question: string;
+        resolve: (answer: string) => void;
+    }>;
+    /** Lazily resolved memory tools (async loadMemory runs in initMemory). */
+    private memoryReady;
+    constructor(options?: Partial<DuplexAgentOptions>);
+    /** Resolve memory tools + inject index into voice system prompt (once). */
+    private initMemory;
+    /** Clear the per-turn guards. Called at the head of every voice turn (user send + re-voice flush). */
+    private resetTurn;
+    /** preToolUse guard on the reflex: once it has dispatched this turn, a dispatch is "said my piece,
+     *  now wait for the push" (CC's Task model). Block the temptations — TaskStatus polling and identical
+     *  re-dispatch — so the only remaining move is to voice a short ack and end. A genuinely NEW Act is
+     *  still allowed (parallel independent work). During a re-ack pass, block every tool. */
+    private dispatchGuard;
+    /** True when the just-finished turn dispatched a task but voiced nothing — dead air to repair.
+     *  Requires a host: without one there's no stream to detect speech on (and no one to speak to). */
+    private get silentDispatch();
+    /** A dispatch with no spoken text is dead air. Re-prompt the reflex ONCE so the LLM itself voices a
+     *  short ack (no template). If it STILL says nothing, fall back to a minimal line so silence never ships. */
+    private ackIfSilent;
+    /** One user turn: the voice agent streams the reply (and may Act/Think). Serialized with re-voice turns. */
+    send(content: MessageContent): Promise<RunResult>;
+    /** Cancel a running background task — shared by the CancelTask tool and the CLI /tasks picker. */
+    cancelTask(id: string): string;
+    /** Resolve when all queued voice turns AND all in-flight worker tasks have settled (tests, graceful shutdown). */
+    idle(): Promise<void>;
+    /** Promise-chain mutex: turns run strictly one at a time; a failed turn doesn't poison the chain. */
+    private enqueue;
+    private notify;
+    /** Queue a `[task …]` event for re-voicing. Events arriving while the voice is busy coalesce into ONE turn. */
+    private queueRevoice;
+    /** The worker's brief: the Act/Think args + a STATIC text snapshot of the recent conversation.
+     *  Act briefs get a self-verify footer — the worker's report is trusted without review, so it
+     *  must check its own work before reporting (nearly free under prompt caching; measured honest:
+     *  it does NOT fix one-shot logic bugs — see mind/10). Think tasks are pure reasoning — no footer. */
+    private buildBrief;
+    /** Spawn a detached worker for task `id`; its settlement notifies + enqueues the re-voice turn. */
+    private spawnWorker;
+    /** Fresh-context check of a successful Act task: a NEW agent (same model/fs/tools, but NO shared
+     *  conversation context) re-reads the file state against the brief and fixes any gap. The fix lands
+     *  on the shared fs automatically (workers write fs directly, no overlay), so grading sees the
+     *  corrected state. Bounded to ONE pass. Off unless `verifyActTasks`; never runs for think/failed/
+     *  cancelled tasks. Usage is merged so /cost reflects the real (worker + checker) spend. */
+    private maybeVerify;
+    /** Throttled per-task progress: worker tool calls → at most one progress re-voice per interval.
+     *  Two sources, one throttle: completed steps (post) and a heartbeat for a SINGLE long tool call
+     *  (pre records the in-flight call; a self-cleaning timer narrates "still inside Bash — 70s").
+     *  Completion supersedes: nothing is emitted once the task has settled. */
+    private progressReporter;
+    /** Park a question under `askId` (a task id, or any unique key for permission asks): re-voices
+     *  '[task <id> asks] …' and resolves with the user's answer via AnswerTask — or '' on timeout/
+     *  task settle (callers map '' to deny / best-judgment). Workers never block forever. */
+    parkQuestion(askId: string, question: string): Promise<string>;
+    /** Resolve any question a settling/cancelled task left parked (its answer can no longer matter). */
+    private dropAsk;
+    private onWorkerSettled;
+    private onWorkerFailed;
+    private failTask;
+    /** Live-switch the think tier: `false` disables (removes the Think tool from the voice agent),
+     *  a model id enables (adds the tool if missing). The system-prompt THINK_SLOT text is frozen at
+     *  construction — the tool's own description carries the routing guidance, so a live enable works;
+     *  dispatch()'s think→act fallback covers any straggler calls after a live disable. */
+    setThinkModel(model: string | false): void;
+    /** User/programmatic spawn: the CLI's /act and /think commands. Returns the task id. */
+    dispatch(brief: string, tier?: WorkerTier, label?: string): Promise<string>;
+    private actTool;
+    private thinkTool;
+    private taskStatusTool;
+    /** Sub-100ms read-only lookups the voice may do itself — everything else stays Act-only.
+     *  fs-only (no shell; the engine is VFS-abstracted): time, git branch (.git/HEAD read), ls, file
+     *  head. Output is hard-capped so a lookup can never bloat the skinny voice context. */
+    private quickLookTool;
+    private answerTaskTool;
+    private holdTool;
+    private cancelTaskTool;
+}
+
+/**
+ * Typed subagents — named child-agent definitions from `<dir>/<name>.md`, each with a
+ * description, an optional model + tool allowlist (frontmatter), and a system prompt (the
+ * body). The `Task` tool's `agentType` selects one, so a delegated sub-task runs with its
+ * own persona, model, and scoped tools — the Claude-Code `.claude/agents` model.
+ * VFS-backed (edge-portable), mirroring loadSkills / loadCommands.
+ */
+interface AgentDef {
+    name: string;
+    description: string;
+    /** The .md body — used as the child's system prompt (overrides the default). */
+    systemPrompt?: string;
+    /** Optional model override for this subagent type. */
+    model?: string;
+    /** Optional tool-name allowlist (scopes the child's tools). */
+    tools?: string[];
+}
+/** Discover subagent definitions under `dir` and a catalog block for the system prompt. */
+declare function loadAgents(fs: IFilesystem, dir: string): Promise<{
+    agents: AgentDef[];
+    catalog: string;
+}>;
+
+interface TaskToolOptions {
+    /** The same ai.libx.js client the parent uses — the child shares it. */
+    ai: ChatLike;
+    model: string;
+    /** The filesystem the child operates over (jail/scope it before passing, if desired). */
+    fs: IFilesystem;
+    /** Step budget for the child run (independent of the parent's). */
+    maxSteps?: number;
+    /** Recursion depth of the child this tool would spawn (0 = first level). */
+    depth?: number;
+    /** Hard ceiling on nesting — beyond this the tool refuses to spawn. */
+    maxDepth?: number;
+    /** Named subagent types selectable via the `agentType` param (persona + model + scoped tools). */
+    agents?: AgentDef[];
+    /** Max children running concurrently in a `TaskBatch` (default 4). */
+    maxParallel?: number;
+    /** Parent hooks — `onSubagentStop` fires with each child's summary when it finishes. */
+    hooks?: Hooks;
+}
+/**
+ * `Task` tool — spawn a CHILD agent over the same VFS with its own step budget,
+ * returning only its final summary to the parent. Use to fan out a self-contained
+ * sub-task (search, refactor a subtree) without polluting the parent's context.
+ * @returns the child's final text, or an error string if the depth limit is reached.
+ */
+declare function makeTaskTool(opts: TaskToolOptions): AgentTool;
+/**
+ * `TaskBatch` tool — fan out several self-contained sub-tasks to child agents that run
+ * **concurrently** (bounded pool), returning all their summaries together. Each child runs over its
+ * OWN `OverlayFilesystem` (write-isolated from siblings), and successful children's edits are
+ * committed **in array order** afterward — so concurrent writes resolve deterministically
+ * (last index wins) instead of racing. Use to parallelize independent work (review N files, search M
+ * subtrees, scoped refactors). For a single sub-task, use `Task`.
+ */
+declare function makeTaskBatchTool(opts: TaskToolOptions): AgentTool;
+
+/** Component-scoped logger (libx.js). debug/verbose gated via DEBUG env/localStorage. */
+declare const forComponent: (name: string) => libx_js_src_modules_log.ComponentLogger;
+
+/**
+ * Portable voice I/O contracts — zero platform imports. The engine, STT and TTS clients in this
+ * directory run anywhere with a `WebSocket` global (Bun, Node, browser); platform backends
+ * (mic capture, audio playback) plug in through these seams.
+ */
+type VoiceState = 'idle' | 'listening' | 'thinking' | 'speaking';
+/** STT input sample format — sources MUST deliver this (downsample/convert in the adapter). */
+declare const STT_SAMPLE_RATE = 16000;
+/** Playback format the TTS requests and sinks must play. */
+declare const TTS_SAMPLE_RATE = 44100;
+/** A microphone (or any PCM) source. Emits s16le mono 16kHz chunks.
+ *  Node: mic-aec/ffmpeg child process. Web: getUserMedia({ echoCancellation: true }) + worklet. */
+interface AudioSource {
+    /** `aec` = the source is echo-cancelled (assistant's own TTS never reaches the chunks) —
+     *  selects the engine's trivial barge-in path vs the heuristic echo tier. */
+    readonly aec: boolean;
+    start(onChunk: (pcm: Uint8Array) => void): void | Promise<void>;
+    stop(): void;
+}
+/** An audio playback sink for s16le mono 44.1kHz PCM.
+ *  Node: per-turn ffplay. Web: AudioContext/worklet ring buffer. */
+interface AudioSink {
+    /** start a new spoken turn (may recycle or recreate the underlying player) */
+    markTurn(): void;
+    write(pcm: Uint8Array): void;
+    /** estimated ms until queued audio finishes playing */
+    drainMs(): number;
+    /** ms of audio actually played this turn */
+    playedMs(): number;
+    /** stop playback NOW (barge-in primitive) */
+    kill(): void;
+    /** optional exact-sample pause/resume — enables the overlap trail-off tier (web: AudioContext
+     *  suspend/resume; CLI AEC helper: control frames). Sinks without it degrade to interrupt-only
+     *  turn-taking. Nothing is lost across a pause; playedMs/drainMs must exclude paused time. */
+    pause?(): void;
+    resume?(): void;
+}
+/** Static key (server/CLI) or an async getter (browser: fetch a short-lived token from YOUR
+ *  backend). Getters are invoked on EVERY (re)connect — temp tokens expire, so a reconnect
+ *  must re-mint, never reuse the boot-time token. */
+type AuthProvider = string | (() => string | Promise<string>);
+declare function resolveAuth(auth: AuthProvider): Promise<string>;
+
+/** Structural contracts (satisfied by SonioxSTT/CartesiaTTS or test fakes). */
+interface SttLike {
+    usingAec: boolean;
+    onPartial: (text: string) => void;
+    onUtterance: (text: string, endpointAt: number) => void;
+    onLevel: (rms: number) => void;
+    start(): Promise<void> | void;
+    reset(): void;
+    stop(): void;
+}
+interface TtsLike {
+    onAudio: (chunk: Uint8Array) => void;
+    onDone: () => void;
+    connect(): Promise<void> | void;
+    newContext(): string;
+    speak(text: string, cont: boolean): void;
+    end(): void;
+    cancel(): void;
+    close(): void;
+}
+declare class VoiceEngineOptions {
+    stt: SttLike;
+    tts: TtsLike;
+    player: AudioSink;
+    /** a final utterance arrived (endpoint) — host dispatches it as a turn */
+    onUtterance: (text: string) => void;
+    /** live partial transcript while listening (host renders the 🎤 line) */
+    onPartial: (text: string) => void;
+    onState: (s: VoiceState) => void;
+    /** user spoke/acted over playback — host aborts the in-flight turn (called AFTER audio is killed).
+     *  phase: 'speaking' = cut mid-speech (real interruption); 'drain' = in the final audio tail
+     *  (normal turn-taking — hosts shouldn't alarm). */
+    onBargeIn: (phase: 'speaking' | 'drain') => void;
+    /** spoken micro-ack on utterance endpoint (masks LLM TTFT); '' disables */
+    ackPhrase: string;
+    /** Endpoint merge window (ms): hold an endpointed utterance briefly — if speech resumes (spelled
+     *  letters, mid-thought pauses), the next utterance MERGES instead of dispatching a truncated one
+     *  ("E-L-Y." / "A."). Costs this much latency per turn; 0 disables. */
+    utteranceMergeMs: number;
+    /** Extended merge window (ms) for utterances that look incomplete (trailing conjunction/filler).
+     *  Gives the user time to finish their thought without triggering a model call. */
+    incompleteMergeMs: number;
+    /** Filler phrase spoken when holding for an incomplete utterance ('' disables). */
+    holdFiller: string;
+    /** Called when the engine holds an incomplete utterance (host can render a visual cue). */
+    onHold: () => void;
+    /** heuristic (non-AEC) energy barge-in tuning */
+    bargeRmsMult: number;
+    bargeRmsFloor: number;
+    /** Overlap turn-taking (AEC tier, needs player.pause/resume) — human phone-call model, driven by
+     *  the STT ITSELF (a trained speech classifier) instead of energy thresholds (energy could not
+     *  separate residue bursts from speech in every room — hiccup whack-a-mole): partial text while
+     *  speaking → PAUSE (exact-sample hold); partial grows into dominant-novel ≥2 words → cede
+     *  (interrupt; the LLM re-enters); partial stalls/endpoints without ceding (backchannel by
+     *  DURATION, not vocabulary) → resume + drop. false disables. */
+    overlapPause: boolean;
+    /** no new partial activity for this long while paused → resume, drop the interjection */
+    overlapResumeMs: number;
+    /** A genuine barge over a LONG reply is defeated by the dominant-novel gate: Meet echoes our own
+     *  speech back, so the partial is mostly our words + a few of hers → never "dominant novel" → it
+     *  resumes (replaying old audio — the audible "completes the buffer" blip) instead of ceding.
+     *  Mechanism-based discriminator: a re-PAUSE this soon after a resume = a persistent human, not an
+     *  echo blip (which pauses once and stalls). Cede on the re-pause regardless of the novel gate. */
+    overlapRepauseCedeMs: number;
+}
+declare class VoiceEngine {
+    options: VoiceEngineOptions;
+    state: VoiceState;
+    protected stt: SttLike;
+    protected tts: TtsLike;
+    protected player: AudioSink;
+    private speaking;
+    private ctxOpen;
+    private interrupted;
+    private spokeDeltas;
+    private drainTimer;
+    private echoWords;
+    private prevReply;
+    private reply;
+    private echoUntil;
+    private baseline;
+    private hot;
+    private suspectUntil;
+    private ackAt;
+    private pendingUtt;
+    private pendingTimer;
+    private lastInterrupted;
+    private pausedAt;
+    private lastResumeAt;
+    private lastOverlapPartial;
+    private resumeTimer;
+    private turnStartAt;
+    constructor(options?: Partial<VoiceEngineOptions>);
+    start(): Promise<void>;
+    get usingAec(): boolean;
+    private idleWaiters;
+    private setState;
+    /** Resolve when the engine is no longer speaking (immediate if already idle). */
+    awaitIdle(): Promise<void>;
+    /** open a spoken turn (idempotent — safe from both onUtterance and first-delta paths).
+     *  `ack` speaks the configured micro-ack as the context opener (utterance path only —
+     *  masks LLM TTFT; re-voice turns begun by their first delta skip it). */
+    beginSpeech(ack?: boolean): void;
+    speakDelta(text: string): void;
+    /** close the spoken turn (idempotent); stays audible until ALL audio arrived AND playback drains */
+    endSpeech(): void;
+    /** text of the reply cut by the last barge-in — consumed by the host to tell the model what
+     *  the user did NOT hear. Cleared on read. */
+    takeInterruptedReply(): {
+        full: string;
+        heard: string;
+    } | null;
+    /** Speak a short filler phrase without starting a model turn (stays in listening mode after). */
+    speakFiller(text: string): void;
+    /** barge-in: stop audio NOW, cancel generation, reset for the user's utterance */
+    interrupt(): void;
+    stop(): void;
+    private words;
+    private novelWords;
+    private echoActive;
+    /** Genuine user speech vs our own bleed (AEC tier): novel words must DOMINATE, not merely exist.
+     *  Degraded AEC + an STT mis-hearing manufactures a single novel word out of pure echo (a name or
+     *  rare word in our own reply comes back transcribed slightly differently — 1 novel / N words).
+     *  A real interjection is mostly novel ("stop", "wait what") — short utterances pass on ratio,
+     *  longer ones on count. */
+    private genuine;
+    private handlePartial;
+    private static readonly TRAIL_RE;
+    /** The utterance sounds like the user paused mid-thought (trailing conjunction/filler/comma). */
+    private looksIncomplete;
+    private handleUtterance;
+    private flushUtterance;
+    private get overlapCapable();
+    private armResume;
+    private resetOverlap;
+    /** energy two-stage barge-in (heuristic tier only): spike over echo baseline → pause + confirm via STT */
+    private gatePassTimes;
+    private handleLevel;
+}
+
+declare class SonioxSTTOptions {
+    auth: AuthProvider;
+    source: AudioSource;
+    model: string;
+    languageHints: string[];
+    /** Client-side endpoint: finalized text + no new tokens for this long = utterance (don't wait for
+     *  Soniox's semantic <end>, which adds 0.5-1.5s — the difference between ping-pong and lag). */
+    silenceEndpointMs: number;
+}
+declare class SonioxSTT {
+    options: SonioxSTTOptions;
+    private ws;
+    private stopped;
+    private sourceStarted;
+    onPartial: (text: string) => void;
+    onUtterance: (text: string, endpointAt: number) => void;
+    /** mic energy (RMS) per chunk — drives the energy-based heuristic barge-in tier */
+    onLevel: (rms: number) => void;
+    private finalText;
+    private partialText;
+    private lastChangeAt;
+    private lastCombined;
+    private endpointTimer;
+    private firstTokenAt;
+    constructor(options?: Partial<SonioxSTTOptions>);
+    get usingAec(): boolean;
+    private connectWs;
+    start(): Promise<void>;
+    private handle;
+    reset(): void;
+    stop(): void;
+}
+
+declare class CartesiaTTSOptions {
+    auth: AuthProvider;
+    voiceId: string;
+    model: string;
+    /** 'apiKey' (server/CLI) → `api_key=` URL param; 'token' (browser, BE-minted) → `access_token=`. */
+    authMode: 'apiKey' | 'token';
+}
+declare class CartesiaTTS {
+    options: CartesiaTTSOptions;
+    private ws;
+    private ctxSeq;
+    ctxId: string;
+    onAudio: (chunk: Uint8Array) => void;
+    onDone: () => void;
+    firstAudioAt: number;
+    /** Circuit breaker: consecutive error count + down flag. */
+    private consecutiveErrors;
+    private consecutiveOk;
+    private down;
+    private downAt;
+    private probeTimer;
+    private static readonly CB_THRESHOLD;
+    private static readonly CB_RECOVER_OK;
+    private static readonly CB_PROBE_MS;
+    constructor(options?: Partial<CartesiaTTSOptions>);
+    private closed;
+    private connecting;
+    connect(): Promise<void>;
+    private doConnect;
+    /** Close the breaker only after CB_RECOVER_OK consecutive good frames, so a single straggler chunk
+     *  after a 503 burst doesn't flap open→recover in <1s. A sub-2s down-window is a transient blip → debug. */
+    private markRecovered;
+    /** Ensure the WS is open before sending — reconnects if idle-closed. */
+    private ensureConnected;
+    newContext(): string;
+    private frame;
+    speak(text: string, cont: boolean): void;
+    end(): void;
+    cancel(): void;
+    private startProbe;
+    private stopProbe;
+    close(): void;
+}
+
+export { Agent, type AgentDef, AgentOptions, AgentTool, type AskOptions, type Attempt, type AudioSink, type AudioSource, type AuthProvider, BodDbFilesystem, CartesiaTTS, CartesiaTTSOptions, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, DuplexAgent, DuplexAgentOptions, type DuplexTaskStatus, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type LoadMemoryOpts, MEMORY_PROMPT, MessageContent, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, SCRATCH_DIR, STT_SAMPLE_RATE, type ScheduledJob, type ScheduledJobSnapshot, Scheduler, type SchedulerOptions, Scratch, type ScratchOptions, ScriptedHostBridge, type SiblingResolver, type SkillInfo, SonioxSTT, SonioxSTTOptions, type SttLike, TTS_SAMPLE_RATE, type TaskRecord, type TaskToolOptions, ToolCall, type ToolSpec, type Trigger, type TriggerCron, type TriggerInterval, type TriggerOneOff, type TtsLike, UserQuestion, VOICE_MEMORY_PROMPT, VOICE_SYSTEM_PROMPT, VoiceEngine, VoiceEngineOptions, type VoiceState, type WebFetchOptions, type WebSearchOptions, type WorkerTier, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, cronMatches, decodeDdgUrl, diskAgentOptions, expandCommand, expandEntry, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeAskTool, makeScheduleTools, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, nextCronAfter, parseCron, parseDdgHtml, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, resolveAuth, rollbackTool, sandboxAgentOptions, scanCommands, scanSkills, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };