agent-from-zero 0.27.0 → 0.28.0

package/dist/tools.js

@@ -5,6 +5,8 @@ import { spawn } from "node:child_process"; // async process execution (does NOT
 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
+import { parseTodos, setTodos, summarizeTodos } from "./todos.js"; // the agent's own checklist (Day 36)
+import { startBackground, readBackground } from "./background.js"; // long-running commands that outlive the turn (Day 37)
 // ============ 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
@@ -235,6 +237,45 @@ On error: failures return the error output — analyze it and try a different ap
         });
     }),
 };
+// ============ run_bash_background (Day 37) ============
+// run_bash blocks and dies at its 30s watchdog — useless for anything truly
+// slow. This is its asynchronous twin: it spawns the command and returns a task
+// id IMMEDIATELY, so the agent keeps reasoning while the work happens. The loop
+// injects a <task_notification> when the command finishes (background.ts). Use
+// it for installs, builds, full test runs, or servers that never exit — exactly
+// the keywords that signal a slow operation. The command goes through the SAME
+// permission gate as run_bash (see permissions.ts), so the danger rules are
+// identical; only the blocking behavior differs.
+const runBashBackground = {
+    definition: def("run_bash_background", `Run a slow bash command in the BACKGROUND and return immediately with a task id (e.g. bg_1) — do NOT wait for it.
+When to use: anything that would exceed run_bash's 30s limit or block you — installing dependencies (npm/pip install), builds (npm run build, cargo build, make), full test suites (pytest, npm test), deploys, or long-running servers (npm run dev) that never exit.
+What you get back: just the task id. The command keeps running. When it finishes you'll receive a <task_notification> with its status and output tail — react to that. For a server or a job still running, poll it with bash_output.
+Boundaries & permissions are identical to run_bash (dangerous commands are still gated or denied). For quick commands use run_bash instead — waiting on a one-off background job wastes a turn.`, { command: { type: "string", description: "The bash command to run in the background" } }, ["command"]),
+    // Fire-and-return: start the process, hand back the id. The output is captured
+    // by background.ts and delivered later as a notification — never inline here.
+    run: (args) => {
+        const id = startBackground(args.command);
+        return `Started background task ${id}: ${args.command}\nIt is running now; you will get a <task_notification> when it finishes. Keep working — use bash_output with task_id "${id}" to check on it (e.g. to confirm a server came up).`;
+    },
+};
+// ============ bash_output (Day 37) ============
+// Poll a background task: its status and any output produced since the last
+// poll. Essential for the case a notification can never cover — a server that
+// runs forever (npm run dev) never "finishes", so the only way to see "ready on
+// :3000" is to read its output. Reading advances a per-task cursor, so repeated
+// polls show only what's new, not the whole log every time.
+const bashOutput = {
+    definition: def("bash_output", `Check on a background task started with run_bash_background: returns its status and any NEW output since you last checked.
+When to use: to see if a long job is done, or to read a long-running server's output (e.g. confirm "listening on :3000"). A finished task also sends you a <task_notification> automatically — you don't need to poll just to learn it ended.
+Pass full=true to get the entire captured log instead of only the new lines. On an unknown task id you'll get the list of ids that exist.`, {
+        task_id: { type: "string", description: "The background task id, e.g. bg_1" },
+        full: { type: "boolean", description: "Return the entire captured output instead of only new output since the last check (default false)" },
+    }, ["task_id"]),
+    run: (args) => {
+        const full = args.full === true; // optional boolean
+        return spillIfHuge(readBackground(args.task_id, full), "background 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
@@ -251,6 +292,47 @@ On approval, plan mode turns off and writing/executing tools become available. I
         return "Plan approved by the user. Plan mode is OFF — implement the plan now; writing and executing tools are available again.";
     },
 };
+// ============ todo_write ============
+// The agent's planning tool (Day 36). The model sends the WHOLE list each time
+// (it replaces the previous one); we store it, show it, and hand back a one-line
+// tally. The array-of-objects schema is built by hand — the `def()` helper only
+// does flat string params. State + rendering + the nag live in todos.ts.
+const todoWrite = {
+    definition: {
+        type: "function",
+        function: {
+            name: "todo_write",
+            description: `Record and update a short plan for the CURRENT task as a checklist. This adds planning, NOT new abilities — it changes nothing on disk.
+When to use: a task with 3+ distinct steps, or whenever the user gives several requirements. Skip it for trivial one-step asks.
+How: pass the COMPLETE list every time (it replaces the previous one). Keep AT MOST ONE item in_progress. As you work, flip items to completed and move the next to in_progress — an out-of-date list is worse than none.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    todos: {
+                        type: "array",
+                        description: "The complete todo list, in order. Replaces the previous list.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                content: { type: "string", description: "The step, phrased as an action" },
+                                status: { type: "string", enum: ["pending", "in_progress", "completed"], description: "pending | in_progress | completed (only one in_progress)" },
+                            },
+                            required: ["content", "status"],
+                        },
+                    },
+                },
+                required: ["todos"],
+            },
+        },
+    },
+    run: (args) => {
+        const parsed = parseTodos(args.todos); // validate the model's list
+        if (parsed.error)
+            return fail(parsed.error); // precise repair message, not a crash
+        setTodos(parsed.todos); // store it (resets the nag clock); the loop renders it to the screen
+        return summarizeTodos(parsed.todos); // concise tally back to the model — the pretty list is for the human
+    },
+};
 // ============ Registry & dispatch ============
 // 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
@@ -262,7 +344,10 @@ export const tools = {
     edit_file: editFile,
     search,
     run_bash: runBash,
+    run_bash_background: runBashBackground,
+    bash_output: bashOutput,
     exit_plan_mode: exitPlanMode,
+    todo_write: todoWrite,
 };
 // 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
@@ -308,7 +393,7 @@ export async function dispatch(name, argsJson, signal) {
     // 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;
+    const cap = name === "read_file" ? READ_LIMIT + 100 : name === "run_bash" || name === "bash_output" ? BASH_OUTPUT_LIMIT + SPILL_NOTE_SLACK : TOOL_RESULT_LIMIT;
     try {
         const result = await tool.run(args, signal); // await covers both sync and async tools
         return result.slice(0, cap); // cap the result size

package/dist/ui.js

@@ -28,7 +28,7 @@ export function banner(version, model, host) {
         { 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 },
+        { 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
@@ -48,6 +48,10 @@ export const mark = {
     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),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.27.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 && 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"
+    "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",