amness 0.0.0-stage → 0.1.0

package/dist/src/sandbox.js

@@ -0,0 +1,68 @@
+// OS-level sandbox for shell commands. The permission prompts are a policy; this is enforcement: even an approved or auto-approved command cannot write outside
+// the workspace (or into .git), and in strict mode cannot use the network. macOS: Seatbelt (sandbox-exec). Linux: Bubblewrap (bwrap). Elsewhere: unavailable, and
+// asking for a sandbox that cannot be provided is an error, never a silent downgrade.
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+export const SANDBOX_MODES = ["off", "workspace", "strict"];
+let cached = null;
+const has = (bin) => { try {
+    execFileSync("sh", ["-c", `command -v ${bin}`], { stdio: "ignore" });
+    return true;
+}
+catch {
+    return false;
+} };
+/** bwrap is often installed but unable to create namespaces (containers, locked-down kernels): probe with a no-op instead of trusting `command -v`. */
+function bwrapWorks() { try {
+    execFileSync("bwrap", ["--ro-bind", "/", "/", "--dev", "/dev", "true"], { stdio: "ignore", timeout: 5000 });
+    return true;
+}
+catch {
+    return false;
+} }
+/** Which sandbox this machine can provide. */
+export function sandboxKind() {
+    if (cached === null)
+        cached = process.platform === "darwin" && has("sandbox-exec") ? "seatbelt" : process.platform === "linux" && has("bwrap") && bwrapWorks() ? "bwrap" : undefined;
+    return cached;
+}
+export const sandboxHelp = () => process.platform === "linux" ? "install bubblewrap (apt install bubblewrap); if it is installed, this kernel or container does not allow it to create namespaces" : process.platform === "darwin" ? "sandbox-exec was not found" : "OS sandboxing is only available on macOS and Linux";
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return resolve(p);
+} };
+/** Folders that tools legitimately write to besides the workspace: temp folders and package-manager caches (not in strict mode). */
+function writable(workspace, mode) {
+    const h = homedir(), base = [workspace, tmpdir(), "/tmp", "/private/tmp", "/private/var/folders", "/var/folders", "/dev/shm"];
+    const caches = [".npm", ".cache", ".cargo", ".rustup", ".gradle", ".m2", ".pnpm-store", ".yarn", ".bun", ".deno", "go/pkg", ".local/share", "Library/Caches", ".node-gyp", ".config"].map((d) => join(h, d));
+    return [...new Set([...base, ...(mode === "workspace" ? caches : [])].map(real))].filter((p) => existsSync(p));
+}
+const q = (s) => JSON.stringify(s); // SBPL string literals use the same quoting as JSON for the characters that matter here
+/** The Seatbelt profile: everything allowed except writing outside the allowed folders (and inside .git), and, in strict mode, the network. */
+export function seatbeltProfile(workspace, mode) {
+    const ws = real(workspace), dirs = writable(ws, mode);
+    return [
+        "(version 1)", "(allow default)",
+        "(deny file-write*)",
+        `(allow file-write* ${dirs.map((d) => `(subpath ${q(d)})`).join(" ")} (literal "/dev/null") (literal "/dev/tty") (literal "/dev/dtracehelper") (regex #"^/dev/(fd|pts|tty)")` + ")",
+        `(deny file-write* (subpath ${q(join(ws, ".git"))}) (regex #"^${join(ws, ".amness").replace(/[.+*?^${}()|[\]\\]/g, "\\$&")}/(hooks|permissions)\\.json$"))`,
+        ...(mode === "strict" ? ["(deny network*)", "(allow network* (local unix))"] : []),
+    ].join("\n");
+}
+/** `file` and `args` that run `cmd` under the sandbox, or undefined when mode is off. Throws when a sandbox was asked for and cannot be provided. */
+export function wrapCommand(cmd, workspace, mode) {
+    if (mode === "off")
+        return undefined;
+    const kind = sandboxKind();
+    if (!kind)
+        throw new Error(`the sandbox is on (${mode}) but unavailable here: ${sandboxHelp()}. Turn it off with /sandbox off to run commands unsandboxed.`);
+    if (kind === "seatbelt")
+        return { file: "sandbox-exec", args: ["-p", seatbeltProfile(workspace, mode), "sh", "-c", cmd] };
+    const ws = real(workspace), dirs = writable(ws, mode);
+    return { file: "bwrap", args: ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", ...dirs.flatMap((d) => ["--bind", d, d]), ...(existsSync(join(ws, ".git")) ? ["--ro-bind", join(ws, ".git"), join(ws, ".git")] : []),
+            ...(mode === "strict" ? ["--unshare-net"] : []), "--die-with-parent", "--chdir", ws, "sh", "-c", cmd] };
+}

package/dist/src/schedule.d.ts

@@ -0,0 +1,20 @@
+export type Schedule = {
+    name: string;
+    cron: string;
+    task: string;
+    verify?: string;
+    extra?: string[];
+};
+/** Strict 5-field cron check (numbers, ranges, lists, steps, `*`). Names like MON are not accepted, to keep what runs unambiguous. */
+export declare function validCron(expr: string): string | undefined;
+export declare const file: (cwd: string) => string;
+export declare function load(cwd: string): Schedule[];
+export declare function save(cwd: string, list: Schedule[]): void;
+export declare function add(cwd: string, s: Schedule): void;
+export declare function remove(cwd: string, name: string): boolean;
+/** The crontab lines for these schedules. Runs are denied risky commands (no --yes) unless the schedule says otherwise in `extra`. */
+export declare function cronLines(cwd: string, list: Schedule[], bin?: string): string[];
+/** `current` crontab text with this project's block replaced by `lines` (or removed when empty). Everything else is kept byte for byte. */
+export declare function mergeCrontab(current: string, cwd: string, lines: string[]): string;
+export declare function ensureLogDir(cwd: string): void;
+export declare const hasSchedules: (cwd: string) => boolean;

package/dist/src/schedule.js

@@ -0,0 +1,59 @@
+// Recurring headless runs. Schedules live in .amness/schedules.json; `amness schedule install` turns them into crontab lines (printed by default; written only with --write,
+// inside a marked block so removing them is exact). Each run is `amness run --json` with its output kept in .amness/schedule-logs/.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+/** Strict 5-field cron check (numbers, ranges, lists, steps, `*`). Names like MON are not accepted, to keep what runs unambiguous. */
+export function validCron(expr) {
+    const f = expr.trim().split(/\s+/);
+    if (f.length !== 5)
+        return "a schedule needs 5 fields: minute hour day-of-month month day-of-week";
+    for (let i = 0; i < 5; i++)
+        for (const part of f[i].split(",")) {
+            const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+            if (!m)
+                return `field ${i + 1} (${f[i]}) is not valid`;
+            const [lo, hi] = RANGES[i], nums = m[1] === "*" ? [] : m[1].split("-").map(Number);
+            if (nums.some((n) => n < lo || n > hi) || (nums.length === 2 && nums[0] > nums[1]))
+                return `field ${i + 1} (${f[i]}) is out of range ${lo}-${hi}`;
+            if (m[2] !== undefined && Number(m[2]) < 1)
+                return `field ${i + 1} step must be at least 1`;
+        }
+    return undefined;
+}
+const sq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+export const file = (cwd) => join(cwd, ".amness", "schedules.json");
+export function load(cwd) { try {
+    return JSON.parse(readFileSync(file(cwd), "utf8"));
+}
+catch {
+    return [];
+} }
+export function save(cwd, list) { mkdirSync(dirname(file(cwd)), { recursive: true }); writeFileSync(file(cwd), JSON.stringify(list, null, 2) + "\n"); }
+export function add(cwd, s) {
+    const bad = validCron(s.cron);
+    if (bad)
+        throw new Error(bad);
+    if (!/^[\w.-]{1,40}$/.test(s.name))
+        throw new Error("the name may use letters, numbers, . _ - (40 characters at most)");
+    if (!s.task.trim())
+        throw new Error("a schedule needs a task");
+    const list = load(cwd).filter((x) => x.name !== s.name);
+    list.push(s);
+    save(cwd, list);
+}
+export function remove(cwd, name) { const l = load(cwd), n = l.filter((x) => x.name !== name); save(cwd, n); return n.length !== l.length; }
+const BEGIN = (cwd) => `# >>> amness schedules for ${cwd} >>>`, END = (cwd) => `# <<< amness schedules for ${cwd} <<<`;
+/** The crontab lines for these schedules. Runs are denied risky commands (no --yes) unless the schedule says otherwise in `extra`. */
+export function cronLines(cwd, list, bin = "amness") {
+    return list.map((s) => `${s.cron} cd ${sq(cwd)} && ${bin} run --json ${s.verify ? `--verify ${sq(s.verify)} ` : ""}${(s.extra ?? []).map(sq).join(" ")}${s.extra?.length ? " " : ""}${sq(s.task)} >> ${sq(join(cwd, ".amness", "schedule-logs", s.name + ".jsonl"))} 2>&1`);
+}
+/** `current` crontab text with this project's block replaced by `lines` (or removed when empty). Everything else is kept byte for byte. */
+export function mergeCrontab(current, cwd, lines) {
+    const b = BEGIN(cwd), e = END(cwd), i = current.indexOf(b), j = current.indexOf(e);
+    const rest = i >= 0 && j > i ? current.slice(0, i) + current.slice(j + e.length).replace(/^\n/, "") : current;
+    const base = rest.replace(/\n*$/, rest.trim() ? "\n" : "");
+    return lines.length ? `${base}${b}\n${lines.join("\n")}\n${e}\n` : base;
+}
+export function ensureLogDir(cwd) { mkdirSync(join(cwd, ".amness", "schedule-logs"), { recursive: true }); }
+export const hasSchedules = (cwd) => existsSync(file(cwd));

package/dist/src/schema.d.ts

@@ -0,0 +1,13 @@
+/** Minimal JSON-schema subset: type, enum, required, properties, additionalProperties, items. Returns error strings. */
+export type Schema = {
+    type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
+    enum?: unknown[];
+    properties?: Record<string, Schema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: Schema;
+    description?: string;
+};
+export declare function validate(v: unknown, s: Schema, path?: string): string[];
+/** Parse JSON the way models actually emit it: strip ``` fences and surrounding prose. */
+export declare function parseLooseJson(text: string): unknown;

package/dist/src/schema.js

@@ -0,0 +1,36 @@
+const typeOf = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : typeof v);
+export function validate(v, s, path = "$") {
+    const errs = [];
+    const t = typeOf(v);
+    if (s.type && !(t === s.type || (s.type === "integer" && Number.isInteger(v)) || (s.type === "number" && t === "number")))
+        return [`${path}: expected ${s.type}, got ${t}`];
+    if (s.enum && !s.enum.includes(v))
+        errs.push(`${path}: must be one of ${JSON.stringify(s.enum)}`);
+    if (t === "object") {
+        const o = v;
+        for (const k of s.required ?? [])
+            if (!(k in o))
+                errs.push(`${path}.${k}: required`);
+        for (const [k, x] of Object.entries(o)) {
+            if (s.properties?.[k])
+                errs.push(...validate(x, s.properties[k], `${path}.${k}`));
+            else if (s.additionalProperties === false)
+                errs.push(`${path}.${k}: unexpected property`);
+        }
+    }
+    if (t === "array" && s.items)
+        v.forEach((x, i) => errs.push(...validate(x, s.items, `${path}[${i}]`)));
+    return errs;
+}
+/** Parse JSON the way models actually emit it: strip ``` fences and surrounding prose. */
+export function parseLooseJson(text) {
+    const t = text.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
+    try {
+        return JSON.parse(t);
+    }
+    catch { /* fall through to brace scan */ }
+    const i = t.search(/[{[]/), j = Math.max(t.lastIndexOf("}"), t.lastIndexOf("]"));
+    if (i >= 0 && j > i)
+        return JSON.parse(t.slice(i, j + 1));
+    throw new Error("no JSON found");
+}

package/dist/src/secrets.d.ts

@@ -0,0 +1,10 @@
+export type Redacted = {
+    text: string;
+    count: number;
+    kinds: string[];
+};
+export declare function redact(text: string): Redacted;
+/** `redact` applied to every string inside a JSON-like value (used before anything is written to a trace). */
+export declare function redactDeep<T>(v: T): T;
+/** Environment variables a command run by the agent should not inherit: Amness's own keys always; with `strict`, anything that looks like a credential. */
+export declare function childEnv(env?: NodeJS.ProcessEnv, strict?: boolean): NodeJS.ProcessEnv;

package/dist/src/secrets.js

@@ -0,0 +1,41 @@
+const PATTERNS = [
+    ["anthropic-key", /\bsk-ant-[A-Za-z0-9_-]{20,}/g], ["openai-key", /\bsk-(?:proj-)?[A-Za-z0-9_-]{24,}/g], ["github-token", /\bgh[pousr]_[A-Za-z0-9]{30,}\b|\bgithub_pat_[A-Za-z0-9_]{40,}/g],
+    ["aws-access-key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g], ["slack-token", /\bxox[baprs]-[A-Za-z0-9-]{10,}/g], ["google-api-key", /\bAIza[0-9A-Za-z_-]{35}\b/g], ["stripe-key", /\b[rs]k_(?:live|test)_[0-9a-zA-Z]{20,}/g],
+    ["npm-token", /\bnpm_[A-Za-z0-9]{36}\b/g], ["private-key", /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g], ["jwt", /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g],
+];
+/** `PASSWORD=hunter2hunter2`, `"api_key": "abcd1234efgh"`, `Authorization: Bearer xyz...` : keep the name, mask the value. */
+const ASSIGN = /((?:^|[\s"'`{,])(?:[A-Za-z0-9_.-]*(?:pass(?:word|wd)?|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credential|auth)[A-Za-z0-9_.-]*)["'`]?\s*[:=]\s*["'`]?)([^\s"'`,;}{]{8,})/gi;
+const BEARER = /(\bBearer\s+)([A-Za-z0-9._~+/=-]{16,})/g;
+export function redact(text) {
+    let count = 0;
+    const kinds = new Set();
+    let out = text;
+    for (const [kind, re] of PATTERNS)
+        out = out.replace(re, () => { count++; kinds.add(kind); return `[REDACTED:${kind}]`; });
+    out = out.replace(BEARER, (_m, pre) => { count++; kinds.add("bearer-token"); return `${pre}[REDACTED:bearer-token]`; });
+    out = out.replace(ASSIGN, (m, pre, val) => { if (/^\[REDACTED|^\$\{?\w+\}?$|^<[^>]+>$|^(?:true|false|null|undefined|none)$/i.test(val) || /^(?:process\.env|os\.environ|getenv|ENV\[)/.test(val))
+        return m; count++; kinds.add("credential-assignment"); return `${pre}[REDACTED:credential]`; });
+    return { text: out, count, kinds: [...kinds] };
+}
+/** `redact` applied to every string inside a JSON-like value (used before anything is written to a trace). */
+export function redactDeep(v) {
+    if (typeof v === "string")
+        return redact(v).text;
+    if (Array.isArray(v))
+        return v.map(redactDeep);
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, redactDeep(x)]));
+    return v;
+}
+/** Environment variables a command run by the agent should not inherit: Amness's own keys always; with `strict`, anything that looks like a credential. */
+export function childEnv(env = process.env, strict = false) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (/^(OPENAI_API_KEY|ANTHROPIC_API_KEY|TAVILY_API_KEY|OPENROUTER_API_KEY|AMNESS_[A-Z_]*KEY|AMNESS_OTLP)$/.test(k))
+            continue;
+        if (strict && /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)/i.test(k) && !/^(SSH_AUTH_SOCK|GPG_TTY|KEYCHAIN.*|DISPLAY)$/.test(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}

package/dist/src/shell.d.ts

@@ -0,0 +1,34 @@
+export type ShellKind = "posix" | "powershell" | "cmd";
+export type ShellInfo = {
+    name: string;
+    kind: ShellKind;
+    file: string; /** how the shell is started with one command line */
+    args: (cmd: string) => string[];
+};
+export declare const SHELL_CHOICES: readonly string[];
+type Probe = {
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    exists: (f: string) => boolean;
+};
+/** Pick a shell. `want` is "auto" or a name; a name that is not installed falls back to auto (and `fallback` says so). Pure apart from the probe, so it is testable. */
+export declare function chooseShell(want?: string, p?: Probe): {
+    shell: ShellInfo;
+    fallback?: string;
+};
+/** Set the preferred shell (from config or /shell). Anything else than a known name is ignored. */
+export declare function setShell(name: string | undefined): void;
+export declare function currentShell(): ShellInfo;
+export declare const shellFallbackNote: () => string | undefined;
+/** The program and arguments that run one command line in the current shell. */
+export declare const shellInvocation: (cmd: string) => {
+    file: string;
+    args: string[];
+};
+/** Kept for older callers: the path of the current shell program. */
+export declare const posixShell: () => string;
+/** What to tell the model about where its commands run. */
+export declare function shellNote(p?: Probe): string;
+/** The path as the model should see it: always forward slashes. */
+export declare const slash: (p: string) => string;
+export {};

package/dist/src/shell.js

@@ -0,0 +1,95 @@
+// Which shell runs the agent's commands. The best choice depends on the machine, so Amness looks at what exists:
+//   macOS / Linux: bash, else zsh, else sh (the model writes bash; your login shell is not used unless you ask for it).
+//   Windows: the bash that comes with Git for Windows, else PowerShell 7 (pwsh), else Windows PowerShell, else cmd.exe.
+// The model is told which shell it is talking to (a PowerShell command is not a bash command), and the safety floor knows the dangerous commands of each family.
+// Override with the AMNESS_SHELL environment variable, the `shell` setting, or /shell: auto, bash, zsh, sh, pwsh, powershell or cmd.
+import { existsSync } from "node:fs";
+import { delimiter, join as joinHere, win32 } from "node:path";
+const jn = (win) => (win ? win32.join : joinHere);
+const WANT = ["auto", "bash", "zsh", "sh", "pwsh", "powershell", "cmd"];
+export const SHELL_CHOICES = WANT;
+const real = { platform: process.platform, get env() { return process.env; }, exists: existsSync };
+const exe = (n, win) => (win && !/\.(exe|cmd|bat)$/i.test(n) ? n + ".exe" : n);
+/** Find a program on PATH (never the WSL launcher in System32, which sees another filesystem). */
+function onPath(name, p) {
+    const win = p.platform === "win32", dirs = (p.env.PATH ?? p.env.Path ?? "").split(win ? ";" : delimiter).filter(Boolean);
+    for (const d of dirs) {
+        const f = jn(win)(d, exe(name, win));
+        if (p.exists(f) && !(win && name === "bash" && /system32/i.test(f)))
+            return f;
+    }
+    return undefined;
+}
+function gitBash(p) {
+    const join = jn(p.platform === "win32");
+    const fromPath = onPath("bash", p);
+    if (fromPath)
+        return fromPath;
+    for (const base of [p.env.ProgramFiles, p.env["ProgramFiles(x86)"], p.env.LOCALAPPDATA && jn(true)(p.env.LOCALAPPDATA, "Programs")])
+        if (base)
+            for (const sub of [join("Git", "bin", "bash.exe"), join("Git", "usr", "bin", "bash.exe")]) {
+                const f = join(base, sub);
+                if (p.exists(f))
+                    return f;
+            }
+    return undefined;
+}
+const posix = (name, file) => ({ name, kind: "posix", file, args: (cmd) => ["-c", cmd] });
+const ps = (name, file) => ({ name, kind: "powershell", file, args: (cmd) => ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", cmd] });
+const cmdShell = (file) => ({ name: "cmd", kind: "cmd", file, args: (cmd) => ["/d", "/s", "/c", cmd] });
+/** Pick a shell. `want` is "auto" or a name; a name that is not installed falls back to auto (and `fallback` says so). Pure apart from the probe, so it is testable. */
+export function chooseShell(want = "auto", p = real) {
+    const win = p.platform === "win32";
+    const find = (n) => {
+        if (n === "cmd")
+            return win ? cmdShell(p.env.ComSpec ?? "cmd.exe") : undefined;
+        if (n === "pwsh") {
+            const f = onPath("pwsh", p);
+            return f ? ps("pwsh", f) : undefined;
+        }
+        if (n === "powershell") {
+            const f = onPath("powershell", p) ?? (win && p.env.SystemRoot && p.exists(win32.join(p.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")) ? win32.join(p.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe") : undefined);
+            return f ? ps("powershell", f) : undefined;
+        }
+        if (n === "bash" && win) {
+            const f = gitBash(p);
+            return f ? posix("bash", f) : undefined;
+        }
+        const f = onPath(n, p) ?? (!win && p.exists("/bin/" + n) ? "/bin/" + n : undefined);
+        return f ? posix(n, f) : undefined;
+    };
+    let fallback;
+    if (want !== "auto") {
+        const s = find(want);
+        if (s)
+            return { shell: s };
+        fallback = `${want} was asked for but is not installed here; using the automatic choice`;
+    }
+    if (win) {
+        const s = find("bash") ?? find("pwsh") ?? find("powershell") ?? find("cmd") ?? cmdShell("cmd.exe");
+        return { shell: s, fallback };
+    }
+    // bash first (it is what models write), then zsh, then sh. Your login shell is deliberately not used by default: commands should behave the same on every machine; ask for zsh with /shell zsh.
+    const s = find("bash") ?? find("zsh") ?? find("sh") ?? posix("sh", "/bin/sh");
+    return { shell: s, fallback };
+}
+let wanted = "auto", cached;
+/** Set the preferred shell (from config or /shell). Anything else than a known name is ignored. */
+export function setShell(name) { const n = (name ?? "auto").toLowerCase(); wanted = WANT.includes(n) ? n : "auto"; cached = undefined; }
+export function currentShell() { return (cached ??= chooseShell(process.env.AMNESS_SHELL ?? wanted)).shell; }
+export const shellFallbackNote = () => (cached ??= chooseShell(process.env.AMNESS_SHELL ?? wanted)).fallback;
+/** The program and arguments that run one command line in the current shell. */
+export const shellInvocation = (cmd) => { const s = currentShell(); return { file: s.file, args: s.args(cmd) }; };
+/** Kept for older callers: the path of the current shell program. */
+export const posixShell = () => currentShell().file;
+/** What to tell the model about where its commands run. */
+export function shellNote(p = real) {
+    const s = chooseShell(process.env.AMNESS_SHELL ?? wanted, p).shell, os = p.platform === "win32" ? "Windows" : p.platform === "darwin" ? "macOS" : p.platform === "linux" ? "Linux" : p.platform;
+    if (s.kind === "powershell")
+        return `Environment: ${os}. Commands run in PowerShell (${s.name}), not bash: use PowerShell syntax (Get-ChildItem, Select-String, Get-Content, $env:NAME, \`;\` to chain commands). Forward slashes work in paths. Tools like grep, ls and cat may not exist.`;
+    if (s.kind === "cmd")
+        return `Environment: ${os}. Commands run in cmd.exe, not bash: use cmd syntax (dir, type, set NAME=value, & to chain commands). Tools like grep, ls and cat do not exist.`;
+    return `Environment: ${os}. Commands run with ${s.name} (${s.name} -c "<cmd>"): use ${s.name === "sh" || s.name === "dash" ? "POSIX sh" : s.name} syntax.`;
+}
+/** The path as the model should see it: always forward slashes. */
+export const slash = (p) => p.replace(/\\/g, "/");

package/dist/src/skills.d.ts

@@ -0,0 +1,20 @@
+import { type Tool } from "./harness.ts";
+export type Skill = {
+    name: string;
+    description: string;
+    dir: string;
+    file: string;
+    scope: "project" | "user";
+    source: string;
+};
+/** All skills visible from `cwd`: project folders first, then the user's; for the same name the first convention found wins. Malformed skills are skipped and reported. */
+export declare function loadSkills(cwd: string, o?: {
+    userHome?: string;
+}): {
+    skills: Skill[];
+    warnings: string[];
+};
+/** The short list that goes into the prompt. */
+export declare function skillsBlock(skills: Skill[]): string;
+/** `skill({ name })` returns the instructions plus the list of bundled files; `skill({ name, file })` returns one of those files. Nothing outside the skill's folder can be read. */
+export declare function skillTool(get: () => Skill[]): Tool;

package/dist/src/skills.js

@@ -0,0 +1,112 @@
+// Skills: folders with a SKILL.md (name + description in front matter, instructions in the body, optional helper files). Only the name and one-line description go
+// in the prompt; the model loads the full text with the `skill` tool when it needs it ("progressive disclosure"), so many skills cost almost nothing until used.
+// Compatible folder conventions: .amness/skills, .agents/skills (Codex, Gemini CLI, OpenCode) and .claude/skills (Claude Code), in the project and in your home folder.
+import { slash } from "./shell.js";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { defineTool } from "./harness.js";
+const CONVENTIONS = [".amness/skills", ".agents/skills", ".claude/skills"];
+function parseFront(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!m)
+        return { meta: {}, body: text };
+    const meta = {};
+    let key = "";
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([\w-]+):\s*(.*)$/.exec(line);
+        if (kv) {
+            key = kv[1];
+            meta[key] = kv[2].replace(/^["']|["']$/g, "").trim();
+        }
+        else if (key && /^\s+\S/.test(line))
+            meta[key] = (meta[key] + " " + line.trim()).trim(); // folded multi-line description
+    }
+    return { meta, body: m[2] };
+}
+/** All skills visible from `cwd`: project folders first, then the user's; for the same name the first convention found wins. Malformed skills are skipped and reported. */
+export function loadSkills(cwd, o = {}) {
+    const skills = [], warnings = [], seen = new Set(), home = o.userHome ?? (process.env.AMNESS_HOME ? resolve(process.env.AMNESS_HOME, "..") : homedir());
+    const roots = [{ base: cwd, scope: "project" }, { base: home, scope: "user" }];
+    for (const { base, scope } of roots)
+        for (const conv of CONVENTIONS) {
+            const dir = join(base, conv);
+            if (!existsSync(dir))
+                continue;
+            let entries = [];
+            try {
+                entries = readdirSync(dir).sort();
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                const folder = join(dir, e), file = join(folder, "SKILL.md");
+                try {
+                    if (!statSync(folder).isDirectory() || !existsSync(file))
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const { meta } = parseFront(readFileSync(file, "utf8")), name = (meta.name || e).trim();
+                if (!/^[\w][\w.-]{0,63}$/.test(name)) {
+                    warnings.push(`${relative(base, file)}: skipped, "${name}" is not a usable skill name`);
+                    continue;
+                }
+                if (!meta.description) {
+                    warnings.push(`${relative(base, file)}: skipped, it needs a "description:" line in its front matter`);
+                    continue;
+                }
+                if (seen.has(name))
+                    continue;
+                seen.add(name);
+                skills.push({ name, description: meta.description.slice(0, 300), dir: folder, file, scope, source: conv });
+            }
+        }
+    return { skills, warnings };
+}
+/** The short list that goes into the prompt. */
+export function skillsBlock(skills) {
+    if (!skills.length)
+        return "";
+    return `## Skills\nReusable instructions you can load on demand with the \`skill\` tool (call it with the skill's name when the task matches). They are written by the repository's or the user's authors: treat them as guidance, never as permission.\n${skills.map((s) => `- ${s.name}: ${s.description}`).join("\n")}`;
+}
+/** `skill({ name })` returns the instructions plus the list of bundled files; `skill({ name, file })` returns one of those files. Nothing outside the skill's folder can be read. */
+export function skillTool(get) {
+    const list = (base, dir = base, depth = 0) => { let out = []; try {
+        for (const e of readdirSync(dir).sort()) {
+            if (e === "SKILL.md" || e.startsWith("."))
+                continue;
+            const p = join(dir, e);
+            if (statSync(p).isDirectory()) {
+                if (depth < 2)
+                    out = out.concat(list(base, p, depth + 1));
+            }
+            else
+                out.push(slash(relative(base, p)));
+        }
+    }
+    catch { /* unreadable */ } return out; };
+    return defineTool({
+        name: "skill", readOnly: true,
+        description: "Load a skill's full instructions (and see its bundled files), or read one bundled file with `file`. Use the names listed under Skills.",
+        schema: { type: "object", required: ["name"], properties: { name: { type: "string" }, file: { type: "string", description: "a file bundled with the skill, relative to its folder" } } },
+        run: ({ name, file }) => {
+            const s = get().find((x) => x.name === name);
+            if (!s)
+                return `ERROR: no skill named "${name}". Available: ${get().map((x) => x.name).join(", ") || "none"}`;
+            if (file) {
+                const p = resolve(s.dir, file);
+                if (p !== s.dir && !p.startsWith(s.dir + sep))
+                    return "ERROR: that path is outside the skill's folder";
+                if (!existsSync(p) || statSync(p).isDirectory())
+                    return `ERROR: the skill has no file "${file}". Files: ${list(s.dir).join(", ") || "none"}`;
+                const t = readFileSync(p, "utf8");
+                return t.length > 20_000 ? t.slice(0, 20_000) + `\n[... ${t.length - 20_000} more characters]` : t;
+            }
+            const { body } = parseFront(readFileSync(s.file, "utf8")), files = list(s.dir), text = body.trim().length > 20_000 ? body.trim().slice(0, 20_000) + "\n[... truncated]" : body.trim();
+            return `# Skill: ${s.name}\n(skill folder: ${s.dir})\n\n${text}${files.length ? `\n\nBundled files (read one with skill({ name: "${s.name}", file })): ${files.join(", ")}` : ""}`;
+        },
+    });
+}

package/dist/src/snapshot.d.ts

@@ -0,0 +1,20 @@
+export declare function irreversibleReason(cmd: string): string | undefined;
+export type SnapshotResult = {
+    restored: string[];
+    removed: string[];
+};
+export declare class Snapshots {
+    private cwd;
+    private ok?;
+    private gitDir;
+    constructor(cwd: string);
+    /** Snapshots need a git repository (with or without commits). */
+    available(): Promise<boolean>;
+    private index;
+    /** Record the working tree as a tree object and return its id (undefined when there is no git repository or git fails). */
+    take(): Promise<string | undefined>;
+    /** Paths in the working tree that differ from the snapshot (changed, deleted, or created since). */
+    changedSince(tree: string): Promise<string[]>;
+    /** Put the working tree back to `tree`: restore files that were changed or deleted, remove files that were created (only those git would see: ignored files are never touched). */
+    restore(tree: string): Promise<SnapshotResult>;
+}

package/dist/src/snapshot.js

@@ -0,0 +1,93 @@
+// Reversible shell commands. Before an agent runs a command that may change files, the whole working tree (tracked and untracked, ignored files excluded) is recorded as a git
+// TREE OBJECT using a private index file: no commit, no branch, no stash, the user's index and history are never touched. `restoreTree` puts the working tree back exactly
+// (files restored, files the command created removed). Effects outside the workspace and on other systems cannot be restored, so such commands are named instead.
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+const git = (cwd, args, env = {}, input) => new Promise((res, rej) => { const p = execFile("git", args, { cwd, env: { ...process.env, ...env }, maxBuffer: 256 << 20 }, (e, out, err) => (e ? rej(new Error((err || e.message).trim().split("\n")[0])) : res(out))); if (input !== undefined)
+    p.stdin?.end(input); });
+const EXCLUDE = [":(exclude).amness", ":(exclude).git"];
+/** Commands whose effects reach beyond the working tree, so undo cannot take them back. */
+const IRREVERSIBLE = [
+    [/\bgit\s+(?:-\S+\s+)*push\b/, "pushes commits to a remote"], [/\b(?:npm|pnpm|yarn)\s+(?:publish|deprecate|unpublish)\b|\bcargo\s+publish\b|\btwine\s+upload\b|\bgem\s+push\b/, "publishes a package"],
+    [/\bdocker\s+(?:push|rm|rmi|system\s+prune|volume\s+rm)\b|\bdocker-compose\s+down\s+-v\b/, "changes or deletes containers or images"], [/\bkubectl\s+(?:apply|delete|replace|scale|rollout|patch)\b|\bhelm\s+(?:install|upgrade|uninstall)\b|\bterraform\s+(?:apply|destroy)\b|\bpulumi\s+(?:up|destroy)\b/, "changes live infrastructure"],
+    [/\baws\s+\S+\s+(?:create|delete|put|update|terminate|remove|run|start|stop)\w*|\bgcloud\s+.*\b(?:create|delete|update|deploy)\b|\baz\s+.*\b(?:create|delete|update)\b/, "changes a cloud account"],
+    [/\bcurl\b[^|;&]*\s(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--request\s+(?:POST|PUT|PATCH|DELETE)|-d\b|--data\b|-F\b|--upload-file|-T\b)/i, "sends data to a server"],
+    [/\b(?:psql|mysql|sqlite3|mongo|mongosh|redis-cli)\b[^|;&]*(?:drop|delete|truncate|update|insert|alter|flushall|flushdb|set\b)/i, "writes to a database"],
+    [/\b(?:ssh|scp|rsync)\b/, "acts on another machine"], [/\bsendmail\b|\bmail\s+-s\b|\bslack\b[^|;&]*(?:post|send)/i, "sends a message"],
+    [/\brm\s+(?:-\S+\s+)*(?:\/|~|\$HOME|\.\.\/)/, "deletes outside the workspace"], [/(?:>|>>|\btee\b)\s*(?:\/(?!tmp\b|dev\/null\b)|~\/)/, "writes outside the workspace"],
+];
+export function irreversibleReason(cmd) { return IRREVERSIBLE.find(([re]) => re.test(cmd))?.[1]; }
+export class Snapshots {
+    cwd;
+    ok;
+    gitDir = "";
+    constructor(cwd) { this.cwd = resolve(cwd); }
+    /** Snapshots need a git repository (with or without commits). */
+    async available() {
+        if (this.ok !== undefined)
+            return this.ok;
+        try {
+            this.gitDir = resolve(this.cwd, (await git(this.cwd, ["rev-parse", "--git-dir"])).trim());
+            this.ok = true;
+        }
+        catch {
+            this.ok = false;
+        }
+        return this.ok;
+    }
+    index() { return join(this.gitDir, "amness-snapshot.index"); }
+    /** Record the working tree as a tree object and return its id (undefined when there is no git repository or git fails). */
+    async take() {
+        if (!(await this.available()))
+            return undefined;
+        try {
+            const env = { GIT_INDEX_FILE: this.index() };
+            await git(this.cwd, ["add", "-A", "--", ".", ...EXCLUDE], env);
+            return (await git(this.cwd, ["write-tree"], env)).trim();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Paths in the working tree that differ from the snapshot (changed, deleted, or created since). */
+    async changedSince(tree) {
+        const now = await this.take();
+        if (!now || now === tree)
+            return [];
+        const out = await git(this.cwd, ["diff-tree", "-r", "--name-only", "-z", tree, now]);
+        return out.split("\0").filter(Boolean);
+    }
+    /** Put the working tree back to `tree`: restore files that were changed or deleted, remove files that were created (only those git would see: ignored files are never touched). */
+    async restore(tree) {
+        if (!(await this.available()))
+            throw new Error("not a git repository");
+        const changed = await this.changedSince(tree), restored = [], removed = [];
+        if (!changed.length)
+            return { restored, removed };
+        const inTree = new Set((await git(this.cwd, ["ls-tree", "-r", "--name-only", "-z", tree])).split("\0").filter(Boolean));
+        const tmp = mkdtempSync(join(tmpdir(), "amness-restore-")), env = { GIT_INDEX_FILE: join(tmp, "index") };
+        try {
+            await git(this.cwd, ["read-tree", tree], env);
+            for (const p of changed) {
+                const abs = resolve(this.cwd, p);
+                if (abs !== this.cwd && !abs.startsWith(this.cwd + sep))
+                    continue;
+                if (inTree.has(p)) {
+                    mkdirSync(dirname(abs), { recursive: true });
+                    await git(this.cwd, ["checkout-index", "-f", "--", p], env);
+                    restored.push(p);
+                }
+                else if (existsSync(abs) && statSync(abs).isFile()) {
+                    rmSync(abs);
+                    removed.push(p);
+                }
+            }
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        return { restored, removed };
+    }
+}