agent-from-zero 0.5.0 → 0.27.0

package/dist/session.js

@@ -3,7 +3,9 @@ import path from "node:path"; // path joining
 // Sessions are project-local: .mini-agent/sessions/<id>.json under the cwd.
 // Project-local (not global) because a conversation is about a codebase —
 // resuming a refactor of project A from inside project B makes no sense.
-const SESSIONS_DIR = path.resolve(".mini-agent", "sessions");
+// Resolved lazily (a function, not a const) so it always reflects the current
+// working directory — and so tests can chdir into a scratch dir.
+const sessionsDir = () => path.resolve(".mini-agent", "sessions");
 const KEEP_SESSIONS = 20; // how many session files survive pruning
 // A fresh, filename-safe session id derived from the wall clock.
 export function newSessionId() {
@@ -14,8 +16,9 @@ export function newSessionId() {
 // only representation that is always correct. Crash mid-write leaves the
 // previous snapshot intact.
 export function saveSession(id, model, messages) {
-    fs.mkdirSync(SESSIONS_DIR, { recursive: true }); // first save creates the directory
-    const file = path.join(SESSIONS_DIR, `${id}.json`); // the real destination
+    const dir = sessionsDir();
+    fs.mkdirSync(dir, { recursive: true }); // first save creates the directory
+    const file = path.join(dir, `${id}.json`); // the real destination
     const existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt
     const data = {
         id,
@@ -29,33 +32,72 @@ export function saveSession(id, model, messages) {
     fs.renameSync(tmp, file); // atomic swap
     prune(); // keep the directory bounded
 }
+// Session files on disk, newest (most recently saved) first. Shared by every
+// reader below. Skips tmp files and strangers.
+function sessionFilesNewestFirst() {
+    const dir = sessionsDir();
+    if (!fs.existsSync(dir))
+        return []; // nothing ever saved here
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json")) // ignore tmp files and strangers
+        .map((f) => ({ f, mtime: fs.statSync(path.join(dir, f)).mtimeMs })) // newest by modification time
+        .sort((a, b) => b.mtime - a.mtime);
+}
 // Load the most recent session, or null if there is none (or it is unreadable —
 // a corrupt session file should not kill the CLI, just start fresh).
 export function latestSession() {
-    if (!fs.existsSync(SESSIONS_DIR))
-        return null; // nothing ever saved here
-    const files = fs
-        .readdirSync(SESSIONS_DIR)
-        .filter((f) => f.endsWith(".json")) // ignore tmp files and strangers
-        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs })) // newest by modification time
-        .sort((a, b) => b.mtime - a.mtime);
+    const files = sessionFilesNewestFirst();
     if (!files.length)
         return null; // empty directory
     try {
-        return JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, files[0].f), "utf8")); // the newest snapshot
+        return JSON.parse(fs.readFileSync(path.join(sessionsDir(), files[0].f), "utf8")); // the newest snapshot
     }
     catch {
         return null; // unreadable — treat as absent, never crash on resume
     }
 }
+// Load one session by id, or null if missing/corrupt.
+export function loadSession(id) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(sessionsDir(), `${id}.json`), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// A one-line, human-readable title for a session: the first thing the user
+// actually typed, with any @file attachment block stripped off and the text
+// flattened to a single trimmed line. This is what makes a session list
+// pickable instead of a wall of timestamps.
+export function sessionTitle(messages) {
+    const firstUser = messages.find((m) => m.role === "user");
+    let text = typeof firstUser?.content === "string" ? firstUser.content : "";
+    text = text.split("\n\n[Referenced files")[0]; // drop the @file attachment the REPL appended (Day 26)
+    const line = text.replace(/\s+/g, " ").trim(); // flatten to one line
+    return line || "(no prompt)";
+}
+// Recent sessions, newest first, summarized for a picker. Unreadable files are
+// skipped, never fatal.
+export function listSessions(limit = 10) {
+    const out = [];
+    for (const { f } of sessionFilesNewestFirst()) {
+        if (out.length >= limit)
+            break;
+        try {
+            const s = JSON.parse(fs.readFileSync(path.join(sessionsDir(), f), "utf8"));
+            out.push({ id: s.id, savedAt: s.savedAt, model: s.model, messageCount: s.messages.length, title: sessionTitle(s.messages) });
+        }
+        catch {
+            /* skip a corrupt file */
+        }
+    }
+    return out;
+}
 // Delete everything beyond the newest KEEP_SESSIONS files. A CLI that quietly
 // accumulates unbounded state in every project directory is not industrial.
 function prune() {
-    const files = fs
-        .readdirSync(SESSIONS_DIR)
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime); // newest first
-    for (const { f } of files.slice(KEEP_SESSIONS))
-        fs.rmSync(path.join(SESSIONS_DIR, f)); // drop the tail
+    const dir = sessionsDir();
+    for (const { f } of sessionFilesNewestFirst().slice(KEEP_SESSIONS))
+        fs.rmSync(path.join(dir, f)); // drop the tail beyond KEEP_SESSIONS
 }

package/dist/skills.js

@@ -0,0 +1,128 @@
+import fs from "node:fs"; // discover and read SKILL.md files
+import os from "node:os"; // the global skills dir
+import path from "node:path"; // path resolution
+// Project skills win over global ones with the same name.
+function skillDirs() {
+    return [path.resolve(".mini-agent", "skills"), path.join(os.homedir(), ".config", "mini-agent", "skills")];
+}
+// Parse one SKILL.md into a Skill. Pure — no filesystem — so the (fiddly)
+// frontmatter parsing is unit-testable. A tiny YAML subset: `key: value` lines.
+export function parseSkill(raw, fallbackName, filePath = "") {
+    const fm = {};
+    let body = raw.trim();
+    const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/); // frontmatter between --- fences
+    if (m) {
+        body = m[2].trim();
+        for (const line of m[1].split(/\r?\n/)) {
+            const i = line.indexOf(":");
+            if (i < 0)
+                continue;
+            const k = line.slice(0, i).trim();
+            const v = line.slice(i + 1).trim().replace(/^["']|["']$/g, ""); // strip surrounding quotes
+            if (k)
+                fm[k] = v;
+        }
+    }
+    return {
+        name: fm.name || fallbackName,
+        description: fm.description || "",
+        whenToUse: fm.when_to_use || fm.whenToUse || fm.description || "",
+        allowedTools: (fm["allowed-tools"] || fm.allowedTools || "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean),
+        disableModelInvocation: /^true$/i.test(fm.disableModelInvocation || fm["disable-model-invocation"] || ""),
+        body,
+        path: filePath,
+    };
+}
+// Discover skills under the skill dirs (project first, then global). A bad file
+// is skipped, never fatal. `dirs` is injectable for tests.
+export function loadSkills(dirs = skillDirs()) {
+    const out = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue; // dir doesn't exist — fine
+        }
+        for (const entry of entries) {
+            const file = path.join(dir, entry, "SKILL.md");
+            try {
+                const skill = parseSkill(fs.readFileSync(file, "utf8"), entry, file);
+                if (seen.has(skill.name))
+                    continue; // first wins → project overrides global
+                seen.add(skill.name);
+                out.push(skill);
+            }
+            catch {
+                /* not a skill folder — skip */
+            }
+        }
+    }
+    return out;
+}
+export function findSkill(skills, name) {
+    const n = name.trim().toLowerCase();
+    return skills.find((s) => s.name.toLowerCase() === n);
+}
+const MAX_DESC = 250; // cap each skill's listing line (handbook MAX_LISTING_DESC_CHARS)
+const LIST_BUDGET = 8000; // cap the whole listing (handbook DEFAULT_CHAR_BUDGET)
+// The one-line-per-skill listing the model sees (name + when-to-use), budget
+// capped. This is the "progressive disclosure" surface: enough to decide whether
+// to invoke, not the full body.
+export function skillListing(skills) {
+    const lines = [];
+    let used = 0;
+    for (const s of skills) {
+        const desc = (s.whenToUse || s.description).replace(/\s+/g, " ").slice(0, MAX_DESC);
+        const line = `- ${s.name}: ${desc}`;
+        if (used + line.length > LIST_BUDGET)
+            break; // out of budget — stop listing
+        used += line.length;
+        lines.push(line);
+    }
+    return lines.join("\n");
+}
+// What gets handed back when a skill is invoked: the body, plus a reminder of
+// its allowed tools (least-privilege is advisory here — the permission gate
+// still governs every actual call).
+export function skillInstructions(s) {
+    const tools = s.allowedTools.length ? `\n\n[This skill should use only these tools: ${s.allowedTools.join(", ")}. Other actions still go through the normal permission gate.]` : "";
+    return `# Skill: ${s.name}\n\nFollow these steps:\n\n${s.body}${tools}`;
+}
+// Build the `skill` tool from the model-invocable skills. The tool's description
+// IS the listing, so the model learns what skills exist and when to use them;
+// calling it with a name returns that skill's full instructions.
+export function buildSkillTool(skills) {
+    const invokable = skills.filter((s) => !s.disableModelInvocation);
+    const listing = skillListing(invokable) || "(none)";
+    return {
+        definition: {
+            type: "function",
+            function: {
+                name: "skill",
+                description: `Load and follow a reusable skill — a saved, named procedure. Call this when the user's request matches one of the skills below; it returns step-by-step instructions you then carry out yourself.
+Available skills:
+${listing}
+Pass the exact skill name. If nothing matches, do not call this — just answer normally.`,
+                parameters: {
+                    type: "object",
+                    properties: { name: { type: "string", description: "The exact skill name to load" } },
+                    required: ["name"],
+                },
+            },
+        },
+        run: (args) => {
+            const s = findSkill(skills, args.name ?? "");
+            if (!s)
+                return `[error] No skill named "${args.name}". Available: ${invokable.map((x) => x.name).join(", ") || "none"}.`;
+            if (s.disableModelInvocation)
+                return `[error] Skill "${s.name}" can only be invoked by the user, not by you.`;
+            return skillInstructions(s);
+        },
+    };
+}

package/dist/tools.js

@@ -2,6 +2,9 @@ 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 { 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
@@ -67,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
@@ -102,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
     },
@@ -230,20 +235,50 @@ On error: failures return the error output — analyze it and try a different ap
         });
     }),
 };
+// ============ 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
-// runs alone, in order. (See loop.ts for the batching.)
+// (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.
@@ -261,6 +296,14 @@ export async function dispatch(name, argsJson, signal) {
     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

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