agent.libx.js 0.86.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elya Livshitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# agent.libx.js
+
+**A coding agent on par with Claude Code — that also runs where Claude Code can't.**
+
+By default it's a full-strength terminal coding agent: real disk, real shell, and the same Read/Edit/Grep/permissions/streaming-DX surface you'd expect from Claude Code. The difference is its two host couplings are swappable seams:
+
+- **LLM** → any model via [`ai.libx.js`](https://github.com/Livshitz/ai.libx.js) (`AIClient.chat`, OpenAI-style tools/streaming).
+- **Filesystem** → a pluggable `IFilesystem` (real disk, in-memory, IndexedDB, a database, hybrid mounts) from [`wcli`](https://github.com/Livshitz/wcli)'s headless core.
+
+So the *same* agent loop also runs **sandboxed** (in-memory VFS, real disk untouched), on the **edge / browser** (no Node, no `/bin/sh`), or **hybrid** (mount real dirs + a database + remote storage side by side, with transactional overlays for checkpoint/rollback).
+
+Claude Code is the floor; running isolated, on the edge, or hybrid is the ceiling.
+
+## Quickstart
+
+```bash
+bun install                 # links wcli (file:), ai.libx.js + libx.js (bun link)
+bun test                    # 34 unit/integration tests (no API key needed)
+ANTHROPIC_API_KEY=… bun examples/run-sonnet.ts   # drive a real model
+bun eval/run.ts             # quantitative eval scorecard (real model)
+```
+
+## Use it
+
+```ts
+import { AIClient } from 'ai.libx.js';
+import { Agent, MemFilesystem } from 'agent.libx.js';
+
+const fs = new MemFilesystem();              // or NodeDiskFilesystem(dir) — interchangeable
+await fs.createDir('/src');
+await fs.writeFile('/src/x.ts', 'export const add = (a,b) => a - b;\n');
+
+const ai = new AIClient({ apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY } });
+const res = await new Agent({ ai, fs, model: 'anthropic/claude-sonnet-4-6' })
+  .run('Fix the add bug in /src/x.ts');
+
+console.log(res.finishReason, await fs.readFile('/src/x.ts'));
+```
+
+## Tools the agent gets
+
+- **`Shell`** (CLI disk mode) — a real `/bin/sh`: run any installed binary (git, bun, node, curl, scripts, …). **`bash`** (library / sandbox mode) — `ls/cat/grep/find/head/tail/echo/mkdir/rm/mv/wc`, pipes, redirects, chaining — over the VFS (wcli's sandboxed JS interpreter).
+- **`Read`** — 1-indexed numbered lines, `offset`/`limit`.
+- **`Edit`** — exact unique-substring replace, with a read-before-edit staleness guard.
+- **`Grep`/`Glob`/`Write`/`MultiEdit`** — structured, typed results straight from the VFS (no `bash` parsing). The selectable tool set the self-evolution loop mutates over.
+- **`TodoWrite`** — a planning scratchpad; **`Task`** — spawn a depth-limited child agent over the VFS (`subagents: true`); **`SlashCommand`** — reusable prompt templates from `<dir>/*.md` (`commandsDir`); plus a real **MCP client** (`src/mcp.client.ts`, node-only — stdio/HTTP JSON-RPC handshake + discovery) that feeds the edge-safe **MCP adapter** (`mcpToolsToAgentTools`), so any MCP server's tools become agent tools.
+- **`WebFetch`/`WebSearch`** — opt-in network tools (not in the default set): fetch a URL as readable text, or search via a configured provider (`TAVILY_API_KEY`). Enable per project with `tools: [...,'WebFetch']` in config. Factory-built with an injectable `fetch`, so they stay edge-portable and testable.
+
+## Agentic subsystems
+
+Beyond file tools, the runtime ships the higher-altitude pieces too — each an `AgentOptions`/loop extension over the two seams (see [`mind/06`](./mind/06-agent-features.md)):
+
+- **Skills + memory** — VFS-backed (`skillsDir`/`memoryDir`); persistence is just the backend choice.
+- **Subagents** (`subagents`; **typed agents** via `agentsDir` — `<dir>/<name>.md` defines a persona + model + scoped tools, selected with the `Task` `agentType`), **hooks** (`hooks`: preToolUse/postToolUse/onStop — block or audit any tool call), **slash-commands** (`commandsDir`), **TodoWrite**, **MCP** (`mcpToolsToAgentTools`).
+- **Streaming** (`stream: true` → `text_delta` via `HostBridge.notify`) and **context compaction** (`compaction: { maxMessages }` → edge-safe summarize-and-boundary). Defaults preserve the original non-stream, drop-oldest behavior.
+- **Multi-turn + project context** — `Agent.send()` continues a conversation across turns (vs `run()`, which starts fresh); **project instructions** (`instructionFiles`: `AGENTS.md`/`CLAUDE.md` at the FS root) inject into the system prompt.
+- **Budget kill-switches** — always-on per-run guards (`maxTokens`/`timeoutMs`/`maxRepeats`/`maxToolCalls`/`signal` → `finishReason` `budget`/`timeout`/`loop`/`max_tool_calls`/`aborted`) protect the API spend against runaway loops. The *enforceable* billing cap is server-side in the web key-proxy: a VFS-backed budget config (`/.agent/budget.json`, USD-metered, hot-reloaded, $100/wk default) a browser client can't bypass. See [`web/`](./web) and [`mind/06`](./mind/06-agent-features.md).
+
+## The `agentx` CLI
+
+A dependency-light `readline` REPL (plus headless `-p` mode) over the runtime:
+
+```bash
+agentx                      # interactive REPL in the current dir
+agentx "fix the bug in x"   # run once and exit
+agentx -c "keep going"      # continue the most recent session
+agentx --resume <id> "…"    # resume a specific session
+```
+
+- **Filesystem + Shell** — by default the CLI has **full real-filesystem access like Claude Code** (root `/` is the machine root, the launch dir is the working dir, absolute host paths and above-cwd reach both work) with a **real `/bin/sh`** (`Shell` tool) so the agent can run git, bun, node, curl, and any installed binary. Secrets (`.env`, `.ssh`, keys, `.git`) stay hidden by the jail; env secrets are scrubbed from the child shell. `--sandbox` instead operates over an in-memory copy of the working dir with a VFS-only `bash` — the real disk is never touched. `--boddb <dir>` runs over a **persistent database workspace** (a bod-db store at `<dir>` — `meta.db` tree + `files/` bytes) that survives across runs while the real disk stays untouched; DB-native by default, or add `--seed` to hydrate it from cwd on the first run. `--no-shell` forces the VFS bash in disk mode. (`/sandbox` shows the active mode.)
+- **Sessions** — every conversation persists to `./.agent/sessions/<id>.json`; `--continue`/`--resume` (and `/sessions`, `/resume`) pick it back up, *with memory across turns* — a REPL turn sees the previous one.
+- **Diffs** — every `Edit`/`Write`/`MultiEdit` renders a colorized `+/-` diff (TTY-gated; plain when piped).
+- **Slash commands** — `/help /tools /model /compact /clear /sessions /resume /commands /init`; user-defined `./.agent/commands/<name>.md` are invokable directly as `/<name>` (the same registry the model's `SlashCommand` tool uses).
+- **Project instructions** — `./AGENTS.md` (or `CLAUDE.md`) auto-loads into every run; `/init` scaffolds one.
+- **Any provider** — set `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `GROQ_API_KEY`; choose with `-m provider/model`.
+- **@-file mentions & headless JSON** — reference files inline in a prompt with `@path` (e.g. `explain @src/Agent.ts`); script with `-p --output-format json` to get one machine-readable result object on stdout (activity stays on stderr).
+- **Tab-completion** — `Tab` completes `/<command>` names and `@<path>` file/dir references (descends subdirs, dotfiles hidden unless typed) straight from the working tree.
+- **MCP servers** — declare `mcpServers: { name: { command, args } | { url } }` in config and they're auto-mounted at startup: the client does the JSON-RPC handshake (stdio or HTTP) + `tools/list`, and the discovered tools appear as `mcp__<name>__<tool>` in `/tools` (inspect with `/mcp`). A bad server is logged and skipped, never blocking the agent.
+
+## 🧬 It improves itself
+
+The agent is a coding agent that operates over a swappable filesystem — so it can be pointed at **its own repo** and evolve its own configuration. `evolve/` is an autonomous loop:
+
+```
+champion → propose patch → jailed + sandboxed eval → per-task no-regression gate → ledger → repeat
+```
+
+An LLM is the mutation operator; a **behavioral** fitness function (run the produced code) is natural selection. Correctness is a hard gate, the rule files are **hash-pinned** (the agent can't edit what judges it), and every candidate runs under two containment boundaries — a `JailedFilesystem` (secret denylist, symlink-escape defense) and a **sandboxed grader** (scrubbed env, nonce-authenticated result, default-on `sandbox-exec`). Those guardrails were hardened against a **22-agent adversarial red-team (14 findings fixed)** before the loop was allowed to run.
+
+**Result (Sonnet 4.6):** the loop autonomously drove **baseline 32 → 15 tool-calls (53% fewer), 5/5 pass held** — **parity with Claude Code** (head-to-head **15 vs 15 tools, 1.8× faster, 2.8× fewer tokens**), the efficiency gap we'd only described before. This is the *denoised* figure (each candidate averaged over 3 runs so no lucky run promotes); a single un-averaged run reached 14. It **generalizes** to held-out tasks (24 → 12, no overfit) and discovered the human-authored parity plan on its own: *use structured Grep/MultiEdit, stop over-exploring.*
+
+```bash
+GENERATIONS=8 bun evolve/loop.ts     # evolve → evolve/champion.json + ledger.jsonl
+bun evolve/report.ts                 # instant replay of the arc (no tokens)
+EVOLVED=1 bun compare/run.ts         # evolved champion vs Claude Code
+bun evolve/generalize.ts             # baseline vs champion on UNSEEN tasks
+```
+
+Full design + threat model + results: [`mind/08-self-evolve.md`](./mind/08-self-evolve.md).
+
+## Status
+
+**v1 (done):** loop + hybrid tools + Mem/Disk backends + deterministic `FakeAIClient` tests + real-model run. **5/5 pass@1** on the behavioral eval (Sonnet 4.6); the head-to-head started at correctness parity with Claude Code but ~2× the tool calls (≈28 vs 15) — a gap the **self-evolution loop has now closed autonomously**: it drove its own baseline from 32 → 15 tool-calls (denoised over 3 runs) and ties Claude Code in a fresh head-to-head (15 vs 15). **112 tests green.**
+
+See [`mind/`](./mind/) for the full vision, architecture, decision journal, roadmap, eval + head-to-head results, the [parity plan](./mind/05-parity.md), and the [self-evolution design](./mind/08-self-evolve.md).
+
+## Eval & compare
+
+```bash
+bun eval/run.ts            # behavioral scorecard (our agent over MemFilesystem)
+bun compare/seed-tasks.ts  # materialize task specs into .tmp/tasks/
+bun compare/run.ts         # head-to-head vs Claude Code (needs `claude` CLI)
+```

package/dist/Agent-WTkHB8RY.d.ts

@@ -0,0 +1,319 @@
+import { IFilesystem } from '@livx.cc/wcli/core';
+import { M as Message, H as HostBridge, A as AgentTool, C as ChatLike, e as MessageContent } from './tools-Ch-OzOU8.js';
+
+/**
+ * Hooks — deterministic interception points around tool execution, run by the
+ * harness/host (mirrors Claude Code hooks). The seam stays edge-safe: hooks are
+ * plain async callbacks, no node builtins, injected via AgentOptions.hooks.
+ *
+ *  - preToolUse:  fires BEFORE a tool runs. Return `{ block: true, reason }` to
+ *                 skip the tool — Agent.dispatch returns `Blocked by hook: <reason>`
+ *                 as the tool result (the model sees it and can adapt).
+ *  - postToolUse: fires AFTER a tool produced its result string (observe/audit).
+ *  - onStop:      fires once when the loop terminates with finishReason 'stop'.
+ */
+
+interface ToolUse {
+    name: string;
+    args: any;
+}
+interface PreToolUseDecision {
+    block?: boolean;
+    reason?: string;
+}
+/** Per-call metadata threaded through dispatch — `id` is the model-supplied tool_call id,
+ *  letting a host correlate a result to its call without assuming serial dispatch order. */
+interface ToolUseMeta {
+    id?: string;
+}
+interface Hooks {
+    /** Guard a tool call before it runs; return `{ block, reason }` to skip it. */
+    preToolUse?(call: ToolUse, meta?: ToolUseMeta): Promise<PreToolUseDecision | void> | PreToolUseDecision | void;
+    /** Observe a tool's result after it ran (audit, metrics, side-channel). */
+    postToolUse?(call: ToolUse, result: string, meta?: ToolUseMeta): void | Promise<void>;
+    /** Fired once when the agent loop stops cleanly with the model's final text. */
+    onStop?(finalText: string): void;
+    /** Fired once at session start (a fresh `run()`, or the first `send()`). Return a string to inject
+     *  as extra system context (e.g. environment facts, project status). Multiple hooks concatenate. */
+    onSessionStart?(): string | void | Promise<string | void>;
+    /** Fired per user turn BEFORE the model call. Return a string to replace the submitted text
+     *  (rewrite/annotate the prompt); chained across hooks. Return void to leave it unchanged. */
+    onUserPromptSubmit?(text: string): string | void | Promise<string | void>;
+    /** Fired before a manual `compactNow()` folds older messages — observe (e.g. persist a summary). */
+    onPreCompact?(messages: Message[]): void | Promise<void>;
+    /** Fired when a `Task`/`TaskBatch` child agent finishes, with its summary + label. */
+    onSubagentStop?(summary: string, info?: {
+        label?: string;
+        agentType?: string;
+    }): void | Promise<void>;
+}
+/** Deterministic Hooks for tests/dev: records calls + scripts block decisions by tool name. */
+declare class RecordingHooks implements Hooks {
+    private blocks;
+    pre: Array<{
+        call: ToolUse;
+        meta?: ToolUseMeta;
+    }>;
+    post: Array<{
+        call: ToolUse;
+        result: string;
+        meta?: ToolUseMeta;
+    }>;
+    stops: string[];
+    /** tool name -> reason; a matching preToolUse call is blocked with that reason. */
+    constructor(blocks?: Record<string, string>);
+    preToolUse(call: ToolUse, meta?: ToolUseMeta): PreToolUseDecision | void;
+    postToolUse(call: ToolUse, result: string, meta?: ToolUseMeta): void;
+    onStop(finalText: string): void;
+}
+/** Recording lifecycle hooks for tests: capture session-start/prompt-submit/pre-compact + script transforms. */
+declare class RecordingLifecycle implements Hooks {
+    private startContext?;
+    private rewrite?;
+    starts: number;
+    prompts: string[];
+    compactions: number[];
+    /** @param startContext injected at session start; @param rewrite maps a submitted prompt to a new one. */
+    constructor(startContext?: string | undefined, rewrite?: ((t: string) => string) | undefined);
+    subagentStops: Array<{
+        summary: string;
+        label?: string;
+    }>;
+    onSessionStart(): string | void;
+    onUserPromptSubmit(text: string): string | void;
+    onPreCompact(messages: Message[]): void;
+    onSubagentStop(summary: string, info?: {
+        label?: string;
+    }): void;
+}
+
+/**
+ * Permissions & plan-mode — safe-autonomy controls built ENTIRELY on the hooks +
+ * host seams (no Agent-core changes needed). Two pieces:
+ *   - PermissionPolicy → Hooks: allow / ask (host.confirm) / deny a tool call by tool
+ *     name + path glob. First matching rule wins; default decision otherwise.
+ *   - planMode(): blocks mutating tools until the agent presents a plan via `ExitPlanMode`
+ *     and the host approves — Claude-Code-style plan gating.
+ */
+type Decision = 'allow' | 'ask' | 'deny';
+interface PermissionRule {
+    /** tool name to match (omit = any tool). */
+    tool?: string;
+    /** glob on the call's `path` arg to match (omit = any/none). */
+    pathGlob?: string;
+    decision: Decision;
+}
+declare class PermissionOptions {
+    rules: PermissionRule[];
+    /** decision when no rule matches. */
+    default: Decision;
+    /** host channel for `ask` (confirm). If absent, `ask` is treated as `deny` (fail-closed). */
+    host?: HostBridge;
+    /** Richer ask resolver (CLI surfaces a Yes/No/Always menu). Returns the decision + whether to
+     *  remember it — on remember, the policy adds a session rule so the same tool isn't re-asked.
+     *  If unset, falls back to `host.confirm` (plain yes/no). */
+    ask?(call: ToolUse): Promise<{
+        decision: 'allow' | 'deny';
+        remember?: boolean;
+    } | undefined>;
+}
+declare class PermissionPolicy {
+    options: PermissionOptions;
+    constructor(options?: Partial<PermissionOptions>);
+    /** Resolve the decision for a tool call (first matching rule, else default). */
+    decide(call: ToolUse): Decision;
+    /** A preToolUse hook enforcing this policy (deny/ask → block; allow → proceed). */
+    hooks(): Hooks;
+}
+/** Tools the agent must not run before the plan is approved (sensible default). */
+declare const DEFAULT_MUTATING: string[];
+/**
+ * Plan-mode: mutating tools are BLOCKED until the agent calls `ExitPlanMode` with a plan
+ * and (if a host is present) the user approves it. Returns the gating hook + the tool to
+ * add to the agent. Compose the hook with others via composeHooks().
+ */
+declare function planMode(opts?: {
+    mutating?: string[];
+    host?: HostBridge;
+}): {
+    hooks: Hooks;
+    tool: AgentTool;
+};
+/** Run several Hooks as one: preToolUse stops at the first block; post/stop all fire. */
+declare function composeHooks(...list: (Hooks | undefined)[]): Hooks;
+
+interface RunResult {
+    text: string;
+    steps: number;
+    /** Why the loop ended. The middle group are automatic kill-switches (budget/abuse guards). */
+    finishReason: 'stop' | 'max_steps' | 'budget' | 'timeout' | 'loop' | 'max_tool_calls' | 'aborted' | 'error';
+    messages: Message[];
+    /** Accumulated token usage across all turns (non-stream path). */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** True if ANY turn's usage was estimated (provider gave none) rather than exact — lets the UI mark cost `~`. */
+    usageEstimated?: boolean;
+    error?: unknown;
+}
+declare class AgentOptions {
+    /** Any ai.libx.js AIClient (or a FakeAIClient). */
+    ai: ChatLike;
+    /** Filesystem backend — MemFilesystem, NodeDiskFilesystem, IndexedDbFilesystem, …
+     *  OPTIONAL: if omitted, the agent lazily defaults to a JAILED real disk rooted at `process.cwd()`
+     *  (secrets hidden by DEFAULT_DENY) — resolved via a dynamic node import at first run, so the edge/
+     *  browser build (which always passes its own fs) never pulls in `node:fs`. Pass `fs` explicitly to
+     *  use any other backend (and to keep full control of the jail). */
+    fs?: IFilesystem;
+    model: string;
+    systemPrompt: string;
+    tools: AgentTool[];
+    maxSteps: number;
+    /** Hard ceiling on accumulated tokens (prompt+completion) across the run. 0 = unbounded. */
+    maxTokens: number;
+    /** Wall-clock ceiling in ms for the whole run. 0 = unbounded. */
+    timeoutMs: number;
+    /** Stop if the identical tool-call batch (name+args) repeats this many times in a row. 0 = off. */
+    maxRepeats: number;
+    /** Cumulative cap on tool calls dispatched across the run. 0 = unbounded. */
+    maxToolCalls: number;
+    /** External cancellation — abort the loop between steps (e.g. a UI "Cancel" button). */
+    signal?: AbortSignal;
+    /** 0 = never trim. Otherwise cap the messages sent per turn (system + most recent). */
+    maxContextMessages: number;
+    /** Note-taking: keep the most-recent N tool-result outputs verbatim; collapse OLDER ones to a one-line
+     *  stub in the sent context (the model already consumed them — it can re-Read/re-run). The stored
+     *  transcript is never mutated. 0 = keep all verbatim. */
+    keepToolOutputs: number;
+    /** Token-aware backstop (~4 chars/token estimate). After note-taking, drop oldest messages from the
+     *  sent context until the estimate is under this ceiling (pairing-safe). 0 = off. */
+    maxContextTokens: number;
+    /** VFS dir(s) of skills (`<dir>/<id>/SKILL.md`). If set: inject a catalog + add the `Skill` tool. Multiple dirs are merged (first wins on name collisions). */
+    skillsDir?: string | string[];
+    /** VFS dir(s) of slash-command templates (`<dir>/<name>.md`). If set: inject a catalog + add the `SlashCommand` tool. Multiple dirs are merged (first wins). */
+    commandsDir?: string | string[];
+    /** VFS dir of memory (`<dir>/MEMORY.md`). If set: inject the index at run start (persistence = backend). */
+    memoryDir?: string;
+    /** Filenames to discover as project instructions (e.g. `AGENT.md`, `AGENTS.md`, `CLAUDE.md`).
+     *  Walks the VFS tree and merges all found files (general → specific, like Claude Code).
+     *  `true` (default) = auto-discover standard names. `string[]` = custom names. `false` = skip. */
+    instructionFiles: boolean | string[];
+    /** Host interaction channel (human-in-the-loop). If set: adds the `AskUserQuestion` tool. */
+    host?: HostBridge;
+    /** Deterministic interception points around tool execution (pre/post/stop). */
+    hooks?: Hooks;
+    /** If true: add the `Task` tool so the agent can spawn depth-limited child agents over the VFS. */
+    subagents: boolean;
+    /** VFS dir of typed-subagent defs (`<dir>/<name>.md`). If set with `subagents`: inject a catalog + enable the `Task` `agentType` param. */
+    agentsDir?: string;
+    /** Current recursion depth (0 = top-level); spawned children run at depth+1. */
+    depth: number;
+    /** Hard ceiling on subagent nesting (beyond it the `Task` tool refuses to spawn). */
+    maxDepth: number;
+    /** Stream tokens from the model. Takes effect only with a `host.notify`; off => current (non-stream) behavior. */
+    stream: boolean;
+    /** Fold the dropped middle of an over-long transcript into a synthetic summary (edge-safe, no LLM). Off => drop-oldest. */
+    compaction?: {
+        maxMessages: number;
+    };
+    /** Add `Checkpoint`/`Rollback` tools (requires the fs to be an OverlayFilesystem). */
+    checkpoints: boolean;
+    /** Enable `bash({background:true})` + JobOutput/JobStatus/JobKill — sandbox background jobs (overlay-isolated,
+     *  committed on completion, drained at turn end). Useful when the VFS backend is slow (remote) or for sub-agents. */
+    backgroundJobs: boolean;
+    /** Plan mode: block mutating tools until the agent calls `ExitPlanMode` (host-approved). */
+    planMode: boolean;
+    /** Permission policy gating each tool call (allow / ask / deny). */
+    permissions?: PermissionPolicy;
+    /** Opt-in syntax guardrail: refuse to persist a syntactically-broken code-file write/edit. Default off. */
+    lintOnWrite?: boolean;
+    /** Opt-in: after a write-class tool runs, run `command` over the VFS and append any failure to the tool result.
+     *  `tools` defaults to ['Write','Edit','MultiEdit','ApplyEdits']. */
+    autoTest?: {
+        command: string;
+        tools?: string[];
+    };
+}
+/**
+ * The agentic loop: chat() -> dispatch tool_calls over the VFS -> thread results
+ * back -> repeat until the model stops (no tool calls) or maxSteps is hit.
+ */
+declare class Agent {
+    options: AgentOptions;
+    transcript: Message[];
+    private ctx;
+    private activeTools;
+    private activeHooks?;
+    private prepared;
+    private systemPromptCache;
+    private started;
+    /** Inject tools into a running agent (e.g. dynamically mounted MCP servers). Takes effect on the next turn. */
+    addTools(tools: AgentTool[]): void;
+    /** Remove tools by name from a running agent. Returns the count removed. */
+    removeTools(names: Set<string> | string[]): number;
+    constructor(options?: Partial<AgentOptions>);
+    /** Build the tool context from the resolved fs + options. Idempotent-safe: called once (ctor or ensureFs). */
+    private buildCtx;
+    /**
+     * Resolve the filesystem + build the tool context if the ctor couldn't (no `fs` was passed). The disk
+     * default lives HERE, not in the ctor: the ctor can't await, and we must avoid a STATIC `node:fs` import
+     * in the core (edge/browser would break). The dynamic import only fires when `fs` is omitted — edge code
+     * always passes its own `MemFilesystem`, so the node module is never reached. Default = jailed disk @ cwd.
+     */
+    private ensureFs;
+    /**
+     * Assemble the system prompt + active tools/hooks ONCE per conversation (memoized).
+     * `run()` resets the memo to start fresh; `send()` reuses it, so multi-turn state —
+     * plan-mode approval, the tool set, the skills/commands/memory snapshot — stays stable
+     * across turns (and the frozen prompt pairs well with prompt caching). Does NOT touch
+     * the transcript; `run`/`send` own that.
+     */
+    private prepare;
+    /** Single-shot: reset all per-conversation state and run `task` to completion. `task` may be plain
+     *  text or multimodal content parts (text + images). */
+    run(task: MessageContent): Promise<RunResult>;
+    /** Apply onUserPromptSubmit to a turn: rewrite plain text; pass multimodal content through untouched. */
+    private applyPromptSubmit;
+    /** Fire onSessionStart once per conversation; returns any injected context. */
+    private fireSessionStart;
+    /** Fire onUserPromptSubmit; returns the (possibly rewritten) prompt text. */
+    private fireUserPromptSubmit;
+    /**
+     * Multi-turn: continue the existing conversation by appending a user turn instead of
+     * resetting — this is what makes an interactive REPL feel like one conversation. The
+     * leading system message is (re)synced to the current prompt, so a resumed session whose
+     * tools were rebuilt gets a matching catalog rather than a stale one.
+     */
+    send(task: MessageContent): Promise<RunResult>;
+    /**
+     * Fold the conversation in place (manual `/compact`): keep the system message + the
+     * most-recent window, summarizing the dropped middle (deterministic, no LLM call).
+     * No-op when the transcript already fits. Returns the number of messages removed.
+     */
+    compactNow(maxMessages?: number): number;
+    private runLoop;
+    /**
+     * Drain a streamed chat() response: emit each text delta to the host
+     * (`{kind:'text_delta'}`) and fold all chunks back into the single
+     * ChatResponse the non-stream path would have returned.
+     */
+    private consumeStream;
+    private dispatch;
+    private static readonly WRITE_CLASS;
+    /** Append an autoTest failure section to a write-class tool result, if configured. */
+    private maybeAutoTest;
+    /**
+     * Shape the per-turn context (a VIEW — the stored transcript is never mutated). Layered, each off by default:
+     *  1. coarse reduction — `compaction` (fold the dropped middle into a synthetic summary) OR
+     *     `maxContextMessages` (pure drop-oldest), keeping the system message + most-recent window.
+     *  2. note-taking (`keepToolOutputs`) — collapse all-but-the-recent-N tool-result bodies to one-line stubs
+     *     (kills "immortal tool results": a big Read/Grep stops costing its full weight once it's old).
+     *  3. token-aware backstop (`maxContextTokens`) — drop oldest messages until under an estimated token ceiling.
+     * With every knob off, returns the transcript unchanged (same reference).
+     */
+    trimContext(): Message[];
+}
+
+export { Agent as A, DEFAULT_MUTATING as D, type Hooks as H, PermissionOptions as P, RecordingHooks as R, type ToolUse as T, AgentOptions as a, type Decision as b, PermissionPolicy as c, type PermissionRule as d, type PreToolUseDecision as e, RecordingLifecycle as f, type RunResult as g, type ToolUseMeta as h, composeHooks as i, planMode as p };

package/dist/cli.d.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+import { g as RunResult } from './Agent-WTkHB8RY.js';
+import { IFilesystem } from '@livx.cc/wcli/core';
+import { M as Message, c as ContentPart } from './tools-Ch-OzOU8.js';
+
+/**
+ * On-disk session store for the CLI: each conversation is one JSON file at
+ * `<cwd>/.agent/sessions/<id>.json`. Writes are atomic (temp + rename) so a crash
+ * mid-write never corrupts a prior session. This is what gives the REPL memory across
+ * turns and powers `--continue` / `--resume`.
+ */
+interface SessionMeta {
+    id: string;
+    created: number;
+    updated: number;
+    cwd: string;
+    model?: string;
+    turns: number;
+    title: string;
+    /** Cumulative tokens across all turns in this session (for `/cost`). */
+    tokens?: number;
+    /** Cumulative USD cost across all turns (per-turn model pricing; for `/cost`). */
+    costUsd?: number;
+    /** Sticky: true if any turn's usage was estimated (streamed without provider usage) → cost is approximate. */
+    costEstimated?: boolean;
+}
+interface SessionData {
+    meta: SessionMeta;
+    messages: Message[];
+}
+
+/** Classify a pasted blob (e.g. a drag-dropped file path) into an attachment: `display` is shown in the
+ *  in-buffer placeholder, `ref` is what the placeholder expands to on submit (e.g. an `@/abs/path` mention). */
+type PasteClassifier = (text: string) => {
+    display: string;
+    ref: string;
+} | null;
+
+interface Args {
+    task?: string;
+    model?: string;
+    cwd?: string;
+    stream: boolean;
+    plan: boolean;
+    ask: boolean;
+    yes: boolean;
+    vfs: boolean;
+    shell: boolean | undefined;
+    boddb?: string;
+    seed: boolean;
+    subagents: boolean;
+    maxSteps?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    help: boolean;
+    version: boolean;
+    cont: boolean;
+    resume?: string;
+    outputFormat: 'text' | 'json' | 'stream-json';
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    appendSystemPrompt?: string;
+    addDirs?: string[];
+    print?: boolean;
+    debug?: boolean;
+}
+declare function parseArgs(argv: string[]): Args;
+/** Render a resumed conversation (like CC) so the user sees the context they're continuing: user
+ *  prompts, assistant narration, and a condensed line per tool action. Tool *results* are omitted
+ *  (verbose) and inlined @-mention blocks are stripped from prompts. Pure → unit-testable. */
+declare function formatHistory(messages: Message[]): string;
+/** Render a transcript to portable Markdown (no ANSI) for `/export`. Same shape as formatHistory —
+ *  user prompts + assistant narration + one quoted line per tool action; tool results omitted. Pure → unit-testable. */
+declare function exportMarkdown(meta: {
+    id: string;
+    title?: string;
+    model?: string;
+    turns?: number;
+    created?: number;
+    tokens?: number;
+    costUsd?: number;
+    costEstimated?: boolean;
+}, messages: Message[]): string;
+/** USD cost from a model's per-1K pricing (ai.libx.js ModelPricing) + token usage. 0 if unpriced. */
+declare function costOf(pricing: {
+    inputCostPer1K: number;
+    outputCostPer1K: number;
+} | undefined, promptTokens?: number, completionTokens?: number): number;
+/** Format a USD amount: 2 decimals at $1+, 4 below (agent turns are sub-cent). */
+declare function fmtUsd(n: number): string;
+/** ~4 chars/token estimate over a transcript (matches the Agent's context-budget heuristic). */
+declare function estimateTranscriptTokens(messages: Message[]): number;
+/** One-screen session status (model, dir, fs-mode, tools, permission posture, turns/tokens). Pure. */
+declare function formatStatus(s: {
+    model: string;
+    cwd: string;
+    mode: string;
+    tools: string[];
+    permissions: string;
+    turns: number;
+    tokens: number;
+    sessionId: string;
+    /** Whether the token count is estimated (any turn streamed without provider usage). Defaults to estimated. */
+    estimated?: boolean;
+}): string;
+/** Run a `!cmd` line over the VFS (works on real disk in disk mode) and return its output — no model
+ *  call. Mirrors the bash tool's contract so `!ls`/`!git status` behave like the agent's own bash. */
+declare function runShellLine(fs: IFilesystem, cmd: string): Promise<string>;
+/** Append a `#note` to the memory index (creating the dir/file if needed). Returns the file path. */
+declare function appendMemoryNote(fs: IFilesystem, dir: string, text: string): Promise<string>;
+interface PermMode {
+    gate: 'ask' | 'allow';
+    notice?: string;
+}
+/**
+ * Default permission posture — CC-inspired: **ask when a human can answer, allow when unattended.**
+ * Pure + exported so the decision is unit-testable without a TTY. Precedence:
+ *   --yes  → allow (explicit trust, no prompts)
+ *   --ask  → ask   (explicit gate, even headless)
+ *   interactive (TTY & not json) → ask  (the safe default)
+ *   else (headless/piped) → allow, with a one-line notice so it's never silent.
+ */
+declare function resolvePermMode(args: {
+    yes?: boolean;
+    ask?: boolean;
+    outputFormat?: string;
+}, interactiveCapable: boolean): PermMode;
+/** Read `@image.png` mentions from `line` as base64 image content parts (real files under cwd; binary,
+ *  so read via node fs — the VFS readFile is utf8). Unreadable/missing images are skipped silently
+ *  (expandMentions reports the missing @ref separately). */
+declare function readImageParts(cwd: string, line: string): ContentPart[];
+/** Classify a pasted blob as a file attachment when it's a drag-dropped/typed path to an existing file.
+ *  Returns an `@<abs>` ref the existing mention pipeline attaches (images) or inlines (other files); the
+ *  in-buffer placeholder shows `[Image #N]` / `[File name #N]`. Returns null for anything not a clear single
+ *  path (so ordinary text pastes are unaffected). Paths with spaces are skipped — the `@\S+` pipeline can't carry them. */
+declare function pastePathClassifier(cwd: string): PasteClassifier;
+/** Inline `@path` file mentions: append referenced files' contents so the model sees them (missing → warn, leave as-is). */
+declare function expandMentions(fs: IFilesystem, line: string): Promise<{
+    text: string;
+    loaded: string[];
+    missing: string[];
+}>;
+/** The headless `--output-format json` result object for a turn. */
+declare function jsonResult(res: RunResult, session: SessionData): {
+    ok: boolean;
+    finishReason: "error" | "budget" | "stop" | "max_steps" | "timeout" | "loop" | "max_tool_calls" | "aborted";
+    text: string;
+    steps: number;
+    tools: number;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | undefined;
+    sessionId: string;
+};
+/**
+ * Read one logical input, supporting `\`-continuation for multi-line prompts: a line ending in
+ * a backslash drops the `\` and keeps reading; the parts are joined with newlines. `readLine`
+ * is injected (the REPL passes a readline `question`; tests pass a scripted reader).
+ */
+declare function readMultiline(readLine: (continuing: boolean) => Promise<string | null>): Promise<string | null>;
+
+export { type PermMode, appendMemoryNote, costOf, estimateTranscriptTokens, expandMentions, exportMarkdown, fmtUsd, formatHistory, formatStatus, jsonResult, parseArgs, pastePathClassifier, readImageParts, readMultiline, resolvePermMode, runShellLine };