amness 0.0.0-stage → 0.1.2

package/dist/src/bench.d.ts

@@ -0,0 +1,67 @@
+import { type Analysis, type Case, type Row } from "./evals.ts";
+export type ParseMode = "claude-json" | "codex-jsonl" | "amness-json" | "none";
+export type Contestant = {
+    name: string;
+    /** the program to run (resolved through PATH; on Windows .cmd and .ps1 shims work too) */ command: string;
+    /** arguments; the placeholders {task} {cwd} {model} {verify} are replaced */ args?: string[];
+    /** send the prompt on standard input instead of in an argument (recommended: no quoting problems) */ stdin?: boolean;
+    model?: string;
+    env?: Record<string, string>; /** how to read tokens and cost from the output */
+    parse?: ParseMode;
+    /** kill the run after this many seconds (default: the bench's timeout) */ timeoutSec?: number;
+    /** a note shown in the report, for example "uses my Claude login, loads my CLAUDE.md" */ note?: string;
+};
+export type BenchConfig = {
+    contestants: Contestant[];
+    /** the prompt given to every contestant; {task} is the task text, {verify} the check command the task offers (default below) */ promptTemplate?: string;
+    /** make a git repository in each task folder first (agents often expect one; default true) */ gitInit?: boolean;
+    timeoutSec?: number;
+    trials?: number;
+    jobs?: number; /** where to keep each run's raw output for audit */
+    logDir?: string;
+};
+export declare const DEFAULT_PROMPT = "{task}\n\nWhen you believe you are done, check your work by running: {verify}";
+export declare const PRESETS: Record<string, (o: {
+    model?: string;
+    amnessCli?: string;
+}) => Contestant>;
+export type ParsedUsage = {
+    input?: number;
+    output?: number;
+    cached?: number;
+    costUsd?: number;
+    turns?: number;
+    text?: string;
+    isError?: boolean;
+};
+export declare function parseOutput(mode: ParseMode | undefined, stdout: string): ParsedUsage;
+/** Quote an argument for cmd.exe / a POSIX shell when a shell is needed (Windows .cmd shims). */
+export declare const shellQuote: (a: string, win?: boolean) => string;
+export declare function commandLine(c: Contestant, vars: Record<string, string>): {
+    file: string;
+    args: string[];
+};
+export type ContestantRun = {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    ms: number;
+    timedOut: boolean;
+    startError?: string;
+};
+export declare function runContestant(c: Contestant, vars: Record<string, string>, prompt: string, cwd: string, timeoutSec: number): Promise<ContestantRun>;
+export type BenchProgress = (r: Row & {
+    stderrTail?: string;
+}) => void;
+export declare function bench(cases: Case[], cfg: BenchConfig, o?: {
+    onRow?: BenchProgress;
+    baseline?: string;
+    seed?: number;
+}): Promise<{
+    rows: Row[];
+    analysis: Analysis;
+}>;
+/** What each contestant would run, with the prompt, without running anything. */
+export declare function describePlan(cases: Case[], cfg: BenchConfig): string[];
+export declare const installed: (command: string) => boolean;
+export declare const configFileTemplate: (amnessCli?: string) => BenchConfig;

package/dist/src/bench.js

@@ -0,0 +1,201 @@
+// Bake-off: run the same tasks through different coding-agent CLIs (Amness, Claude Code, Codex, anything with a command line) and grade every result with the same hidden check.
+// What it can say honestly: pass rate with a confidence range, cost, tokens and time per solved task. What it cannot do: make the contestants equal. Prompts, tools, default models and
+// permissions differ, so the report names every setting that was used. Each contestant is described as data (a command template), so you can change anything, and add your own.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { analyze } from "./evals.js";
+import { runShell } from "./code.js";
+export const DEFAULT_PROMPT = "{task}\n\nWhen you believe you are done, check your work by running: {verify}";
+// ------------------------------------------------------------------ presets (verify the flags with your installed version: `claude --help`, `codex exec --help`)
+export const PRESETS = {
+    amness: ({ model, amnessCli }) => ({ name: "amness", command: "node", args: [amnessCli ?? resolve(dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")), "..", "cli", "amness.ts"), "run", "--json", "--yes", "--max-tokens", "400000", ...(model ? ["--model", model] : []), "-"], stdin: true, parse: "amness-json", model, note: "headless `amness run`; the default harness without a finish gate" }),
+    "amness-gate": ({ model, amnessCli }) => ({ ...PRESETS.amness({ model, amnessCli }), name: "amness-gate", args: [...PRESETS.amness({ model, amnessCli }).args.slice(0, -1), "--verify", "{verify}", "-"], note: "headless `amness run` with --verify: it may not finish until the check passes (the other contestants only get the check in the prompt)" }),
+    claude: ({ model }) => ({ name: "claude", command: "claude", args: ["-p", "--output-format", "json", "--permission-mode", "acceptEdits", "--allowedTools", "Bash,Read,Edit,Write", ...(model ? ["--model", model] : [])], stdin: true, parse: "claude-json", model, note: "Claude Code print mode with YOUR login, settings, CLAUDE.md and hooks (use claude-bare for a clean room)" }),
+    "claude-bare": ({ model }) => ({ name: "claude-bare", command: "claude", args: ["--bare", "-p", "--output-format", "json", "--permission-mode", "acceptEdits", "--allowedTools", "Bash,Read,Edit,Write", ...(model ? ["--model", model] : [])], stdin: true, parse: "claude-json", model, note: "Claude Code --bare: no user settings, hooks, CLAUDE.md or memory; needs ANTHROPIC_API_KEY (no subscription login)" }),
+    codex: ({ model }) => ({ name: "codex", command: "codex", args: ["exec", "--json", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--sandbox", "workspace-write", ...(model ? ["--model", model] : []), "-"], stdin: true, parse: "codex-jsonl", model, note: "codex exec in a workspace-write sandbox, ignoring your user config and rules" }),
+};
+const jsonLines = (s) => s.split(/\r?\n/).flatMap((l) => { const t = l.trim(); if (!t.startsWith("{") && !t.startsWith("["))
+    return []; try {
+    return [JSON.parse(t)];
+}
+catch {
+    return [];
+} });
+const num = (x) => (typeof x === "number" && Number.isFinite(x) ? x : undefined);
+export function parseOutput(mode, stdout) {
+    if (!mode || mode === "none")
+        return {};
+    if (mode === "claude-json") {
+        // one JSON object (print mode), or a stream whose last line is the result message
+        let objs = jsonLines(stdout);
+        if (!objs.length) {
+            try {
+                objs = [JSON.parse(stdout)];
+            }
+            catch {
+                return {};
+            }
+        }
+        const r = [...objs.flat()].reverse().find((o) => o && (o.type === "result" || "total_cost_usd" in o)) ?? objs.at(-1) ?? {}, u = r.usage ?? {};
+        const cached = (num(u.cache_read_input_tokens) ?? 0), fresh = (num(u.input_tokens) ?? 0) + (num(u.cache_creation_input_tokens) ?? 0);
+        return { input: fresh + cached, cached, output: num(u.output_tokens), costUsd: num(r.total_cost_usd), turns: num(r.num_turns), text: typeof r.result === "string" ? r.result : undefined, isError: !!r.is_error };
+    }
+    if (mode === "amness-json") {
+        const r = [...jsonLines(stdout)].reverse().find((o) => o.kind === "result");
+        return r ? { input: num(r.tokens), output: undefined, turns: num(r.steps), text: typeof r.text === "string" ? r.text : undefined, isError: r.finished === false } : {};
+    }
+    // codex-jsonl: the token event is not documented, so this reads what is commonly there: a cumulative `total_token_usage` (last one wins), else the sum of per-turn `usage` objects.
+    let total, sum = { i: 0, o: 0, c: 0 }, any = false, text;
+    const walk = (x) => {
+        if (!x || typeof x !== "object")
+            return;
+        if (x.total_token_usage && typeof x.total_token_usage === "object")
+            total = x.total_token_usage;
+        else if (x.usage && typeof x.usage === "object" && (num(x.usage.input_tokens) !== undefined || num(x.usage.output_tokens) !== undefined)) {
+            any = true;
+            sum.i += num(x.usage.input_tokens) ?? 0;
+            sum.o += num(x.usage.output_tokens) ?? 0;
+            sum.c += num(x.usage.cached_input_tokens) ?? 0;
+        }
+        if ((x.type === "agent_message" || x.item?.type === "agent_message") && typeof (x.text ?? x.item?.text) === "string")
+            text = x.text ?? x.item.text;
+        for (const v of Object.values(x))
+            if (v && typeof v === "object")
+                walk(v);
+    };
+    for (const o of jsonLines(stdout))
+        walk(o);
+    if (total)
+        return { input: num(total.input_tokens), output: num(total.output_tokens), cached: num(total.cached_input_tokens), text };
+    return any ? { input: sum.i, output: sum.o, cached: sum.c, text } : { text };
+}
+// ------------------------------------------------------------------ running one contestant
+/** Quote an argument for cmd.exe / a POSIX shell when a shell is needed (Windows .cmd shims). */
+export const shellQuote = (a, win = process.platform === "win32") => (win ? (/^[\w@%+=:,./\\-]+$/.test(a) ? a : `"${a.replace(/"/g, '\\"')}"`) : a);
+const fill = (s, v) => s.replace(/\{(task|cwd|model|verify)\}/g, (_, k) => v[k] ?? "");
+export function commandLine(c, vars) { return { file: c.command, args: (c.args ?? []).map((a) => fill(a, vars)) }; }
+function killTree(p) {
+    if (!p.pid)
+        return;
+    try {
+        if (process.platform === "win32")
+            spawnSync("taskkill", ["/pid", String(p.pid), "/T", "/F"], { stdio: "ignore" });
+        else
+            process.kill(-p.pid, "SIGKILL");
+    }
+    catch {
+        try {
+            p.kill("SIGKILL");
+        }
+        catch { /* gone */ }
+    }
+}
+export function runContestant(c, vars, prompt, cwd, timeoutSec) {
+    const { file, args } = commandLine(c, vars), win = process.platform === "win32", t0 = Date.now();
+    return new Promise((res) => {
+        let out = "", err = "", timedOut = false, done = false;
+        const p = spawn(file, win ? args.map((a) => shellQuote(a, true)) : args, { cwd, env: { ...process.env, ...c.env }, shell: win, detached: !win, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        const finish = (r) => { if (done)
+            return; done = true; clearTimeout(timer); res({ code: null, stdout: out, stderr: err, ms: Date.now() - t0, timedOut, ...r }); };
+        const timer = setTimeout(() => { timedOut = true; killTree(p); setTimeout(() => finish({ code: null }), 2000).unref(); }, timeoutSec * 1000);
+        p.stdout.on("data", (d) => { if (out.length < 20_000_000)
+            out += d; });
+        p.stderr.on("data", (d) => { if (err.length < 2_000_000)
+            err += d; });
+        p.on("error", (e) => finish({ startError: e.message }));
+        p.on("close", (code) => finish({ code }));
+        p.stdin.on("error", () => { });
+        if (c.stdin)
+            p.stdin.end(prompt);
+        else
+            p.stdin.end();
+    });
+}
+export async function bench(cases, cfg, o = {}) {
+    const rows = [], trials = cfg.trials ?? 1, template = cfg.promptTemplate ?? DEFAULT_PROMPT, logRoot = cfg.logDir ? resolve(cfg.logDir) : undefined;
+    const work = [];
+    for (const c of cases)
+        for (const k of cfg.contestants)
+            for (let trial = 0; trial < trials; trial++)
+                work.push(async () => {
+                    const dir = mkdtempSync(join(tmpdir(), "amness-bench-")), t0 = Date.now(), row = { case: c.name, variant: k.name, trial, pass: false, steps: 0, tokens: 0, ms: 0 };
+                    try {
+                        for (const [f, content] of Object.entries(c.files)) {
+                            mkdirSync(dirname(join(dir, f)), { recursive: true });
+                            writeFileSync(join(dir, f), content);
+                        }
+                        if (c.setup) {
+                            try {
+                                await c.setup(dir);
+                            }
+                            catch (e) {
+                                row.excluded = e.message.slice(0, 300);
+                                rows.push(row);
+                                o.onRow?.(row);
+                                return;
+                            }
+                        }
+                        if (cfg.gitInit !== false) {
+                            const g = (...a) => spawnSync("git", a, { cwd: dir, stdio: "ignore" });
+                            g("init", "-q");
+                            g("add", "-A");
+                            g("-c", "user.email=bench@example.com", "-c", "user.name=bench", "commit", "-qm", "start", "--allow-empty");
+                        }
+                        const verify = c.verify ?? "(no check command was given for this task)", vars = { task: c.task, cwd: dir, model: k.model ?? "", verify }, prompt = fill(template, vars);
+                        const r = await runContestant(k, vars, prompt, dir, k.timeoutSec ?? cfg.timeoutSec ?? 900), u = parseOutput(k.parse, r.stdout);
+                        row.ms = r.ms;
+                        row.steps = u.turns ?? 0;
+                        row.tokens = (u.input ?? 0) + (u.output ?? 0);
+                        row.prompt = u.input;
+                        row.cached = u.cached;
+                        const j = typeof c.check === "string" ? ((await runShell(c.check, dir, 120_000)).startsWith("exit=0") || "check command failed") : await c.check(dir);
+                        row.pass = j === true;
+                        row.metrics = { ...(u.costUsd !== undefined && { "cost-usd": u.costUsd }), secs: r.ms / 1000 };
+                        row.note = r.startError ? `could not start ${k.command}: ${r.startError}` : r.timedOut ? `timed out after ${k.timeoutSec ?? cfg.timeoutSec ?? 900}s` : j !== true ? String(j || "failed") : u.isError ? "the tool reported an error but the check passed" : undefined;
+                        if (logRoot) {
+                            const f = join(logRoot, k.name, `${c.name}-${trial}`);
+                            mkdirSync(dirname(f), { recursive: true });
+                            writeFileSync(f + ".out.txt", r.stdout);
+                            writeFileSync(f + ".err.txt", r.stderr);
+                            writeFileSync(f + ".cmd.json", JSON.stringify({ command: k.command, args: commandLine(k, vars).args, exit: r.code, ms: r.ms, usage: u, check: j }, null, 1));
+                        }
+                        void t0;
+                    }
+                    catch (e) {
+                        row.note = "crashed: " + e.message;
+                    }
+                    rows.push(row);
+                    o.onRow?.(row);
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                    catch { /* a leftover temp folder is harmless */ }
+                });
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(cfg.jobs ?? 1, work.length)) }, async () => { while (next < work.length)
+        await work[next++](); }));
+    rows.sort((a, b) => cases.findIndex((x) => x.name === a.case) - cases.findIndex((x) => x.name === b.case) || cfg.contestants.findIndex((x) => x.name === a.variant) - cfg.contestants.findIndex((x) => x.name === b.variant) || a.trial - b.trial);
+    return { rows, analysis: analyze(rows, { baseline: o.baseline, k: Math.min(3, trials), seed: o.seed }) };
+}
+/** What each contestant would run, with the prompt, without running anything. */
+export function describePlan(cases, cfg) {
+    const out = [], c = cases[0];
+    if (!c)
+        return ["no tasks"];
+    const verify = c.verify ?? "(no check command)", template = cfg.promptTemplate ?? DEFAULT_PROMPT;
+    out.push(`${cases.length} task(s) × ${cfg.contestants.length} contestant(s) × ${cfg.trials ?? 1} trial(s) = ${cases.length * cfg.contestants.length * (cfg.trials ?? 1)} runs, up to ${cfg.timeoutSec ?? 900}s each, ${cfg.jobs ?? 1} at a time`);
+    out.push("", "prompt for the first task:", ...fill(template, { task: c.task, verify, cwd: "<dir>", model: "" }).split("\n").map((l) => "  " + l), "");
+    for (const k of cfg.contestants) {
+        const { file, args } = commandLine(k, { task: c.task, cwd: "<dir>", model: k.model ?? "", verify });
+        out.push(`${k.name}: ${[file, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")}${k.stdin ? "   (prompt on stdin)" : ""}${k.model ? `   model: ${k.model}` : "   model: the tool's default"}`, ...(k.note ? [`    ${k.note}`] : []));
+    }
+    return out;
+}
+export const installed = (command) => { const r = spawnSync(process.platform === "win32" ? "where" : "which", [command], { stdio: "ignore" }); return r.status === 0; };
+export const configFileTemplate = (amnessCli) => ({
+    contestants: [PRESETS.amness({ amnessCli }), PRESETS["amness-gate"]({ amnessCli }), PRESETS.claude({}), PRESETS.codex({})],
+    promptTemplate: DEFAULT_PROMPT, gitInit: true, timeoutSec: 900, trials: 3, jobs: 2, logDir: ".amness/bench/logs",
+});
+void existsSync;

package/dist/src/bundle.d.ts

@@ -0,0 +1,36 @@
+import type { MemoryEntry, MemoryStore } from "./memory.ts";
+/**
+ * A portable session: provider-neutral JSON you can move to another machine, repo checkout or model.
+ * It deliberately carries a handoff note + memory + the files the agent changed, not a raw transcript, because transcripts
+ * are provider-specific (thinking blocks, tool-call formats) while a handoff note works anywhere.
+ */
+export type Bundle = {
+    schema: "amness.session/1";
+    createdAt: string;
+    task: string;
+    status: {
+        finished: boolean;
+        summary: string;
+    };
+    handoff: string;
+    memory: MemoryEntry[];
+    files: Record<string, string>;
+    from: {
+        provider?: string;
+        model?: string;
+        cwd?: string;
+    };
+};
+export declare function collectFiles(cwd: string, paths: Iterable<string>): Record<string, string>;
+export declare const writeBundle: (path: string, b: Bundle) => string;
+export declare function readBundle(path: string): Bundle;
+/** Restore a bundle into `cwd`. Never overwrites a differing file unless asked; never writes outside `cwd`. */
+export declare function applyBundle(b: Bundle, o: {
+    cwd: string;
+    memory?: MemoryStore;
+    overwrite?: boolean;
+}): {
+    restored: string[];
+    skipped: string[];
+    memory: number;
+};

package/dist/src/bundle.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, normalize, resolve, sep } from "node:path";
+const MAX_FILE = 200_000, MAX_TOTAL = 2_000_000;
+export function collectFiles(cwd, paths) {
+    const files = {};
+    let total = 0;
+    for (const p of paths) {
+        const abs = resolve(cwd, p);
+        if (!existsSync(abs) || !statSync(abs).isFile() || statSync(abs).size > MAX_FILE || total + statSync(abs).size > MAX_TOTAL)
+            continue;
+        const text = readFileSync(abs, "utf8");
+        if (text.includes("\0"))
+            continue; // binary
+        files[normalize(p).replace(/\\/g, "/")] = text;
+        total += text.length;
+    }
+    return files;
+}
+export const writeBundle = (path, b) => { mkdirSync(dirname(resolve(path)), { recursive: true }); writeFileSync(path, JSON.stringify(b, null, 2)); return path; };
+export function readBundle(path) {
+    const b = JSON.parse(readFileSync(path, "utf8"));
+    if (b?.schema !== "amness.session/1" || typeof b.handoff !== "string" || typeof b.task !== "string")
+        throw new Error(`${path} is not an Amness session bundle`);
+    return b;
+}
+/** Restore a bundle into `cwd`. Never overwrites a differing file unless asked; never writes outside `cwd`. */
+export function applyBundle(b, o) {
+    const root = resolve(o.cwd), restored = [], skipped = [];
+    for (const [rel, content] of Object.entries(b.files)) {
+        const abs = resolve(root, rel);
+        if (isAbsolute(rel) || (abs !== root && !abs.startsWith(root + sep))) {
+            skipped.push(`${rel} (outside workspace)`);
+            continue;
+        }
+        if (existsSync(abs) && readFileSync(abs, "utf8") !== content && !o.overwrite) {
+            skipped.push(`${rel} (differs; kept yours)`);
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+        restored.push(rel);
+    }
+    let memory = 0;
+    if (o.memory)
+        for (const e of b.memory) {
+            if (o.memory.list().some((x) => x.name === e.name && x.scope === e.scope))
+                continue;
+            try {
+                o.memory.save(e);
+                memory++;
+            }
+            catch { /* skip invalid entries */ }
+        }
+    return { restored, skipped, memory };
+}

package/dist/src/chaos.d.ts

@@ -0,0 +1,15 @@
+import type { Model, Tool } from "./harness.ts";
+export type ChaosKind = "tools" | "429" | "args" | "slow-tools";
+export declare const CHAOS_KINDS: ChaosKind[];
+/** Make some tool calls fail with an error the model has to read and work around (never the finish tool). */
+export declare function chaosTools(tools: Tool[], o?: {
+    rate?: number;
+    seed?: number;
+    delayMs?: number;
+}): Tool[];
+/** Make some model calls fail with a recoverable 429 and Retry-After (the rate limiter should absorb it), or answer with broken tool arguments (the harness should ask for a fix). */
+export declare function chaosModel(model: Model, o: {
+    kind: "429" | "args";
+    rate?: number;
+    seed?: number;
+}): Model;

package/dist/src/chaos.js

@@ -0,0 +1,26 @@
+import { rng } from "./stats.js";
+export const CHAOS_KINDS = ["tools", "429", "args", "slow-tools"];
+/** Make some tool calls fail with an error the model has to read and work around (never the finish tool). */
+export function chaosTools(tools, o = {}) {
+    const r = rng(o.seed ?? 1), rate = o.rate ?? 0.25;
+    return tools.map((t) => ({ ...t, run: async (a, c) => {
+            if (o.delayMs)
+                await new Promise((res) => setTimeout(res, o.delayMs));
+            if (r() < rate)
+                return `ERROR: simulated failure in ${t.name} (chaos test): try again or use another approach`;
+            return t.run(a, c);
+        } }));
+}
+/** Make some model calls fail with a recoverable 429 and Retry-After (the rate limiter should absorb it), or answer with broken tool arguments (the harness should ask for a fix). */
+export function chaosModel(model, o) {
+    const r = rng(o.seed ?? 1), rate = o.rate ?? 0.3;
+    const call = (async (messages, tools, opts) => {
+        if (o.kind === "429" && r() < rate)
+            throw Object.assign(new Error("HTTP 429: rate limit reached (chaos test)"), { status: 429, retryAfterMs: 50 });
+        const m = await model(messages, tools, opts);
+        if (o.kind === "args" && m.tool_calls?.length && r() < rate)
+            return { ...m, tool_calls: m.tool_calls.map((c) => ({ ...c, function: { ...c.function, arguments: (c.function.arguments || "{}").slice(0, -1) } })) }; // truncated JSON
+        return m;
+    });
+    return Object.assign(call, model);
+}

package/dist/src/code.d.ts

@@ -0,0 +1,187 @@
+import { type SandboxMode } from "./sandbox.ts";
+import { type Bundle } from "./bundle.ts";
+import { Registry, type Approve, type Budget, type Event, type Guard, type Message, type Model, type Tool } from "./harness.ts";
+import { MemoryStore, type MemoryBackend } from "./memory.ts";
+import type { Embedder } from "./embed.ts";
+import { Guidance } from "./guidance.ts";
+import { ProcessManager } from "./procs.ts";
+import { Diagnostics, type LspServer } from "./lsp.ts";
+import { CodeIndex } from "./codeindex.ts";
+import { type AgentDef } from "./agents.ts";
+import type { Roles } from "./route.ts";
+import { type Skill } from "./skills.ts";
+import type { HookRunner } from "./hooks.ts";
+import { type Plugin } from "./plugins.ts";
+import { type PermissionChecker } from "./permissions.ts";
+export declare const riskOf: (cmd: string) => string | false;
+/** How much the agent may do without asking. default: ask for edits and non-trivial shell; acceptEdits: ask only for shell; plan: read-only; yolo: never ask. */
+export type PermMode = "default" | "acceptEdits" | "plan" | "yolo";
+/** Inspection-only shell commands (no chaining, redirects or substitutions): always allowed, even in plan mode. */
+export declare const READONLY_CMD: RegExp;
+/** Explain "command not found" (exit 127): the name is not a program here, and say so when it is really one of the agent's own tools. */
+export declare function withNotFoundHint(out: string, isTool?: (name: string) => boolean, forUser?: boolean): string;
+export declare function runShell(cmd: string, cwd: string, ms?: number, signal?: AbortSignal, sandbox?: SandboxMode): Promise<string>;
+/** File + shell tools confined to `cwd`. Enforces read-before-edit; flags dangerous shell commands as risky. */
+export declare function codeTools(cwd: string, o?: {
+    beforeShell?: (cmd: string) => Promise<void>; /** OS sandbox for shell commands, read each time so it can be switched live */
+    sandbox?: () => SandboxMode; /** background processes (sh_start, sh_read, sh_stop, sh_list) */
+    procs?: ProcessManager; /** folder-level instruction files, appended to results the first time the agent works in that folder */
+    guidance?: Guidance;
+    onChange?: (path: string) => void;
+    mode?: () => PermMode; /** Run after each successful edit; returns text to append to the tool result (empty when all is well). */
+    check?: (paths: string[]) => Promise<string>;
+}): Tool[];
+export declare const CODE_SYSTEM = "You are an expert software engineer working autonomously in a repository. Complete the task, then call `finish`.\nWorkflow:\n1. EXPLORE (proportionate: a small fix needs a handful of reads, not a survey; stop when you know where to change): list_files / grep / read_file to understand the code before changing it. Reproduce the problem or run the existing tests first when possible.\n2. EDIT: smallest correct change, matching surrounding style. Prefer edit_file over rewriting files (several replacements in one file: its `edits` list); use apply_patch when one change spans several files. Do not touch unrelated code. Never edit tests to make them pass unless the task says so.\n3. VERIFY: run the tests/build/command that proves it works. Read failures carefully and fix the root cause. If an approach fails twice, rethink.\n4. FINISH: `finish(summary)` with what changed, how you verified, and assumptions. It is rejected if verification fails.\nMEMORY: notes from earlier sessions may appear below the task; treat them as hints to verify. When you learn something durable that is NOT obvious from the code (the real test command, a convention the user insists on, a correction), save it with memory_save. Never save secrets or task-progress chatter.\nNever invent file contents or command output. Don't ask the user questions; choose sensible defaults. Some commands need human approval; if denied, use another route.";
+/** Conversational variant of the prompt: answers questions directly, plans, delegates exploration, works within permission modes. */
+export declare const CHAT_SYSTEM = "You are an expert software engineer pair-programming with the user in their terminal, inside their repository. Be concise and direct; format with Markdown (short paragraphs, `inline code`, fenced code blocks).\nHow to work:\n- Questions: answer from the code. Explore first (list_files, grep, read_file; in a large repository start with repo_map, find_refs and impact when you have them) instead of guessing; cite files as path:line. Use the `task` tool for broad searches so your own context stays clean.\n- Effort: match effort to the question. A fact or one-file question: 3-10 tool calls, no subagent. Comparing or tracing a few things: 10-15 calls. Only a genuinely broad survey justifies `task`, and then give each subagent a distinct slice. When your budget notes say it is running low, stop exploring and give the best answer you have, saying what you did not cover.\n- Changes: read a file before editing it, make the smallest correct change, then verify it (run the tests/build). For anything with 3+ steps, keep a checklist with `todo_write` and update it as you go (exactly one item in_progress).\n- When you finish a coding task, call `finish(summary)` (what changed, how you verified). For plain questions just answer; no `finish` needed.\n- Permissions: the user may be asked to approve edits and shell commands. If a call is denied, do not retry it; use another approach or explain what you need. In plan mode you are read-only: investigate, then present a plan with `exit_plan_mode` and wait for approval.\n- If the request is ambiguous in a way that matters, ask ONE short clarifying question; otherwise choose sensible defaults and say what you assumed.\n- Notes from earlier sessions may appear below the user's message; treat them as hints to verify. Save durable, non-obvious lessons with memory_save (never secrets).\n- Servers and watchers: start them with `sh_start` (plain `sh` waits for the command to end), read their output with `sh_read`, and `sh_stop` them when you are done.\n- Never invent file contents or command output. The user can type while you work; their new messages arrive between your steps, so adjust course when they do.";
+export type CodeAgentOptions = {
+    /** Conversational mode (the TUI): chat prompt, plus todo_write, task (read-only explorer subagent) and exit_plan_mode tools. */
+    chat?: boolean;
+    /** Live permission mode. When given, edits and shell commands ask for approval per the mode (see PermMode); omit for the autonomous behaviour. */
+    permissions?: {
+        mode: () => PermMode;
+    };
+    /** Polled every turn for messages the user typed while the agent works. */
+    inbox?: () => string[];
+    model: Model;
+    cwd: string;
+    /** Shell command that must exit 0 (e.g. "npm test") before `finish` is accepted. */
+    verify?: string;
+    /** Fast command (typecheck, lint) run after every edit. Only a failure is shown to the model, appended to the edit result, so mistakes are caught one step after they happen. */
+    check?: string;
+    /** Ask an installed language server (typescript-language-server, pyright, gopls, rust-analyzer) for errors in each file after it is edited, and append them to the edit result. Pass servers to override the defaults. Off by default. */
+    lsp?: boolean | {
+        servers?: LspServer[];
+    };
+    approve?: Approve;
+    budget?: Budget;
+    maxSteps?: number;
+    tools?: Tool[];
+    /** Let the agent define its own shell-backed tools (each creation needs approval). Saved to `.amness/tools.json` and reloaded next run. */
+    selfExtend?: boolean;
+    off?: Guard[];
+    onEvent?: (e: Event) => void;
+    /** Persist transcript here after every turn; run(task, {resume:true}) continues from it. */
+    checkpointFile?: string;
+    /** Durable memory across sessions (markdown files in <cwd>/.amness/memory + ~/.amness/memory). Default on. */
+    memory?: boolean | MemoryStore | MemoryBackend;
+    /** Load AGENTS.md (or CLAUDE.md / GEMINI.md) from the workspace root and from folders the agent works in. Default on. */
+    guidance?: boolean;
+    /** Called before a command that may change files runs: take a snapshot, note that it cannot be undone. */
+    beforeShell?: (cmd: string) => Promise<void>;
+    /** Mask secrets in tool output before the model sees it (default on). */
+    redact?: boolean;
+    /** Commands that contain text copied from untrusted tool results (web pages, MCP servers): "ask" (default), "deny" or "off". */
+    taint?: "ask" | "deny" | "off";
+    /** Record full messages in events so a trace can be replayed (`replay`). */
+    record?: boolean;
+    /** Structural code index tools (repo_map, find_refs, impact), offered when the repository has at least `minFiles` source files (default 25). */
+    index?: boolean | {
+        minFiles?: number;
+    };
+    /** Discover custom subagents (.amness/agents/*.md, .claude/agents/*.md; project and home) for the `task` tool. Default on. */
+    agents?: boolean;
+    /** Models that agents can name in their front matter (`model: fast`). */
+    agentModels?: Record<string, Model>;
+    /** Different models for different jobs: `explore` (the read-only explorer), `compact` (handoff notes and /compact), `review` (the independent reviewer). Unset roles use `model`. */
+    models?: Roles;
+    /** Discover SKILL.md folders (.amness/skills, .agents/skills, .claude/skills; project and home) and offer them through the `skill` tool. Default on. */
+    skills?: boolean;
+    /** Run shell commands under an OS sandbox: "workspace" (writes only in the project and temp/cache folders, `.git` read-only) or "strict" (also no network). A getter lets you switch it live. */
+    sandbox?: SandboxMode | (() => SandboxMode);
+    /** An independent, skeptical reviewer (a fresh context that cannot edit): it writes acceptance criteria before the work and checks the result against them before a finish is accepted. Costs extra model calls; off by default. `model` lets it be a different model. */
+    review?: boolean | {
+        model?: Model;
+    };
+    /** A second model looks at each risky call before the user is asked: it can approve (with a stated reason, logged as a policy event) or pass the call on. It never sees the safety floor or untrusted-text calls. Pass { model } to use a cheaper model. Costs one short model call per risky action. */
+    approvalReviewer?: boolean | {
+        model?: Model;
+    };
+    /** Turns without any measurable improvement before the loop reflects and then stops (default 8; 0 = off). */
+    stagnationTurns?: number;
+    /** Background process tools (sh_start / sh_read / sh_stop / sh_list). Default on. Call `agent.procs?.dispose()` when you are done. */
+    background?: boolean;
+    /** Lifecycle hooks, e.g. `Hooks.load(cwd, { trustProject: true })`. Nothing runs unless you pass this. */
+    hooks?: HookRunner;
+    /** Create a model from an id (same provider): needed for plugins that route requests with `route`. */
+    modelById?: (id: string) => Model;
+    /** Wrap or replace every tool the agent gets (chaos evals use it to make tools fail on purpose). */
+    wrapTools?: (tools: Tool[]) => Tool[];
+    /** Plugins (see plugins.ts): extra tools, in-process hooks on every loop event, system-prompt rewrites. */
+    plugins?: Plugin[];
+    /** Permission rules plus the built-in safety floor (see `Permissions`). Default: the floor alone. Pass `false` to switch even that off. */
+    rules?: PermissionChecker | false;
+    /** Turns on semantic memory retrieval (blended with keyword ranking). See `openaiEmbedder`. */
+    embedder?: Embedder;
+    /** Start a fresh context with a handoff note when the transcript gets big. Default: at 120k prompt tokens / 500k chars. */
+    rollover?: {
+        afterTokens?: number;
+        afterChars?: number;
+    } | false;
+    /** Interrupt a running agent (e.g. Ctrl-C). It stops at a safe point with the checkpoint written, so it can be resumed. */
+    signal?: AbortSignal | (() => AbortSignal | undefined);
+    /** Recorded in exported bundles so you can see where a session came from. */
+    meta?: {
+        provider?: string;
+        model?: string;
+    };
+};
+export type RunOptions = {
+    images?: {
+        mime: string;
+        data: string;
+    }[];
+    resume?: boolean;
+    bundle?: Bundle | string;
+    overwrite?: boolean;
+};
+export declare function createCodeAgent(o: CodeAgentOptions): {
+    /** The live toolbox: add/remove tools between or during runs. */
+    registry: Registry;
+    memory: MemoryStore | undefined;
+    guidance: Guidance | undefined;
+    procs: ProcessManager | undefined;
+    lsp: Diagnostics | undefined;
+    codeIndex: CodeIndex | undefined;
+    readonly agents: AgentDef[];
+    readonly agentWarnings: string[];
+    readonly skills: Skill[];
+    readonly skillWarnings: string[];
+    /** Keep the provider's prompt cache alive across an idle gap (see createHarness().warm). */
+    warm: (msgs: Message[], opts?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        prompt: number;
+        cached: number;
+    }>;
+    readonly todos: {
+        content: string;
+        status: "pending" | "in_progress" | "done";
+    }[];
+    /** One conversational turn: `history` is everything so far (empty to start); returns the updated transcript in `messages`. */
+    chat(history: Message[], userText: string, extra?: {
+        images?: {
+            mime: string;
+            data: string;
+        }[];
+    }): Promise<import("./harness.ts").RunResult>;
+    run(t: string, opts?: RunOptions): Promise<import("./harness.ts").RunResult>;
+    /** Keep talking to the agent after it finished (or stopped): same conversation, full context. */
+    followUp(prev: {
+        messages: Message[];
+    }, text: string): Promise<import("./harness.ts").RunResult>;
+    /** Replace a long conversation by a model-written handoff note (same mechanism as automatic rollover, on demand). */
+    compact(messages: Message[]): Promise<{
+        messages: Message[];
+        note: string;
+    }>;
+    /** Package the work so far for another machine / model / day. Asks the model for a handoff note unless one is supplied. */
+    exportBundle(result: {
+        messages: Message[];
+        finished: boolean;
+        text: string;
+    }, path?: string, handoff?: string): Promise<{
+        bundle: Bundle;
+        path?: string;
+    }>;
+};