amness 0.0.0-stage → 0.1.2

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 {};

package/dist/cli/tui/ansi.js

@@ -0,0 +1,142 @@
+// ANSI strings <-> styled cells. The renderers produce ANSI strings; the full-screen canvas and the screenshot tool need cells.
+import { cpWidth } from "./text.js";
+/** Colour: -1 = terminal default, 0x000000..0xFFFFFF = truecolor, 0x1000000 + n = 256-palette index n. */
+export const DEFAULT = -1;
+export const A = { bold: 1, dim: 2, italic: 4, underline: 8, strike: 16, inverse: 32 };
+const BASE16 = [0x000000, 0xcd3131, 0x0dbc79, 0xe5e510, 0x2472c8, 0xbc3fbc, 0x11a8cd, 0xe5e5e5, 0x666666, 0xf14c4c, 0x23d18b, 0xf5f543, 0x3b8eea, 0xd670d6, 0x29b8db, 0xffffff];
+/** Resolve any colour value to 0xRRGGBB (for dimming/compositing and for screenshots). `def` stands in for the terminal default. */
+export function toRgb(c, def) {
+    if (c === DEFAULT)
+        return def;
+    if (c < 0x1000000)
+        return c;
+    const i = c - 0x1000000;
+    if (i < 16)
+        return BASE16[i];
+    if (i >= 232) {
+        const v = 8 + (i - 232) * 10;
+        return (v << 16) | (v << 8) | v;
+    }
+    const n = i - 16, lv = (x) => (x === 0 ? 0 : 55 + x * 40);
+    return (lv(Math.floor(n / 36)) << 16) | (lv(Math.floor(n / 6) % 6) << 8) | lv(n % 6);
+}
+export const rgb = (r, g, b) => (r << 16) | (g << 8) | b;
+export const mix = (a, b, t) => rgb(...[16, 8, 0].map((s) => Math.round(((a >> s) & 255) * (1 - t) + ((b >> s) & 255) * t)));
+/** Apply the parameters of one SGR sequence (the part between `ESC[` and `m`) to a style. */
+export function applySgr(st, params) {
+    const p = params === "" ? [0] : params.split(/[;:]/).map((x) => (x === "" ? 0 : Number(x)));
+    for (let i = 0; i < p.length; i++) {
+        const n = p[i];
+        if (n === 0) {
+            st.fg = DEFAULT;
+            st.bg = DEFAULT;
+            st.attr = 0;
+        }
+        else if (n === 1)
+            st.attr |= A.bold;
+        else if (n === 2)
+            st.attr |= A.dim;
+        else if (n === 3)
+            st.attr |= A.italic;
+        else if (n === 4)
+            st.attr |= A.underline;
+        else if (n === 7)
+            st.attr |= A.inverse;
+        else if (n === 9)
+            st.attr |= A.strike;
+        else if (n === 22)
+            st.attr &= ~(A.bold | A.dim);
+        else if (n === 23)
+            st.attr &= ~A.italic;
+        else if (n === 24)
+            st.attr &= ~A.underline;
+        else if (n === 27)
+            st.attr &= ~A.inverse;
+        else if (n === 29)
+            st.attr &= ~A.strike;
+        else if (n >= 30 && n <= 37)
+            st.fg = 0x1000000 + n - 30;
+        else if (n >= 90 && n <= 97)
+            st.fg = 0x1000000 + n - 90 + 8;
+        else if (n === 39)
+            st.fg = DEFAULT;
+        else if (n >= 40 && n <= 47)
+            st.bg = 0x1000000 + n - 40;
+        else if (n >= 100 && n <= 107)
+            st.bg = 0x1000000 + n - 100 + 8;
+        else if (n === 49)
+            st.bg = DEFAULT;
+        else if (n === 38 || n === 48) {
+            const key = n === 38 ? "fg" : "bg";
+            if (p[i + 1] === 2) {
+                st[key] = rgb(p[i + 2] & 255, p[i + 3] & 255, p[i + 4] & 255);
+                i += 4;
+            }
+            else if (p[i + 1] === 5) {
+                st[key] = 0x1000000 + (p[i + 2] & 255);
+                i += 2;
+            }
+        }
+    }
+}
+/** Parse an ANSI string into styled cells. Wide characters become one cell with w = 2. Unknown escape sequences are dropped. */
+export function parseAnsi(s, base = {}) {
+    const st = { fg: base.fg ?? DEFAULT, bg: base.bg ?? DEFAULT, attr: base.attr ?? 0 }, out = [];
+    const re = /\x1b\[([0-9;:?]*)([A-Za-z])|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|([\s\S])/gu;
+    for (let m; (m = re.exec(s));) {
+        if (m[2] === "m") {
+            const b = { ...base };
+            applySgr(st, m[1]);
+            void b;
+        }
+        else if (m[3] !== undefined) {
+            const cp = m[3].codePointAt(0), w = cpWidth(cp);
+            if (w === 0) {
+                if (out.length && cp >= 0x300)
+                    out[out.length - 1].ch += m[3];
+                continue;
+            } // combining marks join the previous cell
+            out.push({ ch: m[3], w, fg: st.fg, bg: st.bg, attr: st.attr });
+        }
+    }
+    return out;
+}
+/** Cells back to an ANSI string (minimal SGR changes). */
+export function cellsToAnsi(cells) {
+    let out = "", fg = DEFAULT, bg = DEFAULT, attr = 0;
+    for (const c of cells) {
+        if (c.fg !== fg || c.bg !== bg || c.attr !== attr) {
+            out += sgrFor(c.fg, c.bg, c.attr);
+            fg = c.fg;
+            bg = c.bg;
+            attr = c.attr;
+        }
+        out += c.ch;
+    }
+    return out + (fg !== DEFAULT || bg !== DEFAULT || attr ? "\x1b[0m" : "");
+}
+const colorSeq = (c, base) => (c === DEFAULT ? String(base + 9) : c >= 0x1000000 ? (c - 0x1000000 < 8 ? String(base + c - 0x1000000) : c - 0x1000000 < 16 ? String(base + 60 + c - 0x1000000 - 8) : `${base + 8};5;${c - 0x1000000}`) : `${base + 8};2;${(c >> 16) & 255};${(c >> 8) & 255};${c & 255}`);
+/** Full SGR (reset + everything) to reach a given style from any state. */
+export function sgrFor(fg, bg, attr) {
+    const p = ["0"];
+    if (attr & A.bold)
+        p.push("1");
+    if (attr & A.dim)
+        p.push("2");
+    if (attr & A.italic)
+        p.push("3");
+    if (attr & A.underline)
+        p.push("4");
+    if (attr & A.inverse)
+        p.push("7");
+    if (attr & A.strike)
+        p.push("9");
+    if (fg !== DEFAULT)
+        p.push(colorSeq(fg, 30));
+    if (bg !== DEFAULT)
+        p.push(colorSeq(bg, 40));
+    return `\x1b[${p.join(";")}m`;
+}
+/** SGR fragments for a colour (truecolor, 256-palette index, or default). */
+export const fgSeq = (c) => (c === DEFAULT ? "\x1b[39m" : c >= 0x1000000 ? `\x1b[38;5;${c - 0x1000000}m` : `\x1b[38;2;${(c >> 16) & 255};${(c >> 8) & 255};${c & 255}m`);
+export const bgSeq = (c) => (c === DEFAULT ? "\x1b[49m" : c >= 0x1000000 ? `\x1b[48;5;${c - 0x1000000}m` : `\x1b[48;2;${(c >> 16) & 255};${(c >> 8) & 255};${c & 255}m`);