agent.libx.js 0.86.0

package/dist/index.d.ts

@@ -0,0 +1,621 @@
+import { a as AgentOptions, H as Hooks, g as RunResult } from './Agent-WTkHB8RY.js';
+export { A as Agent, D as DEFAULT_MUTATING, b as Decision, P as PermissionOptions, c as PermissionPolicy, d as PermissionRule, e as PreToolUseDecision, R as RecordingHooks, f as RecordingLifecycle, T as ToolUse, h as ToolUseMeta, i as composeHooks, p as planMode } from './Agent-WTkHB8RY.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 } from './tools-Ch-OzOU8.js';
+export { c as ContentPart, d as HostEvent, M as Message, e as MessageContent, 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 imagePart, o as makeContext, p as makeJobTools, r as readTool, t as toWireTools, q as todoWriteTool, s as toolRegistry, u as toolsByName } from './tools-Ch-OzOU8.js';
+export { M as McpCall, a as McpToolSearchOptions, b as McpToolSpec, m as makeMcpToolSearch, c as mcpToolToAgentTool, d as mcpToolsToAgentTools } from './mcp-Dg3vA1Uj.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;
+    /** 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;
+
+/** 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'): 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;
+    /** API key for the search provider (default: process.env.TAVILY_API_KEY). */
+    apiKey?: string;
+    /** Provider endpoint (default: Tavily, an agent-oriented search API). */
+    endpoint?: string;
+    maxResults?: number;
+    timeoutMs?: number;
+}
+/** Build a WebSearch tool backed by a configured provider (Tavily by default). */
+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;
+
+/**
+ * `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 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.)
+ */
+declare function loadSkills(fs: IFilesystem, dir: string | string[], opts?: {
+    relevanceHint?: string;
+    max?: number;
+}): 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[];
+};
+
+interface CommandInfo {
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * 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 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.
+ */
+declare function loadCommands(fs: IFilesystem, dir: string | string[], opts?: {
+    relevanceHint?: string;
+    max?: number;
+}): Promise<{
+    commands: CommandInfo[];
+    catalog: string;
+    tool?: AgentTool;
+}>;
+
+/**
+ * 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.
+ */
+declare function loadMemory(fs: IFilesystem, dir: string, opts?: {
+    relevanceHint?: string;
+    max?: number;
+}): 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): 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>;
+
+/**
+ * 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;
+
+export { type AgentDef, AgentOptions, AgentTool, type Attempt, BodDbFilesystem, ChatLike, ChatOptions, ChatResponse, type CommandInfo, ConsoleHostBridge, DEFAULT_DENY, FakeAIClient, Hooks, HostBridge, JailOptions, JailedFilesystem, type LessonOptions, LessonOptionsDefaults, type Mount, MountFilesystem, NodeDiskFilesystem, OverlayFilesystem, type ReflectOptions, RunResult, ScriptedHostBridge, type SkillInfo, type TaskToolOptions, ToolCall, type ToolSpec, UserQuestion, type WebFetchOptions, type WebSearchOptions, applyEditsTool, askUserQuestionTool, checkpointTool, checkpointTools, compileSynthesizedTool, diskAgentOptions, expandCommand, expandTemplate, forComponent, fullAgentOptions, globTool, grepTool, htmlToText, idfWeights, lessonCapture, loadAgents, loadCommands, loadInstructions, loadMemory, loadSkills, makeTaskBatchTool, makeTaskTool, makeWebFetchTool, makeWebSearchTool, mkdirp, multiEditTool, raceAttempts, reflectOnRun, relevanceScore, repoIndex, repoMapTool, rollbackTool, sandboxAgentOptions, slugify, tokenize, toolCall, topByRelevance, validateToolCode, webFetchTool, webSearchTool, writeFact, writeTool };