agent-from-zero 0.5.0 → 0.28.0

package/dist/background.js

@@ -0,0 +1,160 @@
+// ============ Background tasks (Day 37) ============
+// The problem: run_bash blocks. A command that takes longer than its 30s
+// watchdog (npm install, a full test run, a build) is SIGKILLed before it
+// finishes, and even a 25s one freezes the agent — we sit idle, paying for
+// tokens we aren't using, while a child process churns. The model cannot think
+// and wait at the same time.
+//
+// The fix, mirroring Claude Code: a command can be sent to the BACKGROUND. We
+// spawn it, hand the model a task id immediately, and let the loop keep going.
+// When the command finishes, the loop injects a <task_notification> as the next
+// user turn — so the result rejoins the conversation without ever having blocked
+// it. Long-running servers (npm run dev) that never "finish" are supported too:
+// they stay `running` forever and the model polls them with bash_output.
+//
+// Why no extra thread / lock (unlike the Python reference): Node is single-
+// threaded with an event loop. `spawn` is already async — stdout/stderr arrive
+// as events while the main loop runs. There is no shared-memory race to guard,
+// so the whole "daemon thread + mutex" dance collapses into plain callbacks.
+import { spawn } from "node:child_process";
+const tasks = new Map(); // id → task, for the whole session
+let seq = 0; // increments per task — seeds the id
+const OUTPUT_CAP = 80_000; // chars of output retained per task (keep the tail)
+const SUMMARY_TAIL = 1_500; // chars of the tail shown inline in a notification
+// Append output to a task, keeping only the most recent OUTPUT_CAP chars. We
+// keep the TAIL, not the head: an exit error or a "server ready on :3000" line
+// lands at the end, and that is what the model needs to react to. `produced`
+// counts everything ever written so the poll cursor stays correct across trims.
+function append(task, chunk) {
+    task.produced += chunk.length;
+    task.output += chunk;
+    if (task.output.length > OUTPUT_CAP)
+        task.output = task.output.slice(-OUTPUT_CAP);
+}
+// Start a command in the background. Returns its task id immediately — the
+// command keeps running after this returns. Note the deliberate omissions vs
+// run_bash: NO 30s timeout (the whole point is to outlive it) and NO turn
+// AbortSignal (Ctrl+C interrupts the current turn, but a background job is meant
+// to survive into later turns; only killAll, on session exit, stops them).
+export function startBackground(command) {
+    const id = `bg_${++seq}`;
+    const child = spawn(command, { shell: true, stdio: ["ignore", "pipe", "pipe"] }); // shell:true → bash semantics, same as run_bash
+    const task = {
+        id,
+        command,
+        child,
+        status: "running",
+        exitCode: null,
+        output: "",
+        produced: 0,
+        readAt: 0,
+        notified: false,
+        startedAt: Date.now(),
+        endedAt: null,
+    };
+    tasks.set(id, task);
+    child.stdout?.on("data", (d) => append(task, d.toString())); // stream output into the buffer as it arrives
+    child.stderr?.on("data", (d) => append(task, d.toString()));
+    child.on("error", (err) => {
+        // The process could not even start (e.g. command not found). Record it as a
+        // failure with the reason, so the notification explains what happened.
+        append(task, `\n[could not start: ${err.message}]`);
+        if (task.status === "running") {
+            task.status = "failed";
+            task.exitCode = null;
+            task.endedAt = Date.now();
+        }
+    });
+    child.on("close", (code, signal) => {
+        if (task.status !== "running")
+            return; // already terminal (killAll set `killed`, or an error fired) — don't overwrite
+        task.exitCode = code;
+        task.status = code === 0 ? "completed" : "failed";
+        if (signal)
+            task.status = "killed"; // killed by a signal, not its own exit
+        task.endedAt = Date.now();
+    });
+    return id;
+}
+// Collect notifications for every task that has FINISHED since the last call.
+// Each task is reported exactly once (the `notified` flag), so calling this
+// every round is safe: a finished task surfaces once, then never again. Returns
+// "" when there is nothing to report. The <task_notification> shape is taken
+// straight from the tutorial reference so the format is consistent across the
+// course.
+export function pendingNotifications() {
+    const done = [];
+    for (const task of tasks.values()) {
+        if (task.status === "running" || task.notified)
+            continue; // still going, or already reported
+        task.notified = true; // report it once
+        const secs = task.endedAt ? Math.round((task.endedAt - task.startedAt) / 1000) : 0;
+        const tail = task.output.slice(-SUMMARY_TAIL).trim() || "(no output)";
+        const more = task.output.length > SUMMARY_TAIL ? " (truncated — use bash_output for the full log)" : "";
+        done.push(`<task_notification>\n` +
+            `  <task_id>${task.id}</task_id>\n` +
+            `  <status>${task.status}</status>\n` +
+            `  <command>${task.command}</command>\n` +
+            `  <exit_code>${task.exitCode ?? "n/a"}</exit_code>\n` +
+            `  <elapsed>${secs}s</elapsed>\n` +
+            `  <summary>${tail}${more}</summary>\n` +
+            `</task_notification>`);
+    }
+    if (!done.length)
+        return "";
+    // The framing line matters: without it the model can mistake the XML for
+    // something it must echo. Tell it plainly that a job it started has finished.
+    return `A background task you started has finished. Read the notification, then continue.\n\n${done.join("\n\n")}`;
+}
+// Read a background task's current state for the bash_output tool. Returns only
+// the output PRODUCED SINCE THE LAST POLL (like Claude Code's BashOutput), so
+// the model can watch a long job without re-reading the whole log each time.
+// `full: true` returns the entire retained buffer instead.
+export function readBackground(id, full = false) {
+    const task = tasks.get(id);
+    if (!task) {
+        const known = [...tasks.keys()];
+        return `[error] No background task "${id}". ${known.length ? `Known tasks: ${known.join(", ")}.` : "No background tasks have been started this session."}`;
+    }
+    let chunk;
+    if (full) {
+        chunk = task.output; // the entire retained buffer
+    }
+    else {
+        const fresh = task.produced - task.readAt; // chars produced since last poll
+        // Trimming may have dropped older chars; never read past what we still hold.
+        chunk = task.output.slice(Math.max(0, task.output.length - fresh));
+    }
+    task.readAt = task.produced; // either way, the model has now seen up to here — next poll shows only newer output
+    const head = `[${task.id}] ${task.status}${task.exitCode !== null ? ` (exit ${task.exitCode})` : ""} · ${task.command}`;
+    // Be precise about an empty body: nothing ever vs. nothing NEW since the last
+    // poll (the model already read it) vs. nothing new yet on a still-running job.
+    const body = chunk.trim() || (task.produced === 0 ? "(no output)" : task.status === "running" ? "(no new output yet)" : "(no new output)");
+    return `${head}\n${body}`;
+}
+// A one-line-per-task snapshot for the /bg command. Newest first.
+export function listBackground() {
+    return [...tasks.values()]
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .map((t) => ({
+        id: t.id,
+        status: t.status,
+        command: t.command,
+        elapsed: Math.round(((t.endedAt ?? Date.now()) - t.startedAt) / 1000),
+    }));
+}
+// True if any task is still running — the REPL uses this to warn before exit.
+export function hasRunningBackground() {
+    return [...tasks.values()].some((t) => t.status === "running");
+}
+// Kill every still-running task. Called on session exit so a forgotten dev
+// server or a slow install does not outlive the agent as an orphan.
+export function killAllBackground() {
+    for (const task of tasks.values()) {
+        if (task.status !== "running")
+            continue;
+        task.child.kill("SIGKILL");
+        task.status = "killed";
+        task.endedAt = Date.now();
+    }
+}

package/dist/board.js

@@ -0,0 +1,179 @@
+// ============ The shared task board (Day 40) ============
+// Day 38/39 gave us a team, but the LEAD still had to hand every teammate its
+// work by message. That doesn't scale: with twenty tasks the lead becomes a
+// dispatcher, and a teammate that finishes early sits idle while the lead is
+// busy. s17's fix: a shared TASK BOARD that agents pull from THEMSELVES. The
+// lead (or a teammate) drops tasks on the board; any idle teammate scans it,
+// CLAIMS a ready one, does it, marks it complete, and scans again — autonomous
+// work distribution with no dispatcher in the middle.
+//
+// Like the mailboxes, the board is ON DISK (落盘) for observability: each task is
+// a .mini-agent/tasks/<id>.json file you can read while the team runs. And like
+// the mailboxes, it needs NO lock despite "concurrent" claimers: claimTask is a
+// synchronous read-check-write, and on one event loop a synchronous function
+// runs to completion without yielding — so two teammates can never both win the
+// same task. (The Python reference uses proper-lockfile because its teammates are
+// OS threads; production CC adds fs.watch + atomic claim-with-busy-check.)
+//
+// Not to be confused with todo_write (Day 36): that is one agent's PRIVATE
+// checklist; this is the team's SHARED, claimable work queue.
+import fs from "node:fs"; // tasks are real files
+import path from "node:path"; // path joining
+let seq = 0; // increments per task — seeds the id
+let wiped = false; // wipe stale board files once per process run (like team.ts)
+// Resolved lazily so it tracks the cwd, exactly like the session + team dirs.
+function boardRoot() {
+    const root = path.resolve(".mini-agent", "tasks");
+    fs.mkdirSync(root, { recursive: true });
+    if (!wiped) {
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".json"))
+                fs.rmSync(path.join(root, f)); // fresh board for this run
+        wiped = true;
+    }
+    return root;
+}
+const taskPath = (id) => path.join(boardRoot(), `${id}.json`);
+function saveTask(task) {
+    fs.writeFileSync(taskPath(task.id), JSON.stringify(task, null, 2)); // pretty, so `cat` is readable
+}
+export function getTask(id) {
+    try {
+        return JSON.parse(fs.readFileSync(taskPath(id), "utf8"));
+    }
+    catch {
+        return undefined; // missing or corrupt
+    }
+}
+// Every task on the board, oldest first (creation order = the natural reading
+// order for a dependency graph).
+export function listTasks() {
+    const root = boardRoot();
+    return fs
+        .readdirSync(root)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(root, f), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((t) => t !== null)
+        .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+// Create a task. `blockedBy` may reference ids that don't exist yet — canStart
+// treats an unknown dependency as "not satisfied", so order of creation is free.
+export function createTask(subject, description = "", blockedBy = []) {
+    const task = { id: `task_${++seq}`, subject, description, status: "pending", owner: null, blockedBy, createdAt: Date.now() };
+    saveTask(task);
+    return task;
+}
+// Resolve a blockedBy entry to a task. Models naturally reference a dependency
+// by its SUBJECT ("alpha") rather than its id ("task_1"), so we accept either —
+// id first, then a unique subject match. Returns undefined if it matches nothing
+// (or an ambiguous subject), which canStart then treats as still-blocking.
+export function resolveDep(dep) {
+    const byId = getTask(dep);
+    if (byId)
+        return byId;
+    const bySubject = listTasks().filter((t) => t.subject === dep);
+    return bySubject.length === 1 ? bySubject[0] : undefined; // ignore an ambiguous subject
+}
+// Can this task be started? Only if every blockedBy dependency resolves to a
+// COMPLETED task. A missing/ambiguous dependency counts as blocking (fail closed).
+export function canStart(id) {
+    const task = getTask(id);
+    if (!task)
+        return false;
+    return task.blockedBy.every((dep) => resolveDep(dep)?.status === "completed");
+}
+// Claim a task for `owner`. The critical section: read, check it's still
+// pending+unowned+ready, then write owner+in_progress — all synchronous, so it
+// is atomic against any other agent on this event loop. Returns ok=false (with a
+// reason) if someone else got there first or a dependency isn't done.
+export function claimTask(id, owner) {
+    const task = getTask(id);
+    if (!task)
+        return { ok: false, error: `No task "${id}".` };
+    if (task.status !== "pending")
+        return { ok: false, error: `Task ${id} is ${task.status}${task.owner ? ` (owner ${task.owner})` : ""}, not claimable.` };
+    if (task.owner)
+        return { ok: false, error: `Task ${id} is already owned by ${task.owner}.` };
+    if (!canStart(id))
+        return { ok: false, error: `Task ${id} is blocked by unfinished tasks: ${task.blockedBy.filter((d) => resolveDep(d)?.status !== "completed").join(", ")}.` };
+    task.owner = owner;
+    task.status = "in_progress";
+    saveTask(task);
+    return { ok: true, task };
+}
+// Complete a task and report which downstream tasks it just unblocked (so the
+// claimer can mention them, and the board moves forward).
+export function completeTask(id, by) {
+    const task = getTask(id);
+    if (!task)
+        return { ok: false, error: `No task "${id}".` };
+    if (task.status !== "in_progress")
+        return { ok: false, error: `Task ${id} is ${task.status}, not in progress.` };
+    if (by && task.owner && task.owner !== by)
+        return { ok: false, error: `Task ${id} is owned by ${task.owner}, not ${by}.` };
+    task.status = "completed";
+    saveTask(task);
+    // Tasks that listed this one as a dependency (by id or subject) and are now
+    // ready just opened up.
+    const unblocked = listTasks()
+        .filter((t) => t.status === "pending" && !t.owner && t.blockedBy.some((d) => resolveDep(d)?.id === id) && canStart(t.id))
+        .map((t) => t.id);
+    return { ok: true, unblocked };
+}
+// Scan for the next task this agent can take and CLAIM it, atomically. Returns
+// the claimed task, or null if nothing is available right now. This is the heart
+// of autonomy: an idle teammate calls this and either gets work or keeps waiting.
+// Trying each candidate (rather than just the first) closes the race where two
+// agents scanned the same "available" task — the loser simply tries the next.
+export function claimNextAvailable(owner) {
+    for (const t of listTasks()) {
+        if (t.status !== "pending" || t.owner || !canStart(t.id))
+            continue;
+        const res = claimTask(t.id, owner);
+        if (res.ok)
+            return res.task;
+    }
+    return null;
+}
+// Is there pending-and-ready work nobody has claimed? Used to tell "the board is
+// genuinely drained" from "a teammate is briefly between tasks".
+export function hasClaimableWork() {
+    return listTasks().some((t) => t.status === "pending" && !t.owner && canStart(t.id));
+}
+// Any task not yet completed — the board still has open work (claimed or not).
+export function hasOpenTasks() {
+    return listTasks().some((t) => t.status !== "completed");
+}
+// A compact, human-readable board snapshot — for the list_tasks tool result and
+// the /tasks command. One line per task: status, id, owner, deps.
+export function boardSummary() {
+    const tasks = listTasks();
+    if (!tasks.length)
+        return "(the task board is empty)";
+    const icon = { pending: "○", in_progress: "◐", completed: "✓" };
+    return tasks
+        .map((t) => {
+        const owner = t.owner ? ` @${t.owner}` : "";
+        const deps = t.blockedBy.length ? ` (blockedBy: ${t.blockedBy.join(", ")})` : "";
+        return `${icon[t.status]} ${t.id} [${t.status}${owner}] ${t.subject}${deps}`;
+    })
+        .join("\n");
+}
+// Wipe the board: delete every task file and reset the counter. Called on
+// /clear, /resume, and when the lead disbands the team — each task starts fresh.
+export function resetBoard() {
+    const root = path.resolve(".mini-agent", "tasks");
+    if (fs.existsSync(root))
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".json"))
+                fs.rmSync(path.join(root, f));
+    seq = 0;
+    wiped = true; // we just cleared it; don't re-wipe on the next touch this run
+}

package/dist/config.js

@@ -52,6 +52,10 @@ export const CONFIG = {
         process.env.DEEPSEEK_API_KEY || // ...over the back-compat one
         "", // empty = missing; requireApiKey() turns that into a helpful error
     model: process.env.MINI_AGENT_MODEL || projectSettings.model || globalSettings.model || "deepseek-chat", // must support function calling
+    // Sub-agents (the task tool) can run on a DIFFERENT model than the orchestrator:
+    // a cheap/fast one for grunt work (reading many files, broad search), or a
+    // strong one as an "advisor" to double-check. undefined → use the main model.
+    subAgentModel: process.env.MINI_AGENT_SUBAGENT_MODEL || projectSettings.subAgentModel || globalSettings.subAgentModel || undefined,
     contextWindow: Number(process.env.MINI_AGENT_CONTEXT_WINDOW) || // env override first
         projectSettings.contextWindow || // then files
         globalSettings.contextWindow ||
@@ -62,14 +66,44 @@ export const CONFIG = {
         allow: [...(globalSettings.permissions?.allow ?? []), ...(projectSettings.permissions?.allow ?? [])],
         deny: [...(globalSettings.permissions?.deny ?? []), ...(projectSettings.permissions?.deny ?? [])],
     },
-    hooks: {
-        // Hook lists also concatenate: global hooks run first, then project hooks.
-        PreToolUse: [...(globalSettings.hooks?.PreToolUse ?? []), ...(projectSettings.hooks?.PreToolUse ?? [])],
-        PostToolUse: [...(globalSettings.hooks?.PostToolUse ?? []), ...(projectSettings.hooks?.PostToolUse ?? [])],
-        SessionStart: [...(globalSettings.hooks?.SessionStart ?? []), ...(projectSettings.hooks?.SessionStart ?? [])],
-        Stop: [...(globalSettings.hooks?.Stop ?? []), ...(projectSettings.hooks?.Stop ?? [])],
+    // Hooks for every event, merged across layers (global first, then project) by
+    // a generic union so adding a new event needs no edit here.
+    hooks: (() => {
+        const merged = {};
+        for (const src of [globalSettings.hooks, projectSettings.hooks]) {
+            for (const [event, defs] of Object.entries(src ?? {}))
+                merged[event] = [...(merged[event] ?? []), ...(defs ?? [])];
+        }
+        return merged;
+    })(),
+    // MCP servers: project entries override global ones with the same name.
+    mcpServers: { ...(globalSettings.mcpServers ?? {}), ...(projectSettings.mcpServers ?? {}) },
+    // LLM permission judge: off unless a settings file turns it on. Project wins.
+    judge: {
+        enabled: projectSettings.judge?.enabled ?? globalSettings.judge?.enabled ?? false,
+        model: projectSettings.judge?.model || globalSettings.judge?.model || undefined, // undefined → use the main model
+    },
+    // Token prices for the /cost estimate (defaults applied in cost.ts). Project
+    // overrides global; either may set just the fields it cares about.
+    pricing: { ...(globalSettings.pricing ?? {}), ...(projectSettings.pricing ?? {}) },
+    // Long-term memory: auto-extract durable facts after each turn. Off by default
+    // — it costs an extra (cheap) model call per turn. Project overrides global.
+    memory: {
+        autoExtract: projectSettings.memory?.autoExtract ?? globalSettings.memory?.autoExtract ?? false,
     },
 };
+// Persist a single key to the global settings file, preserving all other keys.
+// Used by /model to remember the user's last choice across sessions.
+export function saveGlobalSetting(key, value) {
+    const dir = path.dirname(GLOBAL_SETTINGS_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const current = fs.existsSync(GLOBAL_SETTINGS_PATH)
+        ? JSON.parse(fs.readFileSync(GLOBAL_SETTINGS_PATH, "utf8"))
+        : {};
+    current[key] = value;
+    fs.writeFileSync(GLOBAL_SETTINGS_PATH, JSON.stringify(current, null, 2) + "\n");
+}
 // No key, no point: fail with instructions instead of a stack trace later.
 export function requireApiKey() {
     if (CONFIG.apiKey)

package/dist/cost.js

@@ -0,0 +1,93 @@
+// Token & cost accounting. The most-emphasized lesson of the Harness book is
+// token economics: "cache breaks are silent", "90% of the bill is re-sending
+// the same prompt". You cannot manage what you cannot see — so every model
+// call's usage is metered, and /cost shows tokens, the cache hit rate, and an
+// estimated spend. Nothing here leaves the machine; it is just arithmetic over
+// the `usage` the API already returns.
+export const DEFAULT_PRICING = {
+    inputPerM: 0.27, // $ / 1M — check your provider; override in settings.pricing
+    cachedInputPerM: 0.07, // cache hits are ~4x cheaper — this is why hit rate matters
+    outputPerM: 1.1, // output is the pricey one — don't let the model ramble
+};
+// Normalize a provider `usage` object into our four fields. Handles DeepSeek
+// (prompt_cache_hit_tokens / prompt_cache_miss_tokens) and OpenAI
+// (prompt_tokens_details.cached_tokens) shapes; falls back gracefully.
+export function normalizeUsage(usage) {
+    if (!usage)
+        return { inputUncached: 0, inputCached: 0, output: 0 };
+    const prompt = Number(usage.prompt_tokens ?? 0); // total input tokens
+    const output = Number(usage.completion_tokens ?? 0); // total output tokens
+    // DeepSeek reports the split directly:
+    const dsHit = Number(usage.prompt_cache_hit_tokens ?? NaN);
+    const dsMiss = Number(usage.prompt_cache_miss_tokens ?? NaN);
+    if (!Number.isNaN(dsHit) && !Number.isNaN(dsMiss)) {
+        return { inputUncached: dsMiss, inputCached: dsHit, output };
+    }
+    // OpenAI reports only the cached count, nested:
+    const details = usage.prompt_tokens_details;
+    const cached = Number(details?.cached_tokens ?? 0);
+    return { inputUncached: Math.max(0, prompt - cached), inputCached: cached, output };
+}
+// Estimated dollar cost of some usage under some pricing. Pure — easy to test.
+export function costOf(u, p) {
+    return (u.inputUncached * p.inputPerM + u.inputCached * p.cachedInputPerM + u.output * p.outputPerM) / 1_000_000;
+}
+// Cache hit rate over input tokens, 0..1. The single most useful number for
+// spotting a silent cache break: if it drops, you are paying full price for a
+// prefix that should have been free.
+export function cacheHitRate(u) {
+    const input = u.inputUncached + u.inputCached;
+    return input === 0 ? 0 : u.inputCached / input;
+}
+// The process-wide meter. The loop records into it from every stream; the CLI
+// builds it once (with the configured prices) and /cost reads it. A module
+// singleton because metering is ambient — threading it through every call would
+// add noise for a cross-cutting concern. Tests construct their own CostMeter.
+let sessionMeter = null;
+export function initCostMeter(pricing) {
+    sessionMeter = new CostMeter(pricing);
+    return sessionMeter;
+}
+export function recordUsage(usage) {
+    sessionMeter?.record(usage); // no-op until the CLI initializes it (tests stay silent)
+}
+// Accumulates usage across a session and formats /cost.
+export class CostMeter {
+    pricing;
+    total = { inputUncached: 0, inputCached: 0, output: 0 };
+    calls = 0; // how many model calls were metered
+    constructor(pricing) {
+        this.pricing = pricing;
+    }
+    // Fold one response's usage into the running total.
+    record(usage) {
+        const u = normalizeUsage(usage);
+        if (u.inputUncached + u.inputCached + u.output === 0)
+            return; // a chunk with no usage — ignore
+        this.total.inputUncached += u.inputUncached;
+        this.total.inputCached += u.inputCached;
+        this.total.output += u.output;
+        this.calls++;
+    }
+    // Numbers for the status line: estimated spend so far and total tokens.
+    cost() {
+        return costOf(this.total, this.pricing);
+    }
+    inputTokens() {
+        return this.total.inputUncached + this.total.inputCached;
+    }
+    outputTokens() {
+        return this.total.output;
+    }
+    // The /cost report. Estimated, local-only.
+    report() {
+        const t = this.total;
+        const input = t.inputUncached + t.inputCached;
+        return [
+            `tokens this session (${this.calls} model calls):`,
+            `  input:  ${input} (${t.inputCached} cached, ${(cacheHitRate(t) * 100).toFixed(0)}% hit rate)`,
+            `  output: ${t.output}`,
+            `  estimated cost: $${costOf(t, this.pricing).toFixed(4)} (rough — prices set in settings.pricing)`,
+        ].join("\n");
+    }
+}

package/dist/diff.js

@@ -0,0 +1,135 @@
+import fs from "node:fs"; // read the target file to diff against
+import path from "node:path"; // resolve the file path
+import chalk from "chalk"; // color the +/- lines (auto-disabled when output isn't a TTY)
+// Longest-common-subsequence over lines → an ordered list of ops. Classic DP:
+// lcs[i][j] = length of the LCS of a[i:] and b[j:]. Walking it forwards turns the
+// table into the smallest set of removals + additions that turns a into b.
+export function diffLines(oldText, newText) {
+    const a = oldText.length ? oldText.split("\n") : []; // empty string = no lines (not [""])
+    const b = newText.length ? newText.split("\n") : [];
+    const n = a.length;
+    const m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0)); // (n+1)×(m+1), last row/col are zeros
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]); // match extends the subsequence; else take the better side
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j])
+            ops.push({ kind: " ", line: a[i++] }), j++; // common line — keep it as context
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            ops.push({ kind: "-", line: a[i++] }); // dropping a[i] keeps more of the LCS → it was removed
+        else
+            ops.push({ kind: "+", line: b[j++] }); // otherwise b[j] is an addition
+    }
+    while (i < n)
+        ops.push({ kind: "-", line: a[i++] }); // leftover old lines were all removed
+    while (j < m)
+        ops.push({ kind: "+", line: b[j++] }); // leftover new lines were all added
+    return ops;
+}
+const CONTEXT = 3; // unchanged lines to keep around each change, for readability
+const MAX_LINES = 60; // hard cap on rendered lines — a huge diff must not flood the prompt
+// Paint one line by its kind. chalk no-ops when colors are off, so the plain
+// text is always present (and assertable in tests).
+function paint(kind, text) {
+    if (kind === "+")
+        return chalk.green(text);
+    if (kind === "-")
+        return chalk.red(text);
+    return chalk.dim(text);
+}
+// Render ops as a compact unified diff: a "+A -B" summary header, the changed
+// lines with a few lines of context, and long runs of untouched lines collapsed
+// to a "⋮ (N unchanged lines)" marker so the reader sees the change, not the file.
+export function renderDiff(oldText, newText, color = true) {
+    const ops = diffLines(oldText, newText);
+    const added = ops.filter((o) => o.kind === "+").length;
+    const removed = ops.filter((o) => o.kind === "-").length;
+    // Keep any unchanged line within CONTEXT of a change; drop the rest.
+    const keep = new Array(ops.length).fill(false);
+    ops.forEach((op, idx) => {
+        if (op.kind === " ")
+            return;
+        for (let k = Math.max(0, idx - CONTEXT); k <= Math.min(ops.length - 1, idx + CONTEXT); k++)
+            keep[k] = true;
+    });
+    const out = [];
+    let i = 0;
+    while (i < ops.length) {
+        if (keep[i]) {
+            out.push(color ? paint(ops[i].kind, `${ops[i].kind} ${ops[i].line}`) : `${ops[i].kind} ${ops[i].line}`);
+            i++;
+        }
+        else {
+            let skipped = 0;
+            while (i < ops.length && !keep[i])
+                skipped++, i++; // collapse the whole untouched run at once
+            const note = `   ⋮ (${skipped} unchanged line${skipped === 1 ? "" : "s"})`;
+            out.push(color ? chalk.dim(note) : note);
+        }
+    }
+    const body = out.length > MAX_LINES ? [...out.slice(0, MAX_LINES), `   … (${out.length - MAX_LINES} more diff lines)`] : out;
+    const header = `  +${added} -${removed}`;
+    return [color ? chalk.dim(header) : header, ...body].join("\n");
+}
+const MAX_PREVIEW_BYTES = 200_000; // don't read+diff an enormous file just to preview it
+// Read a file for diffing, or null if it shouldn't be diffed (missing, too big,
+// or binary). A preview must never break a tool call, so every failure is null.
+function safeRead(p) {
+    try {
+        if (fs.statSync(p).size > MAX_PREVIEW_BYTES)
+            return null; // too big to preview cheaply
+        const text = fs.readFileSync(p, "utf8");
+        return text.includes("\0") ? null : text; // a NUL byte means binary — don't diff it
+    }
+    catch {
+        return null; // unreadable / missing
+    }
+}
+// Build the diff preview shown before a write/edit runs. Returns null when there
+// is nothing useful to show (not a write tool, unparseable args, binary file).
+// NEVER throws.
+export function previewChange(toolName, argsJson) {
+    let args;
+    try {
+        args = JSON.parse(argsJson);
+    }
+    catch {
+        return null; // dispatch will report the JSON error; nothing to preview
+    }
+    try {
+        if (toolName === "write_file") {
+            const p = path.resolve(args.path ?? "");
+            const exists = fs.existsSync(p);
+            const oldText = exists ? safeRead(p) : ""; // new file → empty "before"
+            if (oldText === null)
+                return null; // existing but binary/oversized
+            return `  ${exists ? "overwrite" : "create"} ${args.path}\n${renderDiff(oldText, String(args.content ?? ""))}`;
+        }
+        if (toolName === "edit_file") {
+            const p = path.resolve(args.path ?? "");
+            if (!fs.existsSync(p))
+                return null; // edit of a missing file → the tool will error
+            const oldText = safeRead(p);
+            if (oldText === null)
+                return null;
+            const occurrences = args.old_string ? oldText.split(args.old_string).length - 1 : 0;
+            // The tool only applies a unique match. If it's unique, diff the real
+            // before/after; otherwise just show the intended swap (the tool will
+            // reject a 0/ambiguous match anyway, but the human still sees the intent).
+            const newText = occurrences === 1 ? oldText.split(args.old_string).join(args.new_string ?? "") : null;
+            return newText !== null
+                ? `  edit ${args.path}\n${renderDiff(oldText, newText)}`
+                : `  edit ${args.path}\n${renderDiff(String(args.old_string ?? ""), String(args.new_string ?? ""))}`;
+        }
+    }
+    catch {
+        return null; // anything unexpected → no preview, never a crash
+    }
+    return null; // not a file-changing tool
+}