amness 0.0.0-stage → 0.1.2

package/dist/src/hooks.d.ts

@@ -0,0 +1,44 @@
+export type HookEvent = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PreCompact" | "Stop" | "PreModel" | "PostModel";
+export declare const HOOK_EVENTS: HookEvent[];
+export type HookDef = {
+    match?: string;
+    command: string; /** seconds, default 10 */
+    timeout?: number; /** a crash or timeout blocks instead of being ignored */
+    failClosed?: boolean;
+};
+export type HookConfig = Partial<Record<HookEvent, HookDef[]>>;
+export type HookResult = {
+    block?: string;
+    context?: string;
+    args?: Record<string, unknown>; /** PreModel only: the tools that may be called in this turn (a call to any other is refused with an explanation) */
+    tools?: string[]; /** PreModel only: a text-only reply to this request is not the final answer; add this message and ask for the next step (for a planning phase) */
+    then?: string;
+    warnings: string[];
+};
+export type HookRunner = {
+    run(event: HookEvent, payload: Record<string, unknown>): Promise<HookResult>;
+    count(): number;
+};
+/** The environment a hook sees: no API keys, tokens or passwords. */
+export declare function scrubbedEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare class Hooks implements HookRunner {
+    private cfg;
+    private cwd;
+    private env;
+    constructor(cfg: HookConfig, cwd: string, env?: NodeJS.ProcessEnv);
+    /** Where project hooks live, and a fingerprint of their content (to remember that the user approved exactly this file). */
+    static projectFile(cwd: string): string;
+    static fingerprint(cwd: string): string | undefined;
+    /** User-level hooks always load; project hooks only when `trustProject` (a cloned repo must not run commands on your machine unasked). */
+    static load(cwd: string, o?: {
+        trustProject?: boolean;
+        userDir?: string;
+    }): Hooks;
+    count(): number;
+    list(): {
+        event: HookEvent;
+        def: HookDef;
+    }[];
+    run(event: HookEvent, payload: Record<string, unknown>): Promise<HookResult>;
+    private exec;
+}

package/dist/src/hooks.js

@@ -0,0 +1,116 @@
+// Lifecycle hooks: your own commands, run at fixed points of the agent loop, that can block a step, rewrite a tool call, or add context.
+// Same vocabulary as Claude Code and Codex, so a hook script written for one is easy to move.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { shellInvocation } from "./shell.js";
+export const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PreCompact", "Stop", "PreModel", "PostModel"];
+/** The environment a hook sees: no API keys, tokens or passwords. */
+export function scrubbedEnv(env = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (!/(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)/i.test(k))
+            out[k] = v;
+    return out;
+}
+const readCfg = (file) => {
+    if (!existsSync(file))
+        return {};
+    const j = JSON.parse(readFileSync(file, "utf8")), out = {};
+    for (const ev of HOOK_EVENTS) {
+        const list = j[ev];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            throw new Error(`${file}: "${ev}" must be a list of { command, match?, timeout? }`);
+        for (const d of list)
+            if (!d || typeof d.command !== "string")
+                throw new Error(`${file}: every "${ev}" hook needs a "command" string`);
+        out[ev] = list;
+    }
+    return out;
+};
+export class Hooks {
+    cfg;
+    cwd;
+    env;
+    constructor(cfg, cwd, env = scrubbedEnv()) { this.cfg = cfg; this.cwd = cwd; this.env = env; }
+    /** Where project hooks live, and a fingerprint of their content (to remember that the user approved exactly this file). */
+    static projectFile(cwd) { return join(cwd, ".amness", "hooks.json"); }
+    static fingerprint(cwd) { const f = Hooks.projectFile(cwd); return existsSync(f) ? createHash("sha256").update(readFileSync(f)).digest("hex").slice(0, 16) : undefined; }
+    /** User-level hooks always load; project hooks only when `trustProject` (a cloned repo must not run commands on your machine unasked). */
+    static load(cwd, o = {}) {
+        const user = readCfg(join(o.userDir ?? process.env.AMNESS_HOME ?? join(homedir(), ".amness"), "hooks.json")), project = o.trustProject ? readCfg(Hooks.projectFile(cwd)) : {};
+        const merged = {};
+        for (const ev of HOOK_EVENTS) {
+            const l = [...(user[ev] ?? []), ...(project[ev] ?? [])];
+            if (l.length)
+                merged[ev] = l;
+        }
+        return new Hooks(merged, cwd);
+    }
+    count() { return HOOK_EVENTS.reduce((n, ev) => n + (this.cfg[ev]?.length ?? 0), 0); }
+    list() { return HOOK_EVENTS.flatMap((event) => (this.cfg[event] ?? []).map((def) => ({ event, def }))); }
+    async run(event, payload) {
+        const res = { warnings: [] };
+        for (const def of this.cfg[event] ?? []) {
+            if (def.match && typeof payload.tool === "string" && !new RegExp(`^(?:${def.match})$`).test(payload.tool))
+                continue;
+            const r = await this.exec(def, { event, cwd: this.cwd, ...payload });
+            if (r.warning) {
+                if (def.failClosed) {
+                    res.block = r.warning;
+                    break;
+                }
+                res.warnings.push(r.warning);
+                continue;
+            }
+            if (r.block !== undefined) {
+                res.block = r.block;
+                break;
+            }
+            if (r.context)
+                res.context = (res.context ? res.context + "\n" : "") + r.context;
+            if (r.args)
+                res.args = r.args;
+        }
+        return res;
+    }
+    exec(def, input) {
+        return new Promise((done) => {
+            const inv = shellInvocation(def.command), p = spawn(inv.file, inv.args, { windowsHide: true, cwd: this.cwd, env: this.env, stdio: ["pipe", "pipe", "pipe"] });
+            let out = "", err = "", settled = false;
+            const finish = (v) => { if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                done(v);
+            } };
+            const timer = setTimeout(() => { p.kill("SIGKILL"); finish({ warning: `hook \`${def.command}\` timed out after ${def.timeout ?? 10}s` }); }, (def.timeout ?? 10) * 1000);
+            p.stdout.on("data", (d) => { if (out.length < 20_000)
+                out += d; });
+            p.stderr.on("data", (d) => { if (err.length < 20_000)
+                err += d; });
+            p.on("error", (e) => finish({ warning: `hook \`${def.command}\` could not start: ${e.message}` }));
+            p.stdin.on("error", () => { });
+            p.stdin.end(JSON.stringify(input));
+            p.on("close", (code) => {
+                if (code === 2)
+                    return finish({ block: (err.trim() || out.trim() || `blocked by hook \`${def.command}\``).slice(0, 2000) });
+                if (code !== 0)
+                    return finish({ warning: `hook \`${def.command}\` exited with ${code}${err.trim() ? ": " + err.trim().slice(0, 300) : ""}` });
+                const text = out.trim();
+                if (!text)
+                    return finish({});
+                try {
+                    const j = JSON.parse(text);
+                    if (j && typeof j === "object")
+                        return finish(j.decision === "block" ? { block: j.reason ?? "blocked by hook" } : { context: j.context, args: j.args && typeof j.args === "object" ? j.args : undefined });
+                }
+                catch { /* plain text */ }
+                finish({ context: text.slice(0, 4000) });
+            });
+        });
+    }
+}

package/dist/src/images.d.ts

@@ -0,0 +1,13 @@
+export type Image = {
+    mime: string;
+    data: string;
+};
+export declare const MAX_IMAGE_BYTES: number, MAX_IMAGES = 4;
+export declare const isImagePath: (p: string) => boolean;
+/** Read an image file as base64. Throws a readable error when it is too big or not an image. */
+export declare function readImage(path: string): Image;
+/**
+ * Does this model take images? OpenAI and Claude models do; for local servers it is a guess from the model name (llava, vision, -vl, gemma3, minicpm-v, pixtral, ...),
+ * so a text-only model gets a clear message instead of an obscure server error.
+ */
+export declare function visionLikely(provider: string, model: string): boolean;

package/dist/src/images.js

@@ -0,0 +1,27 @@
+// Image input: read a screenshot or picture from disk into a form the model adapters can send.
+import { readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+const MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" };
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024, MAX_IMAGES = 4;
+export const isImagePath = (p) => extname(p).toLowerCase() in MIME;
+/** Read an image file as base64. Throws a readable error when it is too big or not an image. */
+export function readImage(path) {
+    const mime = MIME[extname(path).toLowerCase()];
+    if (!mime)
+        throw new Error(`${path}: not a supported image (png, jpg, gif, webp)`);
+    const size = statSync(path).size;
+    if (size > MAX_IMAGE_BYTES)
+        throw new Error(`${path}: ${(size / 1048576).toFixed(1)} MB is over the ${MAX_IMAGE_BYTES / 1048576} MB limit`);
+    return { mime, data: readFileSync(path).toString("base64") };
+}
+/**
+ * Does this model take images? OpenAI and Claude models do; for local servers it is a guess from the model name (llava, vision, -vl, gemma3, minicpm-v, pixtral, ...),
+ * so a text-only model gets a clear message instead of an obscure server error.
+ */
+export function visionLikely(provider, model) {
+    if (provider === "anthropic")
+        return true;
+    if (provider === "openai")
+        return !/^(gpt-3|gpt-4(-0|-32k)?$|o1-mini|o1-preview|text-|davinci)/i.test(model);
+    return /llava|vision|[-_:.]vl\b|[-_]vl[-_:]|gemma-?3|minicpm-v|pixtral|llama-?3\.2-(11|90)b|moondream|bakllava|internvl|qwen.*vl|glm-4v|mistral-small-?3/i.test(model);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,57 @@
+export * from "./harness.ts";
+export * from "./schema.ts";
+export * from "./openai.ts";
+export * from "./web.ts";
+export * from "./deep.ts";
+export * from "./code.ts";
+export * from "./evals.ts";
+export * from "./dynamic.ts";
+export * from "./anthropic.ts";
+export * from "./diff.ts";
+export * from "./memory.ts";
+export * from "./bundle.ts";
+export * from "./live.ts";
+export * from "./stats.ts";
+export * from "./evalcases.ts";
+export * from "./embed.ts";
+export * from "./guidance.ts";
+export * from "./hooks.ts";
+export * from "./permissions.ts";
+export * from "./trace.ts";
+export * from "./procs.ts";
+export * from "./ledger.ts";
+export * from "./progress.ts";
+export * from "./review.ts";
+export * from "./patch.ts";
+export * from "./sandbox.ts";
+export * from "./skills.ts";
+export * from "./worktree.ts";
+export * from "./agents.ts";
+export * from "./route.ts";
+export * from "./codeindex.ts";
+export * from "./replay.ts";
+export * from "./mining.ts";
+export * from "./suites.ts";
+export * from "./router.ts";
+export * from "./profiles.ts";
+export * from "./secrets.ts";
+export * from "./snapshot.ts";
+export * from "./gitflow.ts";
+export * from "./lsp.ts";
+export * from "./tune.ts";
+export * from "./parallel.ts";
+export * from "./approver.ts";
+export * from "./images.ts";
+export * from "./acp.ts";
+export * from "./schedule.ts";
+export * from "./shell.ts";
+export * from "./hardcases.ts";
+export * from "./ratelimit.ts";
+export * from "./plugins.ts";
+export * from "./strategies.ts";
+export * from "./metrics.ts";
+export * from "./chaos.ts";
+export * from "./prompts.ts";
+export * from "./pluginscan.ts";
+export * from "./grade.ts";
+export * from "./bench.ts";

package/dist/src/index.js

@@ -0,0 +1,57 @@
+export * from "./harness.js";
+export * from "./schema.js";
+export * from "./openai.js";
+export * from "./web.js";
+export * from "./deep.js";
+export * from "./code.js";
+export * from "./evals.js";
+export * from "./dynamic.js";
+export * from "./anthropic.js";
+export * from "./diff.js";
+export * from "./memory.js";
+export * from "./bundle.js";
+export * from "./live.js";
+export * from "./stats.js";
+export * from "./evalcases.js";
+export * from "./embed.js";
+export * from "./guidance.js";
+export * from "./hooks.js";
+export * from "./permissions.js";
+export * from "./trace.js";
+export * from "./procs.js";
+export * from "./ledger.js";
+export * from "./progress.js";
+export * from "./review.js";
+export * from "./patch.js";
+export * from "./sandbox.js";
+export * from "./skills.js";
+export * from "./worktree.js";
+export * from "./agents.js";
+export * from "./route.js";
+export * from "./codeindex.js";
+export * from "./replay.js";
+export * from "./mining.js";
+export * from "./suites.js";
+export * from "./router.js";
+export * from "./profiles.js";
+export * from "./secrets.js";
+export * from "./snapshot.js";
+export * from "./gitflow.js";
+export * from "./lsp.js";
+export * from "./tune.js";
+export * from "./parallel.js";
+export * from "./approver.js";
+export * from "./images.js";
+export * from "./acp.js";
+export * from "./schedule.js";
+export * from "./shell.js";
+export * from "./hardcases.js";
+export * from "./ratelimit.js";
+export * from "./plugins.js";
+export * from "./strategies.js";
+export * from "./metrics.js";
+export * from "./chaos.js";
+export * from "./prompts.js";
+export * from "./pluginscan.js";
+export * from "./grade.js";
+export * from "./bench.js";

package/dist/src/ledger.d.ts

@@ -0,0 +1,58 @@
+export type LedgerEdit = {
+    path: string;
+    added: number;
+    removed: number;
+    created: boolean;
+    seq: number;
+    diff?: string;
+};
+export type LedgerCmd = {
+    cmd: string;
+    code: number | null;
+    test: boolean;
+    build: boolean;
+    failedOutput: boolean;
+    seq: number;
+};
+export type Audit = {
+    changed: string[];
+    testsAfterLastEdit: boolean | undefined;
+    notes: string[];
+};
+export declare const TEST_CMD: RegExp;
+export declare const BUILD_CMD: RegExp;
+export declare class Ledger {
+    edits: LedgerEdit[];
+    cmds: LedgerCmd[];
+    private seq;
+    private extraTest?;
+    constructor(o?: {
+        testCommand?: string;
+    });
+    reset(): void;
+    onEdit(e: {
+        path: string;
+        added: number;
+        removed: number;
+        created: boolean;
+        diff?: string;
+    }): void;
+    /** Every change made so far as diffs (capped), for a reviewer. */
+    diffs(max?: number): string;
+    /** The last few commands with their outcome. */
+    recentCommands(n?: number): string;
+    /** Record a shell command from its tool result (`exit=N\n...`). */
+    onCommand(cmd: string, result: string): void;
+    private lastEdit;
+    private ok;
+    /** A passing test run (or build) that happened after the last edit. */
+    private passedAfterEdit;
+    private ranAny;
+    private shellWrote;
+    /** Problems with the claims in `summary`, judged against what was recorded. `gated`: a verify command already proved the result. */
+    check(summary: string, o?: {
+        gated?: boolean;
+    }): string[];
+    /** A short factual record of the run, for the user. */
+    audit(task: string): Audit;
+}

package/dist/src/ledger.js

@@ -0,0 +1,78 @@
+export const TEST_CMD = /\b(npm\s+(run\s+)?t(est)?\b|yarn\s+test|pnpm\s+(run\s+)?test|npx\s+(jest|vitest|mocha|ava|tap)|jest|vitest|mocha|pytest|python3?\s+-m\s+(pytest|unittest)|go\s+test|cargo\s+(test|nextest)|mvn\s+(-\S+\s+)*test|gradle\w*\s+test|dotnet\s+test|make\s+(test|check)|rspec|phpunit|node\s+(--test\b|\S*test\S*\.[cm]?js)|bun\s+test|deno\s+test|ctest|swift\s+test)\b/i;
+export const BUILD_CMD = /\b(tsc\b|npm\s+run\s+(build|typecheck|lint|check)|yarn\s+(build|lint)|cargo\s+(build|check|clippy)|go\s+(build|vet)|make\b|mvn\s+(-\S+\s+)*(compile|package)|gradle\w*\s+build|eslint|ruff|mypy|pyright|next\s+build|vite\s+build|webpack)\b/i;
+const FAIL_OUTPUT = /(?:^|\n)\s*(?:FAIL\b|✖|not ok\b)|\b[1-9]\d*\s+(?:tests?\s+)?(?:failed|failing)\b|\b(?:failed|failing):\s*[1-9]|Tests:\s+\d+\s+failed|AssertionError|[1-9]\d*\s+errors?\b/i;
+const SHELL_WRITE = /\bsed\s+-i|>\s*[\w./~-]|\btee\b|\bmv\b|\bcp\b|\bgit\s+(apply|checkout|restore|stash|reset|mv)\b|\bpatch\b|\bperl\s+-p?i|\btouch\b|\bmkdir\b/;
+const NEG = /\b(?:not|n't|no|never|without|fail\w*|broken|still)\b[^.\n]{0,25}$/i;
+export class Ledger {
+    edits = [];
+    cmds = [];
+    seq = 0;
+    extraTest;
+    constructor(o = {}) { if (o.testCommand)
+        this.extraTest = new RegExp(o.testCommand.trim().split(/\s+/).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("\\s+")); }
+    reset() { this.edits = []; this.cmds = []; this.seq = 0; }
+    onEdit(e) { this.edits.push({ path: e.path, added: e.added, removed: e.removed, created: e.created, seq: ++this.seq, diff: e.diff?.slice(0, 6000) }); }
+    /** Every change made so far as diffs (capped), for a reviewer. */
+    diffs(max = 24_000) { let out = ""; for (const e of this.edits) {
+        const d = `### ${e.path}${e.created ? " (new)" : ""}\n${e.diff ?? `+${e.added} -${e.removed}`}\n`;
+        if (out.length + d.length > max) {
+            out += `[... ${this.edits.length} edits in total; the rest are not shown]\n`;
+            break;
+        }
+        out += d;
+    } return out; }
+    /** The last few commands with their outcome. */
+    recentCommands(n = 8) { return this.cmds.slice(-n).map((c) => `- ${c.cmd.slice(0, 120)} → exit ${c.code ?? "?"}${c.failedOutput ? " (failures in output)" : ""}`).join("\n"); }
+    /** Record a shell command from its tool result (`exit=N\n...`). */
+    onCommand(cmd, result) {
+        const m = /^exit=(\d+)/.exec(result), code = m ? Number(m[1]) : /^exit=/.test(result) ? null : null;
+        this.cmds.push({ cmd, code: m ? code : null, test: TEST_CMD.test(cmd) || !!this.extraTest?.test(cmd), build: BUILD_CMD.test(cmd), failedOutput: FAIL_OUTPUT.test(result), seq: ++this.seq });
+    }
+    lastEdit() { return this.edits.at(-1)?.seq ?? 0; }
+    ok(c) { return c.code === 0 && !c.failedOutput; }
+    /** A passing test run (or build) that happened after the last edit. */
+    passedAfterEdit(kind) { const le = this.lastEdit(); return this.cmds.some((c) => c[kind] && c.seq > le && this.ok(c)); }
+    ranAny(kind) { return this.cmds.some((c) => c[kind]); }
+    shellWrote() { return this.cmds.some((c) => SHELL_WRITE.test(c.cmd)); }
+    /** Problems with the claims in `summary`, judged against what was recorded. `gated`: a verify command already proved the result. */
+    check(summary, o = {}) {
+        const problems = [], s = summary;
+        const claimed = (re) => { for (const m of s.matchAll(new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g"))) {
+            if (!NEG.test(s.slice(Math.max(0, m.index - 30), m.index)))
+                return true;
+        } return false; };
+        const testClaim = /\b(?:all\s+)?(?:unit\s+|integration\s+)?(?:tests?|specs?|test suite|suite)\b[^.\n]{0,40}?\b(?:pass(?:es|ed|ing)?|green|succe(?:ed|eds|eded|ssful)|ok)\b|\b(?:pass(?:es|ed|ing)?)\b[^.\n]{0,15}\b(?:tests?|suite)\b|\b\d+\s*\/\s*\d+\s+(?:tests?\s+)?pass/i;
+        const buildClaim = /\b(?:build|compil\w+|type-?check\w*|lint\w*)\b[^.\n]{0,30}?\b(?:pass(?:es|ed)?|succe\w+|clean|ok|works?|without errors)\b/i;
+        if (!o.gated && claimed(testClaim)) {
+            if (!this.ranAny("test"))
+                problems.push("you say the tests pass, but no test command was run in this session. Run the tests, or remove the claim.");
+            else if (!this.passedAfterEdit("test"))
+                problems.push(this.edits.length && this.cmds.some((c) => c.test && !this.ok(c) && c.seq > this.lastEdit()) ? "you say the tests pass, but the last test run after your final edit failed." : "you say the tests pass, but no test run succeeded after your last edit. Run them again.");
+        }
+        if (!o.gated && claimed(buildClaim) && !this.passedAfterEdit("build") && !this.passedAfterEdit("test"))
+            problems.push("you say the build/typecheck/lint is clean, but no such command succeeded after your last edit.");
+        if (!this.shellWrote()) {
+            const verbs = /\b(?:fix(?:ed)?|updat(?:ed?)|chang(?:ed?)|add(?:ed)?|implement(?:ed)?|modif(?:y|ied)|edit(?:ed)?|renam(?:ed?)|creat(?:ed?)|remov(?:ed?)|delet(?:ed?)|refactor(?:ed)?|rewr(?:ote|itten))\b[^.;()\n]{0,30}?`?([\w@./-]+\.[A-Za-z]{1,5})`?/gi;
+            const touched = new Set(this.edits.map((e) => e.path.replace(/^\.\//, "")));
+            const missing = [...new Set([...s.matchAll(verbs)].map((m) => m[1].replace(/^\.\//, "")))].filter((p) => p.includes("/") || /\.(?:[cm]?[jt]sx?|py|go|rs|java|rb|php|css|html|json|md|ya?ml|toml|sh|c|cc|cpp|h)$/.test(p)).filter((p) => ![...touched].some((t) => t === p || t.endsWith("/" + p) || p.endsWith("/" + t)));
+            if (missing.length)
+                problems.push(`the summary says ${missing.slice(0, 3).join(", ")} ${missing.length === 1 ? "was" : "were"} changed, but no edit to ${missing.length === 1 ? "it" : "them"} was recorded.`);
+        }
+        return problems;
+    }
+    /** A short factual record of the run, for the user. */
+    audit(task) {
+        const changed = [...new Set(this.edits.map((e) => e.path))], notes = [];
+        const tests = changed.filter((p) => /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[a-z]+$|_test\.(go|py)$/i.test(p));
+        if (tests.length && !/\b(tests?|specs?)\b/i.test(task))
+            notes.push(`test files were modified although the task did not mention tests: ${tests.slice(0, 3).join(", ")}`);
+        if (changed.length > 8)
+            notes.push(`${changed.length} files changed, which is a lot for one task: check the diff`);
+        const testsAfter = this.edits.length ? (this.ranAny("test") ? this.passedAfterEdit("test") : undefined) : undefined;
+        if (this.edits.length && testsAfter === undefined)
+            notes.push("no test command was run");
+        else if (testsAfter === false)
+            notes.push("the last test run after the final edit did not pass");
+        return { changed, testsAfterLastEdit: testsAfter, notes };
+    }
+}

package/dist/src/live.d.ts

@@ -0,0 +1,16 @@
+import type { Event } from "./harness.ts";
+/**
+ * Live view of a run in the browser: file diffs as they land, tool timeline, token meter.
+ * Serves on 127.0.0.1 only and rejects foreign Host headers (DNS-rebinding guard). Events are rendered with textContent,
+ * never as HTML, because diffs contain untrusted file contents.
+ */
+export declare function startLive(o?: {
+    port?: number;
+    title?: string;
+}): Promise<{
+    url: string;
+    onEvent(e: Event & {
+        agent?: string;
+    }): void;
+    close: () => Promise<void>;
+}>;

package/dist/src/live.js

@@ -0,0 +1,80 @@
+import { createServer } from "node:http";
+/**
+ * Live view of a run in the browser: file diffs as they land, tool timeline, token meter.
+ * Serves on 127.0.0.1 only and rejects foreign Host headers (DNS-rebinding guard). Events are rendered with textContent,
+ * never as HTML, because diffs contain untrusted file contents.
+ */
+export async function startLive(o = {}) {
+    const history = [], clients = new Set();
+    const server = createServer((req, res) => {
+        const host = (req.headers.host ?? "").replace(/:\d+$/, "");
+        if (host !== "127.0.0.1" && host !== "localhost") {
+            res.writeHead(403).end("forbidden");
+            return;
+        }
+        if (req.url === "/events") {
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+            history.forEach((d) => res.write(`data: ${d}\n\n`));
+            clients.add(res);
+            req.on("close", () => clients.delete(res));
+        }
+        else if (req.url === "/" || req.url?.startsWith("/?")) {
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'" });
+            res.end(PAGE.replace("__TITLE__", (o.title ?? "Amness live").replace(/[<>&"]/g, "")));
+        }
+        else
+            res.writeHead(404).end();
+    });
+    await new Promise((ok, fail) => { server.once("error", fail); server.listen(o.port ?? 0, "127.0.0.1", ok); });
+    const url = `http://127.0.0.1:${server.address().port}`;
+    return {
+        url,
+        onEvent(e) {
+            const d = JSON.stringify({ ...e, t: Date.now(), ...("diff" in e && { diff: e.diff.slice(0, 30_000) }), ...("result" in e && { result: e.result.slice(0, 400) }) });
+            history.push(d);
+            if (history.length > 1000)
+                history.shift();
+            clients.forEach((c) => c.write(`data: ${d}\n\n`));
+        },
+        close: () => new Promise((ok) => { clients.forEach((c) => c.end()); server.close(() => ok()); server.closeAllConnections?.(); }),
+    };
+}
+const PAGE = `<!doctype html><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><title>__TITLE__</title>
+<style>
+:root{--bg:#0f1115;--fg:#e6e8ee;--mut:#8b93a7;--card:#171a21;--bd:#262b36;--add:#1f6f43;--addfg:#8ff0b3;--del:#7a2630;--delfg:#ffb3bd;--hunk:#7aa2ff;--acc:#7aa2ff}
+@media(prefers-color-scheme:light){:root{--bg:#f6f7f9;--fg:#1b1f27;--mut:#667085;--card:#fff;--bd:#e3e6ec;--add:#d6f5e1;--addfg:#0b5d2a;--del:#fde0e3;--delfg:#8a1c2b;--hunk:#2a55c5;--acc:#2a55c5}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.45 system-ui,sans-serif}
+header{display:flex;gap:16px;align-items:center;padding:10px 16px;border-bottom:1px solid var(--bd);position:sticky;top:0;background:var(--bg)}
+header b{font-size:15px}.dot{width:9px;height:9px;border-radius:50%;background:#e5a50a}.dot.on{background:#2ea043}.dot.off{background:#6e7681}
+.m{color:var(--mut)}main{display:grid;grid-template-columns:minmax(260px,32%) 1fr;gap:12px;padding:12px 16px}
+@media(max-width:800px){main{grid-template-columns:1fr}}
+.col{display:flex;flex-direction:column;gap:8px;min-width:0}h2{font-size:12px;letter-spacing:.06em;text-transform:uppercase;color:var(--mut);margin:4px 0}
+.ev{padding:6px 10px;border:1px solid var(--bd);border-radius:8px;background:var(--card);word-break:break-word}.ev.bad{border-color:#b4414c}.ev.warn{border-color:#b08800}
+.ev small{color:var(--mut)}.f{border:1px solid var(--bd);border-radius:10px;background:var(--card);overflow:hidden}
+.f>div{padding:8px 12px;font-weight:600;display:flex;gap:10px;align-items:center;border-bottom:1px solid var(--bd);position:sticky;top:48px;background:var(--card)}
+pre{margin:0;padding:6px 0;overflow:auto;font:12.5px/1.5 ui-monospace,Menlo,monospace}pre span{display:block;padding:0 12px;white-space:pre}
+.a{background:var(--add);color:var(--addfg)}.d{background:var(--del);color:var(--delfg)}.h{color:var(--hunk)}.c{color:var(--mut)}
+label{margin-left:auto;display:flex;gap:6px;align-items:center}
+</style>
+<header><span class="dot" id=dot></span><b>__TITLE__</b><span class=m id=stat>waiting for events…</span><label class=m><input type=checkbox id=follow checked>follow</label></header>
+<main><div class=col><h2>Timeline</h2><div class=col id=tl></div></div><div class=col><h2>Changes</h2><div class=col id=files><span class=m>No edits yet.</span></div></div></main>
+<script>
+const $=id=>document.getElementById(id),tl=$("tl"),files=$("files");let steps=0,tokens=0,edits=0,cards={};
+const el=(t,c,x)=>{const e=document.createElement(t);if(c)e.className=c;if(x!=null)e.textContent=x;return e};
+function ev(text,cls,sub){const e=el("div","ev "+(cls||""),text);if(sub){e.append(el("br"),el("small",0,sub))}tl.append(e);return e}
+function card(p){if(cards[p])return cards[p];if(files.firstChild&&!files.firstChild.className)files.textContent="";const f=el("div","f"),h=el("div",0,p),s=el("span","m","");h.append(s);f.append(h);const pre=el("pre");f.append(pre);files.append(f);return cards[p]={f,s,pre,a:0,r:0}}
+function on(e){
+ const who=e.agent&&e.agent!=="lead"?"["+e.agent+"] ":"";
+ if(e.kind==="turn"){steps=e.step+1;tokens=e.tokens}
+ else if(e.kind==="tool"){const bad=/^(ERROR|DENIED|REJECTED|exit=[^0])/.test(e.result);let a="";try{const j=JSON.parse(e.args);a=j.cmd||j.path||j.query||j.url||j.description||""}catch{}ev(who+e.name+" "+String(a).slice(0,90),bad?"bad":"",bad?e.result.slice(0,140):"")}
+ else if(e.kind==="edit"){edits++;const c=card(e.path);c.a+=e.added;c.r+=e.removed;c.s.textContent=(e.created?"new  ":"")+"+"+c.a+" −"+c.r;
+  const sep=el("span","c","── edit "+edits+" ──");c.pre.append(sep);
+  for(const l of e.diff.split("\\n")){if(/^(---|\\+\\+\\+)/.test(l))continue;c.pre.append(el("span",l[0]==="+"?"a":l[0]==="-"?"d":l[0]==="@"?"h":"",l))}
+  ev("✎ "+e.path,"","+"+e.added+" −"+e.removed)}
+ else if(e.kind==="rollover")ev("⟳ context rolled over","warn",e.detail);
+ else if(e.kind==="finish"){ev("✔ finished","",e.summary);$("dot").className="dot off"}
+ else if(e.detail)ev(e.kind+": "+e.detail.slice(0,160),["denied","budget","rejected"].includes(e.kind)?"bad":"warn");
+ $("stat").textContent=steps+" turns · "+tokens.toLocaleString()+" tokens · "+edits+" edits";
+ if($("follow").checked)scrollTo(0,document.body.scrollHeight)}
+const es=new EventSource("/events");es.onopen=()=>$("dot").className="dot on";es.onerror=()=>$("dot").className="dot";es.onmessage=m=>on(JSON.parse(m.data));
+</script>`;

package/dist/src/lsp.d.ts

@@ -0,0 +1,31 @@
+export type LspServer = {
+    name: string;
+    command: string;
+    args: string[];
+    extensions: string[];
+    languageId: (ext: string) => string;
+};
+export declare const DEFAULT_SERVERS: LspServer[];
+export type Diagnostic = {
+    line: number;
+    col: number;
+    message: string;
+    severity: number;
+    source?: string;
+};
+export declare class Diagnostics {
+    private clients;
+    private root;
+    private servers;
+    private missing;
+    constructor(root: string, o?: {
+        servers?: LspServer[];
+    });
+    /** Which server would handle this file, if one is installed. */
+    serverFor(path: string): LspServer | undefined;
+    errors(path: string): Promise<Diagnostic[] | undefined>;
+    /** Text to append to an edit result: the errors the language server reports for these files, or "" when there are none (or no server). */
+    report(paths: string[]): Promise<string>;
+    dispose(): Promise<void>;
+    installed(): string[];
+}