agent-from-zero 0.1.0 → 0.27.0

package/dist/tools.js

@@ -1,6 +1,10 @@
 import fs from "node:fs"; // filesystem reads and writes
+import os from "node:os"; // temp dir for spilled tool output
 import path from "node:path"; // path resolution and joining
-import { execSync } from "node:child_process"; // runs a shell command and waits for it
+import { spawn } from "node:child_process"; // async process execution (does NOT block the event loop)
+import { validateArgs } from "./validate.js"; // schema validation for tool arguments
+import { setPlanMode } from "./permissions.js"; // plan mode (Day 20): exit_plan_mode flips it off on approval
+import { recordMutation } from "./undo.js"; // capture the before-state so /undo (Day 22) can restore it
 // ============ Session state ============
 // The foundation of "read before edit": which files has this session actually read?
 // Files that were never read must not be edited — otherwise the model edits from
@@ -15,6 +19,9 @@ const TOOL_RESULT_LIMIT = 4000; // cap (chars) for a normal tool result entering
 const READ_LIMIT = 16000; // read_file gets a larger cap of its own
 const SEARCH_MAX_MATCHES = 50; // max matches returned by search
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build"]); // directories search never enters
+const BASH_TIMEOUT_MS = 30_000; // a single command may run this long before we kill it
+const BASH_OUTPUT_LIMIT = 8_000; // chars of command output kept inline; beyond this we spill to a file
+const SPILL_NOTE_SLACK = 400; // room for the "[...saved to FILE]" note so dispatch's cap never eats it
 // Errors are not exceptions — they are text that tells the model what to do next.
 const fail = (msg) => `[error] ${msg}`;
 // Small helper to build a tool definition without repeating boilerplate.
@@ -63,6 +70,7 @@ On error: follow the error message — read the file first, then retry.`, {
             return fail(`${p} already exists but you have not read it. Use read_file to check its current content before overwriting.`); // no blind overwrites
         }
         fs.mkdirSync(path.dirname(p), { recursive: true }); // create parent directories as needed
+        recordMutation(p); // snapshot the previous state (or "didn't exist") for /undo, before we overwrite
         fs.writeFileSync(p, args.content, "utf8"); // write the new content
         readFiles.set(p, ++touchCounter); // you wrote it, so you know its content — counts as read
         return `Wrote ${p} (${args.content.length} chars)`; // confirm with the size as a sanity check
@@ -98,6 +106,7 @@ ALWAYS use this tool to edit files. NEVER use sed/awk or shell redirection via r
         }
         // Note: content.replace(old, newStr) would expand $& $' etc. in newStr as special
         // replacement patterns — pass a function so the replacement is taken literally.
+        recordMutation(p); // snapshot the pre-edit content for /undo, before we change it
         fs.writeFileSync(p, content.replace(args.old_string, () => args.new_string), "utf8"); // apply the single replacement
         return `Edited ${p}: 1 replacement made.`; // confirm exactly what happened
     },
@@ -165,39 +174,118 @@ ALWAYS use this tool to search. NEVER run grep/rg/find via run_bash.`, {
     },
 };
 // ============ run_bash ============
+// Spill oversized output to a file and hand the model a preview + the path, so
+// it can read_file deeper if it wants. Returning megabytes inline would blow up
+// the context; truncating silently would hide the part that matters.
+function spillIfHuge(out, what) {
+    if (out.length <= BASH_OUTPUT_LIMIT)
+        return out; // fits inline — return as-is
+    const file = path.join(os.tmpdir(), `mini-agent-output-${Date.now()}.txt`); // a stable place to find it
+    fs.writeFileSync(file, out, "utf8"); // the full output lives on disk
+    const head = out.slice(0, BASH_OUTPUT_LIMIT); // a generous preview
+    return `${head}\n\n[...${what} truncated: ${out.length} chars total. Full output saved to ${file} — use read_file to inspect more.]`;
+}
 const runBash = {
     definition: def("run_bash", `Run a bash command on the user's machine (30s timeout) and return its output.
 Boundaries: only for things that truly need execution — installing dependencies, running tests/scripts, git operations.
 To read files use read_file (not cat), to search use search (not grep/find), to edit files use edit_file (not sed/redirection).
 Dangerous commands require user approval; some are denied outright. A [permission] result is a hard boundary — never try to work around it.
 On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, { command: { type: "string", description: "The bash command to run" } }, ["command"]),
-    run: (args) => {
-        try {
-            // stderr is piped (not inherited): it belongs in the tool result for the
-            // model to read, not splattered onto the user's terminal.
-            const out = execSync(args.command, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
-            return out || "(command succeeded, no output)"; // never return an empty string
-        }
-        catch (err) {
-            const e = err; // execSync attaches the captured stderr on failure
-            return fail(`Command failed: ${e.message}${e.stderr ? `\nstderr: ${e.stderr.slice(0, 1000)}` : ""}`); // failure becomes guidance, not a crash
-        }
+    // Async + spawn: the event loop stays responsive while the command runs, so
+    // the spinner keeps spinning and Ctrl+C is heard. execSync would freeze
+    // everything — the whole process, the UI, the signal handler — until it
+    // returned. The AbortSignal lets the loop kill the child on interruption
+    // instead of waiting out the 30s timeout.
+    run: (args, signal) => new Promise((resolve) => {
+        const child = spawn(args.command, { shell: true, stdio: ["ignore", "pipe", "pipe"] }); // shell:true → bash semantics
+        let stdout = ""; // captured stdout
+        let stderr = ""; // captured stderr (for the model, not the user's terminal)
+        let settled = false; // resolve exactly once
+        const done = (text) => {
+            if (settled)
+                return; // guard against timeout/exit/abort racing
+            settled = true;
+            clearTimeout(timer); // stop the watchdog
+            signal?.removeEventListener("abort", onAbort); // unhook
+            resolve(text); // hand the result back
+        };
+        // Hard timeout: SIGKILL the whole process group, never hang the agent.
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            done(fail(`Command timed out after ${BASH_TIMEOUT_MS / 1000}s and was killed.${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
+        }, BASH_TIMEOUT_MS);
+        // Ctrl+C while a command runs: kill the child immediately.
+        const onAbort = () => {
+            child.kill("SIGKILL");
+            done(fail("Command was interrupted by the user."));
+        };
+        signal?.addEventListener("abort", onAbort);
+        child.stdout.on("data", (d) => (stdout += d)); // accumulate
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (err) => done(fail(`Could not start command: ${err.message}`))); // e.g. command not found at the spawn level
+        child.on("close", (code) => {
+            if (code === 0) {
+                done(spillIfHuge(stdout, "output") || "(command succeeded, no output)"); // success
+            }
+            else {
+                // Non-zero exit: combine streams so the model sees the actual error.
+                const combined = [stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`].filter(Boolean).join("\n");
+                done(fail(`Command exited with code ${code}.\n${spillIfHuge(combined, "error output")}`));
+            }
+        });
+    }),
+};
+// ============ exit_plan_mode ============
+// Plan mode (Day 20) makes the agent research-only: the permission gate blocks
+// every mutating tool until the model presents a plan the user approves. The
+// model calls this when its plan is ready; the gate turns it into an "ask", so
+// the user sees the plan first. run() executes ONLY after the user says yes —
+// so reaching this code IS the approval, and the one thing it does is leave plan
+// mode. Outside plan mode the gate makes it a harmless no-op allow.
+const exitPlanMode = {
+    definition: def("exit_plan_mode", `Leave plan mode and start implementing. Call this ONLY when you are in plan mode and have finished investigating with read-only tools.
+Pass your plan as markdown in "plan"; the user is shown it and asked to approve. Do NOT call it to ask a question, and not before you have a concrete, ordered plan.
+On approval, plan mode turns off and writing/executing tools become available. If declined, you stay in plan mode — refine the plan and try again.`, { plan: { type: "string", description: "The implementation plan, as concise ordered markdown steps" } }, ["plan"]),
+    run: () => {
+        setPlanMode(false); // run() only happens after the user approved — leave plan mode so implementation can begin
+        return "Plan approved by the user. Plan mode is OFF — implement the plan now; writing and executing tools are available again.";
     },
 };
 // ============ Registry & dispatch ============
-// One place that knows every tool. Adding a tool = adding one entry here.
+// The built-in tools. External tools (MCP servers, Day 15) are registered into
+// the same record at startup, so they flow through the same dispatch and the
+// same permission gate — there is exactly one execution path, no matter where a
+// tool came from.
 export const tools = {
     read_file: readFile,
     write_file: writeFile,
     edit_file: editFile,
     search,
     run_bash: runBash,
+    exit_plan_mode: exitPlanMode,
 };
-// The list of manuals sent to the model on every API call.
-export const toolDefinitions = Object.values(tools).map((t) => t.definition);
+// Register an external tool (e.g. one discovered from an MCP server). Kept in
+// the same `tools` record so dispatch, the permission gate, and the tool-list
+// sent to the model all treat it identically to a built-in.
+export function registerExternalTool(tool) {
+    tools[tool.definition.function.name] = tool;
+}
+// The manuals sent to the model. A function (not a const) since Day 15: MCP
+// tools register after module load, so the list must be computed when asked.
+export function toolDefinitions() {
+    return Object.values(tools).map((t) => t.definition);
+}
+// Read-only tools never touch the filesystem in a conflicting way, so the loop
+// is free to run a batch of them concurrently. Anything that writes or executes
+// (including any external/MCP tool, which we cannot reason about) runs alone, in
+// order. (See loop.ts for the batching.)
+const READ_ONLY_TOOLS = new Set(["read_file", "search"]);
+export const isReadOnlyTool = (name) => READ_ONLY_TOOLS.has(name);
 // Single entry point: every failure becomes text fed back to the model.
-// It never throws — the main loop must never die because of a tool.
-export function dispatch(name, argsJson) {
+// It never throws — the main loop must never die because of a tool. Async since
+// Day 13 so run_bash can spawn without blocking; the signal lets Ctrl+C kill a
+// running command.
+export async function dispatch(name, argsJson, signal) {
     const tool = tools[name]; // look the tool up by name
     if (!tool)
         return fail(`Unknown tool: ${name}. Available tools: ${Object.keys(tools).join(", ")}`); // model hallucinated a tool → list the real ones
@@ -208,8 +296,22 @@ export function dispatch(name, argsJson) {
     catch {
         return fail(`Arguments are not valid JSON: ${argsJson.slice(0, 200)}`); // malformed JSON → show what we got
     }
+    // Validate against the tool's declared schema BEFORE running it. The model's
+    // arguments are probabilistic — a missing required field or a wrong type gets
+    // a precise repair message here instead of a cryptic crash inside the tool
+    // (or, for MCP tools, a wasted round-trip to the server).
+    const problems = validateArgs(tool.definition.function.parameters, args);
+    if (problems.length) {
+        return fail(`Invalid arguments for ${name}: ${problems.join("; ")}. Fix and call again.`);
+    }
+    // Each tool gets a result cap sized to its job. run_bash already manages its
+    // own output (preview + spill-to-disk via spillIfHuge); its cap must leave
+    // room for the spill note, or dispatch would chop off the very pointer the
+    // model needs to read the rest.
+    const cap = name === "read_file" ? READ_LIMIT + 100 : name === "run_bash" ? BASH_OUTPUT_LIMIT + SPILL_NOTE_SLACK : TOOL_RESULT_LIMIT;
     try {
-        return tool.run(args).slice(0, name === "read_file" ? READ_LIMIT + 100 : TOOL_RESULT_LIMIT); // run it, cap the result size
+        const result = await tool.run(args, signal); // await covers both sync and async tools
+        return result.slice(0, cap); // cap the result size
     }
     catch (err) {
         return fail(`Tool crashed: ${err.message}`); // even a crashing tool becomes a readable result

package/dist/tui.js

@@ -0,0 +1,67 @@
+// Terminal UI helpers that need state or the filesystem: the git branch for the
+// status line, and collapsible tool output. The pure formatting (status line,
+// spinner) lives in ui.ts; this is the side-effecting half.
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+// ---- git branch for the status line -----------------------------------------
+// Walk up from the cwd to the nearest .git and read HEAD. A branch name, a short
+// detached SHA, or null if this isn't a repo. Never throws.
+export function gitBranch() {
+    let dir = process.cwd();
+    for (let i = 0; i < 40; i++) {
+        try {
+            const gitPath = path.join(dir, ".git");
+            const stat = fs.statSync(gitPath);
+            let headFile = path.join(gitPath, "HEAD");
+            if (stat.isFile()) {
+                // A worktree: .git is a file "gitdir: <path>" pointing elsewhere.
+                const gitdir = fs.readFileSync(gitPath, "utf8").replace(/^gitdir:\s*/, "").trim();
+                headFile = path.join(path.resolve(dir, gitdir), "HEAD");
+            }
+            const head = fs.readFileSync(headFile, "utf8").trim();
+            const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+            return m ? m[1] : head.slice(0, 7); // branch name, or a short detached SHA
+        }
+        catch {
+            /* not a repo here — keep walking up */
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached the filesystem root
+        dir = parent;
+    }
+    return null;
+}
+const collapsed = [];
+const MAX_COLLAPSED = 50; // bound the memory — old blocks fall off
+// Print the one-line summary now; stash the full text for Tab to reveal later.
+export function printToolSummary(summary, full) {
+    process.stdout.write(summary + "\n");
+    collapsed.push({ full, expanded: false });
+    if (collapsed.length > MAX_COLLAPSED)
+        collapsed.shift();
+}
+// Tab handler: reveal (or re-hide) the full text of the most recent tool block.
+// Returns false if there's nothing to toggle.
+export function toggleLastCollapsed() {
+    const block = collapsed[collapsed.length - 1];
+    if (!block)
+        return false;
+    block.expanded = !block.expanded;
+    if (block.expanded) {
+        process.stdout.write(chalk.dim(block.full.replace(/^/gm, "  ⎿ ")) + "\n");
+        process.stdout.write(chalk.dim("  (Tab to collapse)\n"));
+    }
+    else {
+        process.stdout.write(chalk.dim("  (collapsed)\n"));
+    }
+    return true;
+}
+// ---- cleanup -----------------------------------------------------------------
+// Called on exit. Nothing fancy to restore now (we no longer hijack the bottom
+// of the screen), but keep the hook so callers don't have to change if that
+// changes again.
+export function cleanup() {
+    process.stdout.write("\n");
+}

package/dist/ui.js

@@ -0,0 +1,134 @@
+import chalk from "chalk"; // the one place color lives
+// The app's visual theme, in one place. Before this, emoji and colors were
+// sprinkled across agent.ts and loop.ts — no coherent look, and impossible to
+// restyle without hunting. This module owns "what the tool looks like": the
+// welcome box, the prompt, the activity markers, the spinner. Still no TUI
+// framework — we print line by line — just with one consistent vocabulary.
+//
+// Glyphs over emoji: ⏺ (an action or answer), ⎿ (a nested detail), ❯ (the
+// prompt). They're width-1 in terminals (emoji like 🔧 are width-2 and break
+// alignment), and they read as "a real tool" rather than "a toy".
+// Draw a rounded box around plain-text lines. Width is measured on the PLAIN
+// text, so callers pass plain strings; an optional per-line style wraps the
+// already-padded cell (ANSI sits outside the padding, so alignment survives).
+// Keep box content ASCII-ish — String.length miscounts CJK/emoji width.
+function box(lines) {
+    const width = Math.max(...lines.map((l) => l.text.length));
+    const top = chalk.dim(`╭${"─".repeat(width + 2)}╮`);
+    const bottom = chalk.dim(`╰${"─".repeat(width + 2)}╯`);
+    const body = lines.map((l) => {
+        const cell = l.text.padEnd(width); // pad the plain text to a uniform width
+        return chalk.dim("│ ") + (l.style ? l.style(cell) : cell) + chalk.dim(" │"); // style wraps the padded cell
+    });
+    return [top, ...body, bottom].join("\n");
+}
+// The welcome banner, shown once at startup.
+export function banner(version, model, host) {
+    return box([
+        { text: `mini-agent  v${version}`, style: chalk.bold.cyan },
+        { text: `${model}  ·  ${host}`, style: chalk.dim },
+        { text: "" },
+        { text: "/help  commands     @file  attach a file     Ctrl+C  interrupt", style: chalk.dim },
+    ]);
+}
+// The input prompt. A styled chevron, not a bare ">". Plan mode (Day 20) gets a
+// distinct marker so you always know writes are blocked.
+export function promptString(planMode) {
+    return planMode ? chalk.yellow.bold("\n⏸ plan ❯ ") : chalk.cyan.bold("\n❯ ");
+}
+// The activity log vocabulary. ⏺ marks a thing happening, ⎿ marks a detail
+// hanging off it. Indentation/nesting is the caller's job (it knows sub-agent
+// depth), so these are just the styled pieces.
+export const mark = {
+    tool: (name, args) => chalk.cyan("⏺ ") + chalk.bold(name) + (args ? chalk.dim(` ${args}`) : ""),
+    answer: chalk.green("⏺ "), // prefix for the model's streamed answer
+    denied: (reason) => chalk.red("  ⎿ ") + chalk.red(`denied — ${reason}`),
+    declined: chalk.yellow("  ⎿ declined"),
+    judge: chalk.dim("  ⎿ judge: clearly safe, auto-allowed"),
+    hookBlock: (event) => chalk.red(`  ⎿ blocked by ${event} hook`),
+    subAgentStart: (desc, tier) => chalk.blue("  ⎿ sub-agent") + (tier ? chalk.dim(` [${tier}]`) : "") + chalk.blue(`: ${desc}`),
+    subAgentDone: chalk.blue("  ⎿ sub-agent done"),
+    note: (s) => chalk.dim(s), // dim asides (resumed, attached, cleared…)
+    warn: (s) => chalk.yellow(s),
+};
+// Playful "thinking" words, cycled while waiting for the first token — the same
+// touch Claude Code uses so a wait feels alive, not frozen.
+const WORDS = ["Thinking", "Pondering", "Cogitating", "Reasoning", "Working", "Scheming", "Brewing", "Crunching", "Mulling", "Noodling"];
+// Pick a word by a seed (a call counter) rather than Math.random — deterministic,
+// testable, and still varies turn to turn.
+export function thinkingWord(seed) {
+    return WORDS[((seed % WORDS.length) + WORDS.length) % WORDS.length];
+}
+// Compact a token count: 1234 → "1.2k", 980 → "980".
+export function formatTokens(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+}
+// Human elapsed time: 7s / 1m32s / 1h05m.
+export function formatElapsed(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m${String(s % 60).padStart(2, "0")}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h${String(m % 60).padStart(2, "0")}m`;
+}
+// The live spinner text: the model (so you can SEE which one is answering — proof
+// a /model switch took effect) + a thinking word + elapsed + tokens streamed so
+// far + how to bail. Mirrors Claude Code's "Mulling… (1m32s · ↓ 4.0k tokens)".
+export function spinnerText(word, elapsedSec, subAgent, model, tokens) {
+    const head = subAgent ? "sub-agent" : word;
+    const tag = model && !subAgent ? chalk.dim(`${model} · `) : ""; // show the model on top-level calls
+    const bits = [`${elapsedSec}s`];
+    if (tokens && tokens > 0)
+        bits.push(`↓ ${formatTokens(tokens)} tokens`);
+    bits.push("Ctrl+C to interrupt");
+    return `${tag}${head}… ${chalk.dim(`(${bits.join(" · ")})`)}`;
+}
+// The persistent status line — model, project, branch, context use, spend, time.
+// Pure (dir + branch passed in) so it's testable without a filesystem or git.
+export function statusLine(model, dir, branch, ctxPct, costUsd, elapsedMs) {
+    const parts = [
+        chalk.cyan(`[${model}]`),
+        chalk.dim(`📁 ${dir}`),
+        branch ? chalk.green(`🌿 ${branch}`) : "",
+        chalk.dim(`ctx ${ctxPct}%`),
+        chalk.yellow(`$${costUsd.toFixed(costUsd < 1 ? 4 : 2)}`),
+        chalk.dim(`⏱ ${formatElapsed(elapsedMs)}`),
+    ].filter(Boolean);
+    return parts.join(chalk.dim("  ·  "));
+}
+// ---- the input area ---------------------------------------------------------
+// Like Claude Code: two horizontal rules (top + bottom) with the user's input
+// between them. Long input is truncated to keep the box compact.
+function frameWidth() {
+    return Math.max(8, Math.min(process.stdout.columns || 80, 100) - 1); // fit the terminal, but cap the rule
+}
+export function inputRule() {
+    return chalk.dim("─".repeat(frameWidth())); // a plain separator line
+}
+// The prompt under the rule. Plan mode (Day 20) is marked so you know writes are blocked.
+export function framedPrompt(planMode) {
+    return planMode ? chalk.yellow.bold("⏸ plan ❯ ") : chalk.cyan.bold("❯ ");
+}
+// ---- the selection menu -----------------------------------------------------
+// Render a numbered list of options with one highlighted. The interactive part
+// (raw-mode arrow keys) lives in menu.ts; this is just the pure drawing, so it's
+// testable. Selecting beats typing: an approval is one keystroke, not "type y/N".
+// Numbered so the user can also see "option 2" at a glance, like Claude Code.
+export function renderMenu(options, selected) {
+    return options
+        .map((o, i) => {
+        const label = `${i + 1}. ${o}`;
+        return i === selected ? chalk.cyan.bold(`❯ ${label}`) : chalk.dim(`  ${label}`);
+    })
+        .join("\n");
+}
+// The hint line under a menu — how to drive it.
+export const MENU_HINT = chalk.dim("↑↓ to move · Enter to select · Esc to cancel");
+// Label a model list for the picker, marking the one in use. Pure, so the "which
+// is current" logic is testable without hitting the network for the list.
+export function formatModelChoices(models, current) {
+    return models.map((m) => (m === current ? `${m}  (current)` : m));
+}

package/dist/undo.js

@@ -0,0 +1,88 @@
+import fs from "node:fs"; // read the "before" state and restore it
+import path from "node:path"; // only for display shortening
+const MAX_UNDO = 50; // remember at most this many writes — older ones drop off
+const stack = []; // most recent change on top
+// The session-origin baseline: for each file touched this session, what it
+// looked like the FIRST time we changed it (null = it didn't exist yet). The
+// undo stack is bounded and popped, so it can't answer "what changed since we
+// started" — this map can. Set once per path, never overwritten, so it always
+// holds the true starting point even after many edits to the same file.
+const origin = new Map();
+// Called BY the write/edit tools, just before they touch the disk. Captures the
+// current on-disk state so it can be restored later. Never throws — recording is
+// best-effort and must not break the write it is shadowing.
+export function recordMutation(absPath) {
+    let before = null;
+    try {
+        if (fs.existsSync(absPath))
+            before = fs.readFileSync(absPath, "utf8"); // existing file → keep its content
+    }
+    catch {
+        before = null; // unreadable → treat as "nothing to restore"
+    }
+    if (!origin.has(absPath))
+        origin.set(absPath, before); // first touch this session = the baseline /diff compares against
+    stack.push({ path: absPath, before });
+    if (stack.length > MAX_UNDO)
+        stack.shift(); // bound the history (drop the oldest)
+}
+// How many undos are available — used by the REPL banner / message.
+export function undoDepth() {
+    return stack.length;
+}
+// Forget all recorded mutations (e.g. on /clear — a fresh conversation should
+// not be able to undo writes from the previous one, nor report them in /diff).
+export function clearUndo() {
+    stack.length = 0;
+    origin.clear();
+}
+// Every file whose content differs from its session-origin baseline. Files that
+// were touched but ended up back at their starting content are NOT listed —
+// /diff shows the net effect of the session, not its history.
+export function sessionChanges() {
+    const changes = [];
+    for (const [p, base] of origin) {
+        let current = null;
+        try {
+            if (fs.existsSync(p))
+                current = fs.readFileSync(p, "utf8"); // where the file stands now
+        }
+        catch {
+            current = null;
+        }
+        if ((base ?? null) === (current ?? null))
+            continue; // net-zero change → skip (e.g. edited then undone)
+        const status = base === null ? "created" : current === null ? "deleted" : "modified";
+        changes.push({ path: p, status, baseline: base ?? "", current: current ?? "" });
+    }
+    return changes;
+}
+// Undo the most recent recorded write. Returns null if there is nothing to undo.
+// Restores the previous content, or deletes a file that the write had created.
+export function undoLast() {
+    const m = stack.pop();
+    if (!m)
+        return null; // empty history
+    let after = null;
+    try {
+        if (fs.existsSync(m.path))
+            after = fs.readFileSync(m.path, "utf8"); // current state, for the diff
+    }
+    catch {
+        after = null;
+    }
+    const shortPath = path.relative(process.cwd(), m.path) || m.path; // nicer to read than an absolute path
+    try {
+        if (m.before === null) {
+            if (fs.existsSync(m.path))
+                fs.rmSync(m.path); // the write created this file → undo removes it
+            return { path: m.path, summary: `removed ${shortPath} (it had just been created)`, before: null, after };
+        }
+        fs.writeFileSync(m.path, m.before, "utf8"); // put the old content back
+        return { path: m.path, summary: `restored ${shortPath} to its previous content`, before: m.before, after };
+    }
+    catch (e) {
+        stack.push(m); // restore failed → keep the record so the user can retry
+        return { path: m.path, summary: `could not undo ${shortPath}: ${e.message}`, before: m.before, after };
+    }
+}

package/dist/validate.js

@@ -0,0 +1,60 @@
+// Structured tool-call validation. A model's tool arguments are probabilistic
+// output: it will sometimes drop a required field, send a number as a string,
+// or pass the wrong shape. The harness job is to constrain that output to the
+// declared schema and, on mismatch, hand back a PRECISE repair instruction so
+// the model fixes it on the next turn — instead of the tool crashing or doing
+// the wrong thing silently.
+//
+// This is a deliberately small subset of JSON Schema — exactly what our tool
+// definitions (and MCP servers') actually use: an object with typed properties
+// and a `required` list. Not a general validator; just enough to catch the
+// mistakes models really make, with messages they can act on.
+// JSON Schema "type" → does this runtime value match it? Unknown/absent type
+// matches anything (we don't over-constrain what the schema didn't constrain).
+function typeMatches(value, type) {
+    switch (type) {
+        case undefined:
+            return true; // no declared type → anything goes
+        case "string":
+            return typeof value === "string";
+        case "number":
+        case "integer":
+            return typeof value === "number" && (type === "number" || Number.isInteger(value));
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return true; // a type we don't model — don't reject on it
+    }
+}
+// Validate parsed arguments against a schema. Returns a list of human-readable
+// problems; an empty list means the arguments are valid. Pure — no I/O.
+export function validateArgs(schema, args) {
+    if (!schema)
+        return []; // no schema → nothing to check
+    const problems = [];
+    // The arguments must be a plain object — every tool takes a named-arg object.
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return ["arguments must be a JSON object of named parameters"];
+    }
+    const obj = args;
+    // Every required parameter must be present and not null/undefined.
+    for (const name of schema.required ?? []) {
+        if (obj[name] === undefined || obj[name] === null) {
+            problems.push(`missing required parameter "${name}"`);
+        }
+    }
+    // Every PRESENT parameter that has a declared type must match it. (We only
+    // type-check what was provided — absence is the `required` check's job.)
+    for (const [name, spec] of Object.entries(schema.properties ?? {})) {
+        if (obj[name] === undefined || obj[name] === null)
+            continue; // not provided — skip (required handled above)
+        if (!typeMatches(obj[name], spec.type)) {
+            problems.push(`parameter "${name}" should be ${spec.type}, got ${Array.isArray(obj[name]) ? "array" : typeof obj[name]}`);
+        }
+    }
+    return problems;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-from-zero",
-  "version": "0.1.0",
-  "description": "A Claude Code-style CLI agent built from scratch with the DeepSeek API — companion code for a 10-day tutorial",
+  "version": "0.27.0",
+  "description": "Build a Claude Code-style CLI agent from scratch, with AI as your pair programmer — companion code for a 10-day tutorial (DeepSeek by default, any OpenAI-compatible model)",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit",
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/ui.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/skills.test.ts"
   },
   "engines": {
     "node": ">=20.6"