agent-from-zero 0.5.0 → 0.28.0

package/dist/ui.js

@@ -0,0 +1,138 @@
+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     Esc  interrupt     Ctrl+C  quit", 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"),
+    bgNote: (n) => chalk.magenta("  ⎿ ") + chalk.magenta(`${n} background task${n === 1 ? "" : "s"} finished — notified the agent`), // Day 37
+    teammateStart: (name, role) => chalk.magenta("  ⎿ teammate ") + chalk.bold(name) + chalk.magenta(` spawned`) + chalk.dim(` — ${role}`), // Day 38
+    teammateDone: (name, ok) => (ok ? chalk.magenta("  ⎿ teammate ") + chalk.bold(name) + chalk.magenta(" finished") : chalk.yellow("  ⎿ teammate ") + chalk.bold(name) + chalk.yellow(" ended (not done)")),
+    inbox: (n) => chalk.magenta("  ⎿ ") + chalk.magenta(`${n} team message${n === 1 ? "" : "s"} received`),
+    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,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.5.0",
+  "version": "0.28.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": {
@@ -16,7 +16,7 @@
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
     "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"
+    "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 && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/board.test.ts"
   },
   "engines": {
     "node": ">=20.6"
@@ -24,8 +24,12 @@
   "license": "MIT",
   "dependencies": {
     "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
     "openai": "^6.42.0",
-    "ora": "^9.4.0"
+    "ora": "^9.4.0",
+    "wrap-ansi": "^10.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",