@livx.cc/agentx 0.94.38

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,164 @@
+# agentx
+
+[![npm](https://img.shields.io/npm/v/@livx.cc/agentx?color=cb3837&logo=npm)](https://www.npmjs.com/package/@livx.cc/agentx)
+[![publish](https://github.com/Livshitz/agentx/actions/workflows/publish.yml/badge.svg)](https://github.com/Livshitz/agentx/actions/workflows/publish.yml)
+[![license](https://img.shields.io/npm/l/@livx.cc/agentx)](./LICENSE)
+![runtime](https://img.shields.io/badge/runtime-Bun-black?logo=bun)
+![edge-ready](https://img.shields.io/badge/runs-node%20%C2%B7%20browser%20%C2%B7%20edge-brightgreen)
+
+**A coding agent that matches Claude Code on correctness — then beats it on cost, tokens, and tool-efficiency, and runs where Claude Code can't (sandbox, browser/edge, database).**
+
+<p align="center"><img src="docs/demo.gif" alt="agentx reading, diffing, and fixing a bug in one prompt" width="760"></p>
+
+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.
+
+## How it stacks up vs Claude Code
+
+**Correctness parity — efficiency, cost, and reach are the lead.** Hard 7-task coding suite, Sonnet, *denoised* (each task ×3, no lucky run promotes; `SUITE=hard bun compare/run.ts`):
+
+| | agentx | Claude Code |
+|---|---|---|
+| Correctness | 7/7 | 7/7 — **parity** |
+| Tool-calls | **16** | 28 — **−43%** |
+| Tokens | **69k** | 171k — **2.5× fewer** |
+| Wall-time | **~100s** | 133s — **~25% faster** |
+
+**Cost** (9-task hard suite, USD-metered, vs CC-on-Opus): **$0.49** single-tier Sonnet (**5.4× cheaper**) · **$0.82** three-tier voice/duplex (**3.3× cheaper**) vs CC-Opus **$2.67** — at quality parity (16/18 vs 17/18 passes).
+
+Plus things Claude Code simply doesn't do:
+
+- **Runs where CC can't** — the *same* agent loop runs on real disk, an in-memory **sandbox**, the **browser/edge** (no Node, no `/bin/sh`), or a **database-backed** workspace. Swap the filesystem, not the agent.
+- **Keyless web search, built in** — `WebSearch` works in any deployment with no API key (DuckDuckGo; auto-upgrades to Tavily if you set one). CC's search is Anthropic-server-bound.
+- **Context-safe by default** — a 1 MB `Grep`/`Read`/MCP result is auto-paginated and can't blow the window; buried detail is recovered via a cheap context-isolated `Ask` peek — **~5.3× cheaper and more accurate** than re-fetching, in a head-to-head.
+- **It improves its own efficiency** — an autonomous evolution loop cut its own tool-use **~50% (32 → 15** on the core suite, denoised), self-discovered, not hand-tuned — the same lever behind the efficiency lead above.
+
+*Honest scope:* the win is **efficiency / cost / reach**, not a claim of smarter reasoning — correctness is parity. All figures are denoised and reproducible (see [Eval & compare](#eval--compare)); full boards in [`mind/09-outperform.md`](./mind/09-outperform.md).
+
+## Quickstart
+
+Point it at your project — no clone needed (requires [Bun](https://bun.sh)):
+
+```bash
+export ANTHROPIC_API_KEY=…                              # or OPENAI_API_KEY / GOOGLE_API_KEY / GROQ_API_KEY
+bunx @livx.cc/agentx "find and fix the failing test"   # run once in the current directory
+bunx @livx.cc/agentx                                   # …or open the interactive REPL
+```
+
+Want a permanent command? `bun add -g @livx.cc/agentx`, then just `agentx` (and `agentx --duplex` for voice). The agent has full real-disk + shell access by default (like Claude Code); add `--sandbox` to work on an in-memory copy instead. See [The `agentx` CLI](#the-agentx-cli) for flags, sessions, and slash commands.
+
+## Use it as a library
+
+```ts
+import { AIClient } from 'ai.libx.js';
+import { Agent, MemFilesystem } from '@livx.cc/agentx';
+
+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`** — fetch a URL as readable text, or search the web. **Keyless by default** (WebSearch uses DuckDuckGo; auto-upgrades to Tavily when `TAVILY_API_KEY` is set) and **auto-enabled in the CLI**. Factory-built with an injectable `fetch`, so they stay edge-portable and testable. (In the library they're opt-in by name: `tools: [...,'WebSearch']`.)
+- **Oversized-output pagination** — any tool result over a byte ceiling (`maxToolResultBytes`, default 60k) is cropped to page 1 with a marker (refine the query / read further), so one big `Grep`/`Read`/MCP/web result can't blow the context window. In the CLI (**on by default**; `--no-scratch` to disable) the full output instead spills **losslessly** to a **scratch** file and the model recovers specifics via `Grep`/`Read` or **`Ask`** — a cheap, context-isolated peek that returns just the answer (the raw blob never re-enters context).
+
+## 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.
+- **DuplexAgent** (`src/duplex.ts`) — voice-optimized three-tier engine (reflex/act/think): a fast reflex agent streams instant replies and self-selects escalation — `Act` for standard tool work (Sonnet-class), `Think` for deep reasoning (Opus-class, configurable, default on). Results are pushed back and re-voiced by the reflex (turn mutex, coalesced completions, `TaskStatus`/`CancelTask`). See [`mind/10`](./mind/10-duplex.md).
+- **Scheduler** (`src/scheduler.ts` + `cli/osScheduler.ts`) — one-off (`{at}`), interval (`{everyMs}`), cron (`{cron}`) via `ScheduleTask`/`ScheduleList`/`ScheduleCancel`/`Wakeup`. In-session jobs fire while the session is alive (persisted, re-armed on `--resume`); far one-offs (or `backend:'os'`) register with the OS scheduler (launchd / crontab / at) and **survive quitting** — the fired job headless-resumes the session (`agentx -p … --resume <id> --yes`). The `PushNotification` tool (osascript / notify-send) alerts the user out-of-band; `Read` on a `.pdf` returns extracted text (poppler's pdftotext, disk mode). **`RemoteTrigger`** invokes another agentx session on this machine: a session open in a live terminal receives the prompt as an injected turn (per-session unix socket, same-user only); otherwise it's resumed headless and the final answer comes back. See [`mind/12`](./mind/12-scheduler.md).
+- **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. `--harden` OS-sandboxes the real shell (macOS `sandbox-exec` / Linux `bwrap`): writes confined to cwd+tmp, outbound network blocked (`--harden-net` keeps network); commands fail closed when no wrapper exists. (`/sandbox` shows the active mode.)
+- **Sessions** — every conversation persists to `./.agent/sessions/<id>.json`, flushed at **every tool step** (a crash, hang, or Ctrl-C mid-turn loses at most the in-flight step, never the transcript); `--continue`/`--resume` (and `/sessions`, `/resume`) pick it back up, *with memory across turns* — a REPL turn sees the previous one. A global symlink index at `~/.agent/sessions/` enables cross-project lookup: `--resume 090715-myproject` resolves from any directory, and `/sessions all` lists every project's sessions in one picker.
+- **Diffs** — every `Edit`/`Write`/`MultiEdit` renders a colorized `+/-` diff (TTY-gated; plain when piped).
+- **Slash commands** — `/help /tools /model /compact /copy /diff /memory /clear /sessions /resume /commands /init`; `/compact <focus>` preserves matching lines from the folded span; `/copy [code]` puts the last reply (or its last code block) on the OS clipboard; `/diff` shows everything the session changed (oldest checkpoint → now); `/memory` opens the memory index in `$EDITOR`; user-defined `./.agent/commands/<name>.md` are invokable directly as `/<name>` (the same registry the model's `SlashCommand` tool uses). Skills/commands created **mid-session** are picked up automatically each turn (delivered as a cache-friendly `<system-reminder>` delta, like Claude Code) and the `Skill`/`SlashCommand` tools rescan on a name miss; `/reload` forces a full catalog + system-prompt rebuild.
+- **Live chrome** — the thinking spinner shows elapsed seconds + `esc to interrupt`; the terminal tab title tracks the session topic; a bell rings when a long (>10s) turn finishes in a backgrounded tab; the footer warns at 80%/90% context pressure and auto-trims announce themselves.
+- **`/transcript [n]`** — the full session transcript including complete tool-result bodies (the past-turn equivalent of Ctrl-O live verbose), paged through `less`; **`/doctor`** — one-shot environment sanity check (keys, model pricing, config, session-store writability, memory, MCP mounts).
+- **Syntax-highlighted code fences** — ```` ```ts ```` (and js/py/sh/go/rust/…) blocks render with keywords bold, strings green, numbers cyan, comments dim; unknown languages keep the plain cyan body. **TodoWrite plans** pin a compact `☑ 2/5 · current step` line into the idle footer.
+- **`/agents`** — list subagent types from `./.agent/agents` (description, model, tool scope); `/agents new <name>` scaffolds a frontmatter'd definition for the `Task` tool's `agentType`. **`!<partial>` + menu** completes from past `!` shell commands. **`@server:uri`** mentions inline an MCP resource body into the prompt. Transient network drops mid-step retry automatically (2 attempts, backoff) instead of failing the turn.
+- **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`; `~/` expands to the home directory; quote paths with spaces as `@"…"` — drag-dropped files, e.g. macOS screenshots, quote themselves automatically); 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.
+- **Duplex mode** — `agentx --duplex` runs the full standard REPL (slash commands, sessions, postures, rewind, MCP) with the three-tier engine driving turns: a fast voice model (`--voice-model`, default `groq/openai/gpt-oss-120b`) answers every line instantly and delegates real work to background workers built with the same wiring as a normal run (fs mode, permissions, MCP); worker activity shows as dim chrome and results are re-voiced when ready. Switch any tier live with `/model` (opens a reflex/act/think picker), or the `/voice-model` · `/think-model` shortcuts. `/tasks` lists background tasks, inspects a task's live output tail, and cancels a running one from a picker (Esc mid-turn cancels the foreground turn; Esc again at the idle prompt cancels running workers).
+- **MCP servers** — declare `mcpServers: { name: { command, args } | { url } }` in config and they're auto-mounted at startup (in parallel, with an optional `mountTimeoutMs` deadline so one slow/dead server never blocks the rest): 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. For large tool sets, **deferred mode** (`makeMcpToolSearch` / `mountMcpDeferred`) exposes just two bounded tools (`ToolSearch` + `McpCall`) instead of N defs — dodging the provider tool-cap and improving selection accuracy; the CLI applies this automatically past 12 mounted tools (a 42-tool server was costing ~80k tok/turn in schema alone), and permission rules written against the real `mcp__<name>__<tool>` names still match through `McpCall`. **`mountMcpCatalog`** goes further: a cached, hash-keyed catalog + lazy connect means a turn that uses no MCP tool opens **zero** connections, and one that uses a tool connects exactly that server — latency scales with tools-used, not servers-configured. A down server is **negative-cached** (`failureCooldownMs`) so it never re-floors a later turn at the deadline. For zero turn-path latency even on a cold process, call **`warmMcpCatalog`** at boot + on a timer (off-turn discovery) and mount with **`{ discover: 'cache-only' }`** — the turn then never synchronously connects: it serves the warmed catalog and discovers any miss in the background.
+
+## 🧬 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). **820+ 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).
+
+## Develop & evaluate
+
+Hacking on the runtime itself (from a clone):
+
+```bash
+bun install                # links wcli (file:), ai.libx.js + libx.js (bun link)
+bun test                   # 820+ unit/integration tests (offline via FakeAIClient, no key)
+ANTHROPIC_API_KEY=… bun examples/run-sonnet.ts   # drive a real model end-to-end
+```
+
+Eval & head-to-head (real model):
+
+```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 the `claude` CLI)
+```

package/dist/Agent-1DRfsYaK.d.ts

@@ -0,0 +1,408 @@
+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-DtpN8Agv.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>;
+    /** Observe a tool's INCREMENTAL output while it runs (only tools that stream, e.g. the real
+     *  Shell). Fire-and-forget — sync, never awaited, never alters the result. */
+    onToolOutput?(call: ToolUse, chunk: string, meta?: ToolUseMeta): 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;
+    }>;
+    outputs: Array<{
+        call: ToolUse;
+        chunk: 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;
+    onToolOutput(call: ToolUse, chunk: 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;
+
+/**
+ * Normalized reasoning/thinking control → provider-specific request fragment.
+ *
+ * Pure & dependency-free (no `ai.libx.js` import — provider is detected from the
+ * `provider/model` prefix), so it stays inside the Agent's structural-typing boundary.
+ * The returned fragment is spread into `ai.chat()`; callers never hand-craft the
+ * per-provider encoding (Anthropic `thinking.budget_tokens`, OpenAI `reasoning_effort`).
+ */
+/** `'off'`/undefined = no reasoning; named buckets; or a raw token budget (budget-based providers). */
+type ReasoningEffort = 'off' | 'low' | 'medium' | 'high' | number;
+interface ChatFragment {
+    providerOptions?: Record<string, unknown>;
+    /** Request `max_tokens`. Raised for budget-based providers so `budget_tokens < max_tokens` holds. */
+    maxTokens?: number;
+}
+/**
+ * Map a normalized effort to a partial `ChatOptions` fragment for `model`'s provider.
+ * Returns `{}` (safe no-op) for `'off'`, undefined, or an unsupported provider.
+ *
+ * Supported: `anthropic/*` (extended thinking), `openai/*` (reasoning_effort).
+ * `google/*` is intentionally NOT mapped here — its adapter `Object.assign`s
+ * providerOptions over the built `generationConfig`, clobbering it; pass an
+ * explicit `providerOptions` if you need Gemini thinking.
+ */
+declare function reasoningToChatFragment(model: string, effort?: ReasoningEffort): ChatFragment;
+
+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). With prompt caching,
+     *  promptTokens includes cached reads/writes; the cache splits ride along for exact pricing. */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cacheCreationTokens?: number;
+        cacheReadTokens?: 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; cache READS count at 0.1×
+     *  (their real price) so a fat cached context doesn't trip the guard on healthy turns. 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;
+    /** Pagination ceiling for a SINGLE tool result (bytes). A result over this is cropped to page 1 with
+     *  a marker telling the model it was cropped (refine the query, or page further). Guards against one
+     *  Grep/Read/MCP call blowing the whole context window. 0 = off. Default 60k (~15k tokens). */
+    maxToolResultBytes: number;
+    /** Hook to handle an oversized tool result instead of the default lossy crop: receives the FULL output
+     *  and returns the (cropped) string to put in context — e.g. spill to scratch and return a recoverable,
+     *  paginated stub. Called only when a result exceeds `maxToolResultBytes`. */
+    capToolResult?: (full: string, info: {
+        tool: string;
+        args: any;
+    }) => string | Promise<string>;
+    /** 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(s) of memory (`<dir>/MEMORY.md`). If set: inject the index at run start (persistence = backend).
+     *  Multiple dirs are merged (reads search all; writes go to first). */
+    memoryDir?: string | string[];
+    /** User-scope memory dir for global facts (type=user/feedback). Remember routes by type when set. */
+    memoryUserDir?: 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;
+    /** Add the `AskUserQuestion` tool when a host is present (default true). Set false for an agent that
+     *  must never block a turn on a structured question — e.g. a voice reflex that confirms inline. */
+    askUserQuestion: boolean;
+    /** 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;
+    /** Optional PDF text extraction for Read on .pdf files (node hosts wire pdftotext); absent => Read explains. */
+    pdfText?: (path: string) => Promise<string>;
+    /** 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[];
+    };
+    /** Provider-specific options forwarded to ai.chat() (e.g. cursor mcpServers, cwd). */
+    providerOptions?: Record<string, unknown>;
+    /** Prompt caching (providers that support it, e.g. Anthropic): cache tools/system/conversation
+     *  prefix across the loop's steps — reads cost 0.1x, writes 1.25x. A multi-step agent loop
+     *  re-sends its whole prefix every step, so this is a large net cost cut. Default on. */
+    promptCache: boolean;
+    /** Tool selection mode: 'auto' = model decides (needed for Groq); undefined = provider default. */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /** Extended-thinking / reasoning effort, normalized across providers (anthropic, openai).
+     *  `'off'`/undefined = none; `'low'|'medium'|'high'` or a raw token budget. Mapped to the
+     *  provider-specific request shape via {@link reasoningToChatFragment}; explicit `providerOptions` wins. */
+    reasoning?: ReasoningEffort;
+}
+/**
+ * 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 lastTrimNotified;
+    private activeTools;
+    private activeHooks?;
+    private prepared;
+    private systemPromptCache;
+    private started;
+    private parkedMs;
+    /** Time a human-blocking await (a permission/plan prompt) and bank it in `parkedMs` so idle prompt
+     *  time never trips the wall-clock kill-switch. The agent did no work while parked on the user. */
+    private park;
+    /** Force the next `send()`/`run()` to rebuild the system prompt, tools, plan-mode and permission hooks
+     *  from `options` — apply mid-conversation changes to `planMode`/`permissions`/`model` etc. (prepare()
+     *  is otherwise memoized per conversation). */
+    reprepare(): void;
+    /** Tools injected via addTools(); kept separate from options.tools so prepare() rebuilds don't drop them. */
+    private injectedTools;
+    /** Current tool surface for hosts/UIs (configured + injected, deduped by name) — options.tools
+     *  alone misses addTools()-injected ones (e.g. MCP servers mounted after startup). */
+    get toolNames(): string[];
+    /** Inject tools into a running agent (e.g. dynamically mounted MCP servers). Takes effect on the next turn
+     *  and survives prepare() rebuilds (reprepare(), new conversations). */
+    addTools(tools: AgentTool[]): void;
+    /** Remove tools by name from a running agent. Returns the count removed. Also filters
+     *  `options.tools` — otherwise a constructor-passed tool resurrects on the next prepare()
+     *  rebuild (and re-adding it via addTools() would then DUPLICATE it in the wire schema). */
+    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.
+     * `focus` (e.g. from `/compact keep the API details`) preserves matching lines from the
+     * dropped span verbatim in the summary, instead of losing them to the generic recap.
+     */
+    compactNow(maxMessages?: number, focus?: string): 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, type ChatFragment as C, DEFAULT_MUTATING as D, type Hooks as H, PermissionOptions as P, type ReasoningEffort as R, type ToolUse as T, AgentOptions as a, type Decision as b, PermissionPolicy as c, type PermissionRule as d, type PreToolUseDecision as e, RecordingHooks as f, RecordingLifecycle as g, type RunResult as h, type ToolUseMeta as i, composeHooks as j, planMode as p, reasoningToChatFragment as r };