amness 0.0.0-stage → 0.1.0

package/dist/cli/format.js

@@ -0,0 +1,55 @@
+import { bold, cyan, dim, gray, green, magenta, red, yellow, blue } from "./ui.js";
+const one = (s, n = 90) => { const l = s.replace(/\s+/g, " ").trim(); return l.length > n ? l.slice(0, n - 1) + "…" : l; };
+const argSummary = (name, raw) => {
+    try {
+        const a = JSON.parse(raw);
+        return one(a.cmd ?? a.path ?? a.query ?? a.url ?? a.description ?? a.note ?? a.pattern ?? a.summary ?? raw, 80);
+    }
+    catch {
+        return one(raw, 80);
+    }
+};
+const agentColor = (name) => ({ lead: cyan, general: magenta }[name] ?? blue)(name.padEnd(7));
+/** One readable trace line per harness event. */
+export function formatEvent(e) {
+    const who = e.agent ? agentColor(e.agent) + " " : "";
+    switch (e.kind) {
+        case "tool": {
+            const bad = /^(ERROR|DENIED|REJECTED)/.test(e.result) || /^exit=[^0]/.test(e.result);
+            return `${who}${bad ? red("✗") : green("✓")} ${e.name} ${dim(argSummary(e.name, e.args))}${bad ? "  " + red(one(e.result, 70)) : ""}`;
+        }
+        case "nudge": return `${who}${yellow("↻ nudge")} ${dim("model described an action instead of doing it → told to act")}`;
+        case "repair": return `${who}${yellow("⚒ repair")} ${dim("invalid tool call → error returned to model: " + one(e.detail, 70))}`;
+        case "loop": return `${who}${yellow("∞ loop guard")} ${dim("repeated identical call refused")}`;
+        case "rejected": return `${who}${yellow("⛔ finish rejected")} ${dim(one(e.detail, 80))}`;
+        case "denied": return `${who}${red("⊘ denied")} ${dim(e.detail)}`;
+        case "budget": return `${who}${red("$ budget")} ${e.detail}`;
+        case "tools": return `${who}${gray("⚙ toolbox changed")} ${dim(one(e.detail, 70))}`;
+        case "edit": {
+            const body = e.diff.split("\n").filter((l) => !/^(---|\+\+\+)/.test(l));
+            const shown = body.slice(0, 40).map((l) => l.startsWith("+") ? green("    " + l) : l.startsWith("-") ? red("    " + l) : l.startsWith("@@") ? cyan("    " + l) : gray("    " + l));
+            if (body.length > 40)
+                shown.push(dim(`    … ${body.length - 40} more lines`));
+            return `${who}${yellow("✎")} ${bold(e.path)} ${e.created ? green("new file ") : ""}${green("+" + e.added)} ${red("-" + e.removed)}\n${shown.join("\n")}`;
+        }
+        case "aborted": return `${who}${yellow("⏹ stopped")} ${dim("run interrupted; progress is saved and can be resumed")}`;
+        case "turn":
+        case "phase":
+        case "trim":
+        case "cachebreak":
+        case "run":
+        case "model":
+        case "policy":
+        case "toolstart":
+        case "text":
+        case "thinking":
+        case "assistant":
+        case "todos":
+        case "steer": return "";
+        case "rollover": return `${who}${magenta("⟳ context rollover")} ${dim("handoff note written; continuing in a fresh context")}`;
+        case "review": return `${who}${e.pass ? green("✔ review") : yellow("✖ review")} ${dim(e.inconclusive ? "inconclusive (accepted)" : e.pass ? "the reviewer found no problems" : e.findings.slice(0, 2).map((f) => one(f, 70)).join("; "))}`;
+        case "audit": return e.changed.length || e.notes.length ? `${who}${e.notes.length ? yellow("◐ audit") : green("◉ audit")} ${dim(`${e.changed.length} file(s) changed${e.testsAfterLastEdit === true ? " · tests passed after the last edit" : ""}${e.notes.length ? " · " + e.notes.join("; ") : ""}`)}` : "";
+        case "hook": return `${who}${e.blocked ? red("⛔ hook") : yellow("⚙ hook")} ${dim(e.event + ": " + one(e.detail, 90))}`;
+        case "finish": return `${who}${green("✔ finish")} ${dim(one(e.summary, 80))}`;
+    }
+}

package/dist/cli/headless.d.ts

@@ -0,0 +1,2 @@
+export declare const HELP: string;
+export declare function runHeadless(argv: string[]): Promise<number>;

package/dist/cli/headless.js

@@ -0,0 +1,169 @@
+// Non-interactive mode for CI, scripts and containers:  amness run [flags] "task"
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Budget, Tracer, Hooks, Permissions, projectConfigFingerprint, createCodeAgent, startLive, setShell, loadPlugins, readImage, visionLikely, bestOfN, parallelParts, isRepo } from "../src/index.js";
+import { PROVIDERS, loadConfig, ready } from "./config.js";
+import { formatEvent } from "./format.js";
+import { createModel } from "./model.js";
+export const HELP = `usage: amness run [flags] "task"
+  --cwd <dir>          workspace (default .)
+  --verify <cmd>       command that must exit 0 before the agent may finish
+  --trust-project      run this project's .amness/hooks.json and plugins and honour its allow rules (they execute code; off by default in headless runs)
+  --sandbox <mode>     run shell commands under an OS sandbox: workspace (write only in the project and temp folders) or strict (also no network)
+  --review             an independent reviewer writes acceptance criteria first and checks the work before it is accepted (extra model calls)
+  --trace <file>       write a JSONL trace of every loop event (also AMNESS_OTLP=<collector url> for OpenTelemetry export)
+  --approval-reviewer  a second model looks at each risky call first and approves clearly safe ones (without --yes, calls it does not clear are still denied)
+  --check <cmd>        fast command run after every edit; failures are shown to the agent immediately
+  --provider <id>      ${Object.keys(PROVIDERS).join(" | ")}    --model <id>    --base-url <url>    --effort none|low|medium|high|xhigh|max   --api auto|responses|chat
+  --bundle <file>      continue from a portable session bundle (any provider/model)
+  --export <file>      write a portable session bundle when done
+  --yes                auto-approve risky commands (default: deny them)
+  --json               machine-readable: one JSON event per line on stdout, final {"kind":"result"} line
+  --live [port]        serve the live browser view
+  --best-of <n>        attempt the task up to n times in separate git worktrees (stops at the first attempt that passes --verify, which is required); the winner is applied
+  --parts <file.json>  run independent parts ([{"name","task"}]) concurrently in worktrees, merged one at a time through --verify; conflicts are reported, not applied
+  --image <file>       show the model a picture (png, jpg, gif, webp; up to 5 MB, repeat the flag for more, max 4); needs a vision-capable model
+  --max-tokens <n>     hard token cap (default 300000)      --no-memory   disable memory
+  -                    as the task: read it from standard input (useful on Windows, where quoting a long task is painful)
+exit code: 0 finished, 1 not finished, 2 usage/config error`;
+export async function runHeadless(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(HELP);
+        return 0;
+    } // asking for help must never start a model run
+    const args = [...argv];
+    const val = (f) => { const i = args.indexOf(f); return i < 0 ? undefined : args.splice(i, 2)[1]; };
+    const bool = (f) => { const i = args.indexOf(f); return i >= 0 && !!args.splice(i, 1); };
+    const cfg = loadConfig();
+    const provider = val("--provider");
+    if (provider) {
+        if (!(provider in PROVIDERS)) {
+            console.error(`unknown provider ${provider}\n${HELP}`);
+            return 2;
+        }
+        Object.assign(cfg, { provider, baseUrl: PROVIDERS[provider].baseUrl, model: PROVIDERS[provider].model });
+        const k = provider === "anthropic" ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
+        cfg.apiKey = k ?? (loadConfig().provider === provider ? loadConfig().apiKey : undefined);
+    }
+    cfg.model = val("--model") ?? cfg.model;
+    cfg.baseUrl = val("--base-url") ?? cfg.baseUrl;
+    cfg.api = val("--api") ?? cfg.api;
+    cfg.effort = val("--effort") ?? cfg.effort;
+    const cwd = resolve(val("--cwd") ?? "."), verify = val("--verify"), check = val("--check"), bundle = val("--bundle"), exportTo = val("--export");
+    const trustHooks = bool("--trust-project") || bool("--trust-hooks"), yes = bool("--yes"), json = bool("--json"), noMemory = bool("--no-memory");
+    const li = args.indexOf("--live");
+    let livePort;
+    if (li >= 0) {
+        const nxt = args[li + 1];
+        livePort = /^\d+$/.test(nxt ?? "") ? Number(args.splice(li, 2)[1]) : (args.splice(li, 1), 0);
+    }
+    const imagePaths = [];
+    for (let v = val("--image"); v !== undefined; v = val("--image"))
+        imagePaths.push(v);
+    const maxTokens = Number(val("--max-tokens") ?? cfg.maxTokens);
+    let task = args.join(" ").trim();
+    if (task === "-")
+        task = (await new Promise((res) => { let s = ""; process.stdin.setEncoding("utf8"); process.stdin.on("data", (d) => (s += d)); process.stdin.on("end", () => res(s)); })).trim(); // `amness run -` reads the task from stdin (no quoting problems on any shell)
+    if (!task && !bundle) {
+        console.error(HELP);
+        return 2;
+    }
+    if (!ready(cfg)) {
+        console.error(`no API key for ${PROVIDERS[cfg.provider].label}. Set ${cfg.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} or run \`amness settings\`.`);
+        return 2;
+    }
+    if (imagePaths.length && !visionLikely(cfg.provider, cfg.model)) {
+        console.error(`${cfg.model} does not look like a vision model; pick one that accepts images or drop --image`);
+        return 2;
+    }
+    let images;
+    try {
+        images = imagePaths.map((p) => readImage(resolve(p)));
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const live = livePort === undefined ? undefined : await startLive({ port: livePort });
+    if (live)
+        console.error(`live view: ${live.url}`);
+    const approve = yes ? () => true : () => "non-interactive run: risky commands are denied unless --yes is passed";
+    const budget = new Budget({ maxTokens });
+    const model = createModel(cfg);
+    const bestOf = Number(val("--best-of") ?? 0), partsFile = val("--parts");
+    if (bestOf || partsFile) {
+        if (!verify) {
+            console.error("--best-of and --parts need --verify <cmd>: that command is what decides which result is kept");
+            return 2;
+        }
+        if (!(await isRepo(cwd))) {
+            console.error("--best-of and --parts need a git repository with at least one commit");
+            return 2;
+        }
+        try {
+            if (bestOf) {
+                const r = await bestOfN({ repo: cwd, n: bestOf, verify, apply: true, maxTokens, attempt: async (dir) => { const b = new Budget({ maxTokens: Math.max(1, Math.floor(maxTokens / bestOf)) }); const a = createCodeAgent({ model, cwd: dir, verify, approve, sandbox: cfg.sandbox, memory: false, budget: b }); const x = await a.run(task); await a.procs?.dispose(); return { tokens: b.tokens, summary: x.text }; }, onCandidate: (c) => console.error(`attempt ${c.index + 1}: ${c.passed ? "passed verify" : c.error ? "error: " + c.error : "failed verify"} (${c.tokens} tokens)`) });
+                if (json)
+                    console.log(JSON.stringify({ kind: "result", finished: !!r.winner, applied: r.applied, tokens: r.tokens, attempts: r.candidates.length }));
+                else
+                    console.log(r.winner ? `attempt ${r.winner.index + 1} won and was ${r.applied ? "applied" : "NOT applied: " + r.applyError}\n${r.winner.summary ?? ""}` : `no attempt passed ${verify} (${r.candidates.length} tried, ${r.tokens} tokens)`);
+                return r.winner && r.applied ? 0 : 1;
+            }
+            const parts = JSON.parse(readFileSync(resolve(partsFile), "utf8"));
+            const { results, tokens } = await parallelParts({ repo: cwd, parts, verify, maxTokens, attempt: async (p, dir) => { const b = new Budget({ maxTokens: Math.max(1, Math.floor(maxTokens / parts.length)) }); const a = createCodeAgent({ model, cwd: dir, verify, approve, sandbox: cfg.sandbox, memory: false, budget: b }); const x = await a.run(p.task); await a.procs?.dispose(); return { tokens: b.tokens, summary: x.text }; }, onPart: (r) => console.error(`${r.part.name}: ${r.status}${r.detail ? " - " + r.detail.split("\n")[0] : ""}`) });
+            if (json)
+                console.log(JSON.stringify({ kind: "result", tokens, parts: results.map((r) => ({ name: r.part.name, status: r.status })) }));
+            else
+                for (const r of results)
+                    console.log(`${r.status.padEnd(14)} ${r.part.name}`);
+            return results.every((r) => r.status === "merged") ? 0 : 1;
+        }
+        catch (e) {
+            console.error("error: " + e.message);
+            return 1;
+        }
+    }
+    const tracer = val("--trace") || process.env.AMNESS_OTLP ? new Tracer({ file: val("--trace") ? resolve(val("--trace")) : undefined, otlp: process.env.AMNESS_OTLP, sessionId: `run-${Date.now()}`, model: cfg.model }) : undefined;
+    setShell(cfg.shell);
+    const loadedPlugins = await loadPlugins(cwd, { trustProject: trustHooks });
+    for (const w of loadedPlugins.warnings)
+        console.error("plugin: " + w);
+    if (loadedPlugins.untrusted)
+        console.error(`note: ${loadedPlugins.untrusted.count} project plugin file(s) in .amness/plugins were not loaded; pass --trust-project to run them`);
+    const agent = createCodeAgent({
+        model, modelById: (id) => createModel({ ...cfg, model: id }), cwd, verify, plugins: loadedPlugins.plugins.length ? loadedPlugins.plugins : undefined, check, approve, record: !!tracer || undefined, sandbox: val("--sandbox") ?? cfg.sandbox, review: bool("--review") || undefined, approvalReviewer: bool("--approval-reviewer") || undefined, hooks: ((h) => { if (!trustHooks && projectConfigFingerprint(cwd))
+            console.error("note: ignoring the project's hooks and allow rules (pass --trust-project to use them)"); return h.count() ? h : undefined; })(Hooks.load(cwd, { trustProject: trustHooks })), rules: Permissions.load(cwd, { trustProject: trustHooks }), budget, memory: noMemory ? false : undefined, meta: { provider: cfg.provider, model: cfg.model },
+        onEvent: (e) => { live?.onEvent(e); tracer?.event(e); if (json)
+            console.log(JSON.stringify(e));
+        else {
+            const l = formatEvent(e);
+            if (l)
+                console.error(l);
+        } },
+    });
+    try {
+        const r = await agent.run(task, { bundle, images });
+        if (exportTo) {
+            await agent.exportBundle(r, exportTo);
+            console.error(`session bundle: ${exportTo}`);
+        }
+        const out = { kind: "result", finished: r.finished, text: r.text, steps: r.steps, tokens: budget.tokens, stopped: r.stopped };
+        if (json)
+            console.log(JSON.stringify(out));
+        else
+            console.log(r.text);
+        return r.finished ? 0 : 1;
+    }
+    catch (e) {
+        if (json)
+            console.log(JSON.stringify({ kind: "error", message: e.message }));
+        else
+            console.error("error: " + e.message);
+        return 1;
+    }
+    finally {
+        await agent.procs?.dispose();
+        await tracer?.close();
+        await live?.close();
+    }
+}

package/dist/cli/model.d.ts

@@ -0,0 +1,11 @@
+import { type Model } from "../src/index.ts";
+import { type Config } from "./config.ts";
+/** One place for the UI to hear about rate limits, whichever model object hit them. */
+declare let waitListener: ((ms: number, attempt: number, concurrency: number) => void) | undefined;
+export declare const onRateLimitWait: (fn: typeof waitListener) => void;
+/** Build the model for a config (shared by the menu and headless mode). */
+export declare function createModel(cfg: Config, retries?: number, o?: {
+    cacheKey?: string; /** told when a rate limit makes calls wait */
+    onWait?: (ms: number, attempt: number, concurrency: number) => void;
+}): Model;
+export {};

package/dist/cli/model.js

@@ -0,0 +1,19 @@
+import { anthropic, effortsFor, gateFor, openai, rateLimited } from "../src/index.js";
+import { PROVIDERS } from "./config.js";
+/** One place for the UI to hear about rate limits, whichever model object hit them. */
+let waitListener;
+export const onRateLimitWait = (fn) => { waitListener = fn; };
+/** Build the model for a config (shared by the menu and headless mode). */
+export function createModel(cfg, retries, o = {}) {
+    // Every model built for the same endpoint and key shares one gate, so parallel subagents slow down together when the provider says 429.
+    const gate = gateFor(`${cfg.provider}|${cfg.baseUrl}|${(cfg.apiKey ?? "").slice(-6)}`, cfg.maxConcurrent ?? 4);
+    return rateLimited(rawModel(cfg, retries, o), { gate, onWait: (ms, attempt, g) => { o.onWait?.(ms, attempt, g.max); waitListener?.(ms, attempt, g.max); } });
+}
+function rawModel(cfg, retries, o) {
+    return cfg.provider === "anthropic"
+        ? anthropic({ model: cfg.model, apiKey: cfg.apiKey, taskBudget: cfg.taskBudget, effort: cfg.effort && !["none", "minimal"].includes(cfg.effort) ? cfg.effort : undefined, baseUrl: cfg.baseUrl === PROVIDERS.anthropic.baseUrl ? undefined : cfg.baseUrl })
+        : openai({
+            model: cfg.model, apiKey: cfg.apiKey, baseUrl: cfg.baseUrl, retries, api: cfg.api, promptCacheKey: o.cacheKey, compactAt: cfg.compactAt, externalRetry: true,
+            effort: cfg.effort && effortsFor(cfg.model).includes(cfg.effort) ? cfg.effort : undefined, // a value this model does not accept is never sent
+        });
+}

package/dist/cli/plugincli.d.ts

@@ -0,0 +1,2 @@
+export declare const PLUGIN_HELP = "usage: amness plugin <command>\n  new <name>     create .amness/plugins/<name>.ts from a template (never overwrites)\n  policy <traces...> --plugin <file>   replay the tool calls recorded in traces (a file, or a folder such as .amness/traces) through the plugin policies and show what each would allow, ask or deny\n  grade <traces...> [--plugin <file>] [--grader a,b]   score real recorded sessions (a trace file, or a folder such as .amness/traces) with built-in or plugin graders\n  add <file|https-url>   copy a plugin file into .amness/plugins/ (never overwrites) and show what it appears to touch; it still needs your approval the first time you start Amness\n  list           show the plugins that load here (project plugins need --trust-project to be listed as loaded)\nA plugin is a TypeScript file that runs inside Amness: guardrails, loop rules, tools, slash commands and eval variants. See docs/plugins.md.";
+export declare function runPlugin(argv: string[], cwd?: string): Promise<number>;

package/dist/cli/plugincli.js

@@ -0,0 +1,176 @@
+// `amness plugin new <name>` and `amness plugin list`.
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { join, resolve } from "node:path";
+import { scanSource, BUILTIN_GRADERS, gradeSessions, sessionFiles, describeProjectPlugins, checkPolicies, importPlugins, loadPlugins, pluginTemplate, projectPluginDir } from "../src/index.js";
+import { dim, green, red } from "./ui.js";
+export const PLUGIN_HELP = `usage: amness plugin <command>
+  new <name>     create .amness/plugins/<name>.ts from a template (never overwrites)
+  policy <traces...> --plugin <file>   replay the tool calls recorded in traces (a file, or a folder such as .amness/traces) through the plugin policies and show what each would allow, ask or deny
+  grade <traces...> [--plugin <file>] [--grader a,b]   score real recorded sessions (a trace file, or a folder such as .amness/traces) with built-in or plugin graders
+  add <file|https-url>   copy a plugin file into .amness/plugins/ (never overwrites) and show what it appears to touch; it still needs your approval the first time you start Amness
+  list           show the plugins that load here (project plugins need --trust-project to be listed as loaded)
+A plugin is a TypeScript file that runs inside Amness: guardrails, loop rules, tools, slash commands and eval variants. See docs/plugins.md.`;
+export async function runPlugin(argv, cwd = process.cwd()) {
+    const [cmd, name] = argv, root = resolve(cwd);
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        console.log(PLUGIN_HELP);
+        return cmd ? 0 : 2;
+    }
+    if (cmd === "new") {
+        if (!name || !/^[\w.-]{1,40}$/.test(name)) {
+            console.error(red("✗ ") + "give a name made of letters, numbers, . _ - (for example: amness plugin new house-rules)");
+            return 2;
+        }
+        const file = join(projectPluginDir(root), `${name}.ts`);
+        if (existsSync(file)) {
+            console.error(red("✗ ") + `${file} already exists`);
+            return 1;
+        }
+        mkdirSync(projectPluginDir(root), { recursive: true });
+        writeFileSync(file, pluginTemplate(name));
+        console.log(green("created ") + file + "\n" + dim("Start the chat: it will ask you to approve this project plugin. Edit it, then /reload-plugins."));
+        return 0;
+    }
+    if (cmd === "list") {
+        const r = await loadPlugins(root, { trustProject: argv.includes("--trust-project") });
+        for (const p of r.plugins)
+            console.log(`${p.name.padEnd(24)} ${p.description ?? ""}`);
+        for (const w of r.warnings)
+            console.error(red("! ") + w);
+        if (r.untrusted) {
+            console.log(dim(`${r.untrusted.count} project plugin file(s) not loaded (not approved); add --trust-project to load them here. What they appear to touch (a text scan, not a guarantee):`));
+            for (const l of describeProjectPlugins(root))
+                console.log("  " + l);
+        }
+        if (!r.plugins.length && !r.untrusted)
+            console.log("no plugins");
+        return 0;
+    }
+    if (cmd === "add") {
+        if (!name) {
+            console.error(red("✗ ") + "usage: amness plugin add <file or https URL>");
+            return 2;
+        }
+        let text, base;
+        try {
+            if (/^https:\/\//.test(name)) {
+                const r = await fetch(name);
+                if (!r.ok)
+                    throw new Error(`HTTP ${r.status}`);
+                text = await r.text();
+                base = basename(new URL(name).pathname) || "plugin.ts";
+            }
+            else if (/^http:\/\//.test(name)) {
+                console.error(red("✗ ") + "only https URLs are accepted");
+                return 2;
+            }
+            else {
+                text = readFileSync(resolve(name), "utf8");
+                base = basename(name);
+            }
+        }
+        catch (e) {
+            console.error(red("✗ ") + `could not read ${name}: ${e.message}`);
+            return 1;
+        }
+        if (text.length > 300_000) {
+            console.error(red("✗ ") + "that file is too large for a plugin (300 KB limit)");
+            return 1;
+        }
+        if (!/\bexport\s+default\b|\bexport\s*\{[^}]*\bas default\b|module\.exports/.test(text)) {
+            console.error(red("✗ ") + "this does not look like a plugin: it has no `export default`");
+            return 1;
+        }
+        const file = join(projectPluginDir(root), /\.(m?[jt]s)$/.test(base) ? base : base + ".ts");
+        if (existsSync(file)) {
+            console.error(red("✗ ") + `${file} already exists`);
+            return 1;
+        }
+        mkdirSync(projectPluginDir(root), { recursive: true });
+        writeFileSync(file, text);
+        const caps = scanSource(text);
+        console.log(green("added ") + file);
+        console.log(caps.length ? "It appears to: " + caps.map((c) => c.label).join("; ") : "It shows no shell, network, file or environment access (a text scan, not a guarantee).");
+        console.log(dim("Read it before you trust it. Amness asks for your approval the first time it starts in this project."));
+        return 0;
+    }
+    if (cmd === "grade") {
+        const rest = argv.slice(1), take = (f) => { const i = rest.indexOf(f); return i >= 0 ? rest.splice(i, 2)[1] : undefined; };
+        const pluginFiles = (take("--plugin") ?? "").split(",").filter(Boolean), pick = (take("--grader") ?? "").split(",").filter(Boolean), inputs = rest.length ? rest : [join(root, ".amness", "traces")];
+        const graders = { ...BUILTIN_GRADERS };
+        for (const f of pluginFiles) {
+            const r = await importPlugins(f);
+            for (const w of r.warnings)
+                console.error(red("! ") + w);
+            for (const p of r.plugins)
+                Object.assign(graders, p.graders ?? {});
+        }
+        const chosen = pick.length ? Object.fromEntries(pick.map((n) => { if (!graders[n])
+            throw new Error(`unknown grader "${n}". Known: ${Object.keys(graders).join(", ")}`); return [n, graders[n]]; })) : graders;
+        const files = sessionFiles(inputs);
+        if (!files.length) {
+            console.error(red("✗ ") + "no trace files found");
+            return 2;
+        }
+        const reports = await gradeSessions(files, chosen);
+        console.log(`${files.length} session file(s)`);
+        for (const r of reports) {
+            console.log(`${r.grader.padEnd(18)} mean ${Number.isNaN(r.mean) ? "n/a" : (r.mean * 100).toFixed(0) + "%"}  over ${r.sessions} session(s)`);
+            for (const l of r.low)
+                console.log(dim(`   ${(l.score * 100).toFixed(0).padStart(3)}%  ${l.session}  ${l.task.slice(0, 60)}${l.note ? "  - " + l.note : ""}`));
+        }
+        return 0;
+    }
+    if (cmd === "policy") {
+        const rest = argv.slice(1), pi = rest.indexOf("--plugin"), pluginFiles = pi >= 0 ? (rest.splice(pi, 2)[1] ?? "").split(",").filter(Boolean) : [], inputs = rest;
+        if (!pluginFiles.length || !inputs.length) {
+            console.error(red("✗ ") + "usage: amness plugin policy <trace file or folder>... --plugin <file>");
+            return 2;
+        }
+        const plugins = [];
+        for (const f of pluginFiles) {
+            const r = await importPlugins(f);
+            for (const w of r.warnings)
+                console.error(red("! ") + w);
+            plugins.push(...r.plugins);
+        }
+        if (!plugins.some((p) => p.policy)) {
+            console.error(red("✗ ") + "none of these plugins defines a policy");
+            return 2;
+        }
+        const files = inputs.flatMap((p) => (existsSync(p) && statSync(p).isDirectory() ? readdirSync(p).filter((f) => f.endsWith(".jsonl")).map((f) => join(p, f)) : [p]));
+        const tally = { allow: 0, ask: 0, deny: 0, none: 0 }, shown = [];
+        for (const f of files)
+            for (const line of readFileSync(f, "utf8").split("\n")) {
+                if (!line.includes('"tool_calls"'))
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                for (const c of ev.message?.tool_calls ?? []) {
+                    let args = {};
+                    try {
+                        args = JSON.parse(c.function.arguments || "{}");
+                    }
+                    catch { /* keep empty */ }
+                    const d = await checkPolicies(plugins, { tool: c.function.name, args, cwd: root });
+                    tally[d?.action ?? "none"]++;
+                    if (d && d.action !== "allow" && shown.length < 25)
+                        shown.push(`${d.action.padEnd(5)} ${c.function.name} ${JSON.stringify(args).slice(0, 90)}  ${dim(d.reason ?? "")}`);
+                }
+            }
+        console.log(`${files.length} trace file(s): ${tally.deny} denied, ${tally.ask} would ask, ${tally.allow} allowed by the policy, ${tally.none} without an opinion`);
+        for (const s of shown)
+            console.log("  " + s);
+        if (!shown.length)
+            console.log(dim("  nothing was denied or asked"));
+        return 0;
+    }
+    console.error(PLUGIN_HELP);
+    return 2;
+}

package/dist/cli/schedulecli.d.ts

@@ -0,0 +1,2 @@
+export declare const SCHEDULE_HELP = "usage: amness schedule <command>\n  add <name> \"<cron>\" \"<task>\" [--verify <cmd>]   save a recurring task for this project (5-field cron, e.g. \"0 3 * * 1-5\")\n  list                                            show this project's schedules\n  remove <name>                                   delete one\n  install [--write]                               print the crontab lines; with --write, put them in your crontab (only a marked block for this project is touched)\n  uninstall                                       remove this project's block from your crontab\n  Runs are headless (`amness run --json`), risky commands are denied, and each run's output is appended to .amness/schedule-logs/<name>.jsonl.\n  Cron must be able to find `amness` and your API key; set them in the crontab environment or use a wrapper script.";
+export declare function runSchedule(argv: string[], cwd?: string): number;

package/dist/cli/schedulecli.js

@@ -0,0 +1,66 @@
+// `amness schedule`: recurring headless runs via cron.
+import { execFileSync, spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { add, cronLines, ensureLogDir, load, mergeCrontab, remove } from "../src/index.js";
+import { bold, dim, green, red } from "./ui.js";
+export const SCHEDULE_HELP = `usage: amness schedule <command>
+  add <name> "<cron>" "<task>" [--verify <cmd>]   save a recurring task for this project (5-field cron, e.g. "0 3 * * 1-5")
+  list                                            show this project's schedules
+  remove <name>                                   delete one
+  install [--write]                               print the crontab lines; with --write, put them in your crontab (only a marked block for this project is touched)
+  uninstall                                       remove this project's block from your crontab
+  Runs are headless (\`amness run --json\`), risky commands are denied, and each run's output is appended to .amness/schedule-logs/<name>.jsonl.
+  Cron must be able to find \`amness\` and your API key; set them in the crontab environment or use a wrapper script.`;
+export function runSchedule(argv, cwd = process.cwd()) {
+    const root = resolve(cwd), [cmd, ...rest] = argv;
+    const val = (f) => { const i = rest.indexOf(f); return i >= 0 ? rest[i + 1] : undefined; };
+    try {
+        if (!cmd || cmd === "--help" || cmd === "-h") {
+            console.log(SCHEDULE_HELP);
+            return cmd ? 0 : 2;
+        }
+        if (cmd === "add") {
+            const [name, cron, task] = rest;
+            add(root, { name, cron, task, verify: val("--verify") });
+            console.log(`saved "${name}". Run \`amness schedule install\` to see the crontab line.`);
+            return 0;
+        }
+        if (cmd === "list") {
+            const l = load(root);
+            if (!l.length)
+                console.log("no schedules for this project");
+            for (const s of l)
+                console.log(`${bold(s.name.padEnd(16))} ${s.cron.padEnd(14)} ${s.task}${s.verify ? dim("  verify: " + s.verify) : ""}`);
+            return 0;
+        }
+        if (cmd === "remove") {
+            console.log(remove(root, rest[0]) ? `removed "${rest[0]}"` : `no schedule named "${rest[0]}"`);
+            return 0;
+        }
+        if (cmd === "install" || cmd === "uninstall") {
+            const lines = cmd === "install" ? cronLines(root, load(root)) : [];
+            if (cmd === "install" && !rest.includes("--write")) {
+                console.log(lines.length ? lines.join("\n") : "no schedules to install");
+                console.log(dim("\n(not written; pass --write to add these to your crontab)"));
+                return 0;
+            }
+            let current = "";
+            try {
+                current = execFileSync("crontab", ["-l"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            }
+            catch { /* none yet */ }
+            ensureLogDir(root);
+            const r = spawnSync("crontab", ["-"], { input: mergeCrontab(current, root, lines), encoding: "utf8" });
+            if (r.status !== 0)
+                throw new Error("crontab refused the update: " + (r.stderr || "unknown error").trim());
+            console.log(green(cmd === "install" ? `installed ${lines.length} schedule(s) in your crontab` : "removed this project's schedules from your crontab"));
+            return 0;
+        }
+        console.error(SCHEDULE_HELP);
+        return 2;
+    }
+    catch (e) {
+        console.error(red("✗ " + e.message));
+        return 2;
+    }
+}

package/dist/cli/state.d.ts

@@ -0,0 +1,11 @@
+export type State = {
+    lastDir?: string;
+    verifyByDir: Record<string, string>;
+    tasks: string[]; /** project hooks the user approved: directory -> fingerprint of the hooks.json that was approved */
+    hookTrust?: Record<string, string>; /** project plugins the user approved: directory -> fingerprint of the plugin files */
+    pluginTrust?: Record<string, string>;
+};
+export declare function loadState(): State;
+export declare function saveState(s: State): void;
+/** Most-recent-first, de-duplicated, capped: the shape readline's `history` wants. */
+export declare function rememberTask(s: State, task: string): State;

package/dist/cli/state.js

@@ -0,0 +1,19 @@
+// Small remembered state so the TUI stops asking things it already knows: last project, per-project verify command, task history.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { home } from "./config.js";
+const file = () => join(home(), "state.json");
+export function loadState() {
+    try {
+        if (existsSync(file()))
+            return { verifyByDir: {}, tasks: [], ...JSON.parse(readFileSync(file(), "utf8")) };
+    }
+    catch { /* corrupt: start fresh */ }
+    return { verifyByDir: {}, tasks: [] };
+}
+export function saveState(s) { mkdirSync(home(), { recursive: true }); writeFileSync(file(), JSON.stringify(s, null, 2)); }
+/** Most-recent-first, de-duplicated, capped: the shape readline's `history` wants. */
+export function rememberTask(s, task) {
+    const t = task.trim();
+    return t ? { ...s, tasks: [t, ...s.tasks.filter((x) => x !== t)].slice(0, 50) } : s;
+}

package/dist/cli/tui/ansi.d.ts

@@ -0,0 +1,38 @@
+/** Colour: -1 = terminal default, 0x000000..0xFFFFFF = truecolor, 0x1000000 + n = 256-palette index n. */
+export declare const DEFAULT = -1;
+export declare const A: {
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly italic: 4;
+    readonly underline: 8;
+    readonly strike: 16;
+    readonly inverse: 32;
+};
+export type Cell = {
+    ch: string;
+    w: number;
+    fg: number;
+    bg: number;
+    attr: number;
+};
+/** Resolve any colour value to 0xRRGGBB (for dimming/compositing and for screenshots). `def` stands in for the terminal default. */
+export declare function toRgb(c: number, def: number): number;
+export declare const rgb: (r: number, g: number, b: number) => number;
+export declare const mix: (a: number, b: number, t: number) => number;
+type St = {
+    fg: number;
+    bg: number;
+    attr: number;
+};
+/** Apply the parameters of one SGR sequence (the part between `ESC[` and `m`) to a style. */
+export declare function applySgr(st: St, params: string): void;
+/** Parse an ANSI string into styled cells. Wide characters become one cell with w = 2. Unknown escape sequences are dropped. */
+export declare function parseAnsi(s: string, base?: Partial<St>): Cell[];
+/** Cells back to an ANSI string (minimal SGR changes). */
+export declare function cellsToAnsi(cells: Cell[]): string;
+/** Full SGR (reset + everything) to reach a given style from any state. */
+export declare function sgrFor(fg: number, bg: number, attr: number): string;
+/** SGR fragments for a colour (truecolor, 256-palette index, or default). */
+export declare const fgSeq: (c: number) => string;
+export declare const bgSeq: (c: number) => string;
+export {};