agent-from-zero 0.32.0 → 0.32.1

package/dist/agent.js

@@ -4,7 +4,7 @@ import chalk from "chalk"; // terminal colors
 import readline from "node:readline/promises"; // promise-based terminal input
 import { createRequire } from "node:module"; // to read package.json for --version
 import { CONFIG, requireApiKey, saveGlobalSetting, PROJECT_SETTINGS_PATH, GLOBAL_SETTINGS_PATH } from "./config.js"; // provider-agnostic settings (.env loaded there)
-import { runLoop, TerminateReason, MAX_RETRIES } from "./loop.js"; // the state machine
+import { runLoop, TerminateReason, MAX_RETRIES, killAllSubAgents } from "./loop.js"; // the state machine
 import { buildSystemMessage } from "./prompt.js"; // the constitution + optional AGENT.md project memory
 import { forgetFilesExcept, registerExternalTool } from "./tools.js"; // file-state reset + tool registration
 import { compactHistory, estimateHistoryTokens, COMPACT_AT } from "./context.js"; // for the manual /compact command
@@ -155,6 +155,7 @@ async function main() {
     const disconnectMcp = await connectMcpServers();
     process.on("exit", disconnectMcp); // best-effort cleanup of server subprocesses
     process.on("exit", killAllBackground); // Day 37: SIGKILL any background job (dev server, slow install) so it never outlives the agent as an orphan
+    process.on("exit", killAllSubAgents); // mark any still-running sub-agents as killed so they don't leave pending promises
     // The optional LLM permission judge, built once if a settings file enabled it.
     const judge = CONFIG.judge.enabled ? new Judge(client, CONFIG.judge.model || CONFIG.model) : undefined;
     if (judge)

package/dist/ink/app.js

@@ -6,7 +6,7 @@ import { formatElapsed, renderMenu, MENU_HINT, formatModelChoices } from "../ui.
 import { renderMarkdown } from "../markdown.js"; // model speaks markdown → ANSI, same as the non-Ink REPL
 import { initFormState, reduceForm, renderForm, collectAnswers } from "../form.js"; // the ask_user form: pure state machine + renderer
 import { CONFIG, saveGlobalSetting } from "../config.js"; // session allowlist + /model save
-import { TerminateReason } from "../loop.js"; // how a turn can end
+import { TerminateReason, listSubAgents } from "../loop.js"; // how a turn can end
 import { compactHistory, COMPACT_AT } from "../context.js"; // /compact
 import { forgetFilesExcept } from "../tools.js"; // /clear resets the file read-state
 import { clearUndo } from "../undo.js";
@@ -27,6 +27,25 @@ import { runInfoCommand } from "./commands.js"; // the non-interactive slash com
 // Injected when plan mode turns on, so the model knows the rules it now lives in.
 const PLAN_MODE_NOTICE = `[plan mode ON] Investigate this request using only read-only tools — read_file, search, and safe read-only shell (ls, cat, git status). Do NOT write files, edit, or run mutating commands; the permission gate will block them. When you have a concrete, ordered plan, call the exit_plan_mode tool with that plan. The user reviews and approves it before you make any change.`;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; // the braille spinner ora uses, hand-rolled for Ink
+// Cap the live streaming preview to a terminal-aware tail. THIS IS LOAD-BEARING:
+// Ink redraws the whole dynamic region (everything below <Static>) on every
+// token, and when that region grows TALLER than the terminal, Ink can no longer
+// erase its previous frame — committed lines get reprinted (duplicate messages)
+// and the cursor math drifts (sudden blank gaps). So we never let the in-flight
+// answer render more than the rows we can spare; the FULL reply still commits to
+// <Static> (formatted as markdown) the moment it finishes.
+function liveTail(s) {
+    const rows = process.stdout.rows || 24;
+    const maxLines = Math.max(3, rows - 14); // reserve rows for the input box + status bar + agent bar + margins
+    const cols = process.stdout.columns || 80;
+    const maxChars = maxLines * cols; // rough bound so one very long line can't blow past either
+    let t = s.length > maxChars ? s.slice(-maxChars) : s;
+    const lines = t.split("\n");
+    const clipped = s.length > maxChars || lines.length > maxLines;
+    if (lines.length > maxLines)
+        t = lines.slice(-maxLines).join("\n");
+    return clipped ? "… " + t : t; // a leading ellipsis signals there's more above (it's all in the scrollback on commit)
+}
 function Spinner() {
     const [f, setF] = useState(0);
     useEffect(() => {
@@ -83,6 +102,8 @@ export function App({ session, runTurn }) {
     const [sessionId, setSessionId] = useState(session.initialSessionId); // changes on /clear, /resume
     const [planMode, setPlan] = useState(isPlanMode()); // mirrored into the prompt frame
     const [histIdx, setHistIdx] = useState(null); // ↑/↓ recall position (null = editing a fresh line)
+    const [subAgentFocus, setSubAgentFocus] = useState(null); // which sub-agent is highlighted (null = none)
+    const [subAgentDetail, setSubAgentDetail] = useState(null); // the id of the sub-agent whose output is shown in detail
     const [, setTick] = useState(0); // forces a re-render once a second so the clock / cost tick
     const { exit } = useApp();
     const pushItem = useRef((it) => setItems((xs) => [...xs, it])).current;
@@ -338,6 +359,12 @@ export function App({ session, runTurn }) {
             return note(getReasoning() ?? chalk.dim("(no thinking recorded for the last answer)"));
         if (key.ctrl && char === "t")
             return note(getToolCalls() ?? chalk.dim("(no tool calls recorded for the last answer)"));
+        // Esc while a sub-agent detail is open: close it, don't interrupt.
+        if (key.escape && subAgentDetail && !pending) {
+            setSubAgentDetail(null);
+            setSubAgentFocus(null);
+            return;
+        }
         // Esc while a turn runs (and no menu is up): interrupt it — like the first
         // Ctrl+C of the readline REPL, without the force-quit escalation.
         if (key.escape && busy && !pending) {
@@ -386,9 +413,53 @@ export function App({ session, runTurn }) {
             }
             return;
         }
+        // Tab / Shift+Tab: cycle through the sub-agent list below the input box.
+        // Enter on a highlighted sub-agent toggles its detail view.
+        const agents = listSubAgents();
+        if (agents.length > 0 && !key.return && key.tab) {
+            const back = key.shift; // Shift+Tab = go backwards
+            if (subAgentDetail) {
+                // Detail open: Tab moves to next + closes detail.
+                setSubAgentDetail(null);
+                setSubAgentFocus((prev) => {
+                    const n = agents.length;
+                    if (back) {
+                        const next = prev === null ? n - 1 : (prev - 1 + n) % n;
+                        return next;
+                    }
+                    const next = prev === null ? 0 : (prev + 1) % n;
+                    return next;
+                });
+            }
+            else {
+                setSubAgentDetail(null);
+                setSubAgentFocus((prev) => {
+                    const n = agents.length;
+                    if (back) {
+                        if (prev === null)
+                            return n - 1;
+                        const next = (prev - 1 + n) % n;
+                        return next === n - 1 ? null : next;
+                    }
+                    if (prev === null)
+                        return 0;
+                    const next = (prev + 1) % n;
+                    return next === 0 ? null : next;
+                });
+            }
+            return;
+        }
+        // Enter with a sub-agent highlighted: show its detail.
+        if (agents.length > 0 && subAgentFocus !== null && key.return) {
+            setSubAgentDetail(agents[subAgentFocus].id === subAgentDetail ? null : agents[subAgentFocus].id);
+            return;
+        }
         if (busy)
             return; // a turn in flight with no prompt — ignore typing for now (type-ahead is later)
         if (key.return) {
+            // Dismiss the sub-agent detail/focus on a normal submit.
+            setSubAgentDetail(null);
+            setSubAgentFocus(null);
             const text = input.trim();
             setInput("");
             setHistIdx(null);
@@ -431,5 +502,17 @@ export function App({ session, runTurn }) {
             setInput((s) => s + add);
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: items, children: (item, i) => _jsx(ItemView, { item: item }, i) }), live !== null && (_jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsx(Text, { color: "green", children: "\u23FA " }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { children: live === "" ? chalk.dim("…") : live }) })] })), status !== null && (_jsxs(Box, { marginTop: live === null ? 1 : 0, children: [_jsx(Spinner, {}), _jsxs(Text, { children: [" ", status] })] })), pending?.kind === "select" && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: pending.header }), _jsx(Text, { children: renderMenu(pending.options, menuSel) }), _jsx(Text, { children: MENU_HINT })] })), pending?.kind === "form" && formState && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: renderForm(pending.questions, formState) }) })), _jsxs(Box, { borderStyle: "round", borderColor: planMode ? "magenta" : "cyan", paddingX: 1, marginTop: 1, children: [_jsx(Text, { color: planMode ? "magenta" : "cyan", children: planMode ? "plan ❯ " : "❯ " }), _jsx(Text, { children: input }), _jsx(Text, { inverse: true, children: " " })] }), _jsx(StatusBar, { model: model, dir: dir, branch: branch, status: getStatus() })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: items, children: (item, i) => _jsx(ItemView, { item: item }, i) }), live !== null && (_jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsx(Text, { color: "green", children: "\u23FA " }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { children: live === "" ? chalk.dim("…") : liveTail(live) }) })] })), (status !== null || (busy && live === null)) && (_jsxs(Box, { marginTop: live === null ? 1 : 0, children: [_jsx(Spinner, {}), _jsxs(Text, { children: [" ", status ?? chalk.dim("working…")] })] })), pending?.kind === "select" && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: pending.header }), _jsx(Text, { children: renderMenu(pending.options, menuSel) }), _jsx(Text, { children: MENU_HINT })] })), pending?.kind === "form" && formState && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: renderForm(pending.questions, formState) }) })), _jsxs(Box, { borderStyle: "round", borderColor: planMode ? "magenta" : "cyan", paddingX: 1, marginTop: 1, children: [_jsx(Text, { color: planMode ? "magenta" : "cyan", children: planMode ? "plan ❯ " : "❯ " }), _jsx(Text, { children: input }), _jsx(Text, { inverse: true, children: " " })] }), (() => {
+                const agents = listSubAgents();
+                if (!agents.length)
+                    return null;
+                return (_jsxs(Box, { flexDirection: "column", marginTop: 0, children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "agents \u00B7 " }), agents.map((sa, i) => (_jsxs(React.Fragment, { children: [_jsx(Text, { color: i === subAgentFocus ? "cyan" : "blue", bold: i === subAgentFocus, children: sa.id }), _jsx(Text, { dimColor: true, children: sa.status === "running" ? " ●" : sa.status === "done" ? " ✓" : " ✗" }), i < agents.length - 1 && _jsx(Text, { dimColor: true, children: " \u2502 " })] }, sa.id))), _jsx(Text, { dimColor: true, children: " \u00B7 Tab" })] }), subAgentDetail && (() => {
+                            const detail = agents.find((sa) => sa.id === subAgentDetail);
+                            if (!detail)
+                                return null;
+                            const head = `${detail.id} · ${detail.status === "running" ? "running" : detail.status === "done" ? "done" : "failed"}`;
+                            const body = detail.result ?? "(still working…)";
+                            return (_jsxs(Box, { flexDirection: "column", marginTop: 0, borderStyle: "single", borderColor: "blue", paddingX: 1, children: [_jsx(Text, { color: "cyan", bold: true, children: head }), _jsx(Text, { dimColor: true, children: detail.description }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: body.length > 500 ? body.slice(0, 500) + "\n…" : body }) })] }));
+                        })()] }));
+            })(), _jsx(StatusBar, { model: model, dir: dir, branch: branch, status: getStatus() })] }));
 }

package/dist/ink/setup.js

@@ -15,6 +15,7 @@ import { registerExternalTool } from "../tools.js";
 import { rememberTool, readMemory } from "../memory.js";
 import { loadSkills, buildSkillTool } from "../skills.js";
 import { killAllBackground } from "../background.js";
+import { killAllSubAgents } from "../loop.js";
 import { banner } from "../ui.js";
 // The Ink REPL's session bootstrap — the same wiring agent.ts (the readline REPL)
 // does before the prompt loop, but front-end-agnostic: it touches none of
@@ -51,6 +52,7 @@ export async function buildInkSession(opts = {}) {
     const disconnectMcp = await connectMcpServers();
     process.on("exit", disconnectMcp);
     process.on("exit", killAllBackground); // SIGKILL any background job so it never outlives the agent
+    process.on("exit", killAllSubAgents); // mark any still-running sub-agents as killed
     const judge = CONFIG.judge.enabled ? new Judge(client, CONFIG.judge.model || CONFIG.model) : undefined;
     if (judge)
         notices.push(`(permission judge on — model ${CONFIG.judge.model || CONFIG.model})`);

package/dist/loop.js

@@ -55,6 +55,7 @@ const taskTool = {
         description: `Delegate one self-contained subtask to a sub-agent that works in a FRESH context.
 The sub-agent has the same tools (except task) but knows NOTHING about this conversation — put every detail it needs into the description.
 Use it for exploration that would flood your context: reading many files, broad searches, summarizing a directory.
+The sub-agent runs ASYNC — it returns a handle immediately and you are notified when it finishes. Do NOT wait idly: continue working or wait for its result.
 The sub-agent's report is INPUT MATERIAL, not verified truth — re-check key claims yourself before acting on them.
 On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a clearer description, or do the work yourself.`,
         parameters: {
@@ -277,37 +278,94 @@ function toolsFor(opts) {
     // watching the board (it lays out tasks; teammates pull from it).
     return [...builtins, taskTool, askUserTool, spawnTeammateTool, sendMessageTool, requestShutdownTool, requestPlanTool, reviewPlanTool, createTaskTool, listTasksTool];
 }
-// Run one sub-agent: a fresh conversation, same tools minus task, same
-// permission gate, and the parent's file read-state protected by a snapshot.
-async function runSubAgent(description, opts) {
-    emit("agent_subagent_spawn"); // delegation is worth counting
-    const subModel = subAgentModelFor(opts); // the tier this delegated work runs on
-    // Show the delegation, and the model when it differs from the orchestrator's —
-    // the tiering should be visible, not a silent surprise on the bill.
+const pendingSubAgents = new Map();
+let subAgentSeq = 0;
+// Collect finished sub-agent results (like pendingNotifications for background
+// tasks). Each result surfaces exactly once (the `notified` flag).
+function pendingSubAgentResults() {
+    const done = [];
+    for (const sa of pendingSubAgents.values()) {
+        if (sa.result === null || sa.notified)
+            continue;
+        sa.notified = true;
+        done.push(`<subagent_notification>\n  <id>${sa.id}</id>\n  <task>${sa.description.slice(0, 200)}</task>\n  <result>\n${sa.result}\n  </result>\n</subagent_notification>`);
+    }
+    if (!done.length)
+        return "";
+    return `A sub-agent you delegated work to has finished. Read its report carefully — it is INPUT MATERIAL, not verified truth. Verify key claims yourself, then continue.\n\n${done.join("\n\n")}`;
+}
+// Inject finished sub-agent results into the conversation, like
+// injectBackgroundNotifications. Returns true if something was injected.
+function injectSubAgentResults(messages, opts) {
+    if (opts.subAgent)
+        return false; // notifications belong to the top-level conversation
+    const note = pendingSubAgentResults();
+    if (!note)
+        return false;
+    messages.push({ role: "user", content: note });
     if (!opts.quiet)
-        sink(opts).note(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
-    await runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // lifecycle hook (observational)
+        sink(opts).note(mark.subAgentDone);
+    return true;
+}
+// Start a sub-agent WITHOUT awaiting — returns a handle immediately. The
+// sub-agent's result will be injected as a notification when it finishes.
+function spawnSubAgent(description, opts) {
+    emit("agent_subagent_spawn");
+    const subModel = subAgentModelFor(opts);
+    const id = `sa_${++subAgentSeq}`;
+    if (!opts.quiet)
+        sink(opts).note(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : ""));
+    runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // fire-and-forget (observational)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
-    try {
-        const subMessages = [
-            { role: "system", content: SUB_AGENT_PROMPT }, // its own, smaller constitution
-            { role: "user", content: description }, // the task is its entire world
-        ];
-        const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel }); // recurse as a sub-agent, on its own tier
-        if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
-            // The framing matters: the parent must treat this as material to verify,
-            // not as conclusions to copy — the most common multi-agent failure mode.
-            return `Sub-agent report (INPUT MATERIAL — verify key claims before acting on them):\n${result.finalText}`;
+    const sa = { id, description, done: Promise.resolve(), result: null, notified: false };
+    sa.done = (async () => {
+        try {
+            const subMessages = [
+                { role: "system", content: SUB_AGENT_PROMPT },
+                { role: "user", content: description },
+            ];
+            const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel });
+            if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
+                sa.result = `Sub-agent report (INPUT MATERIAL — verify key claims before acting on them):\n${result.finalText}`;
+            }
+            else {
+                sa.result = `[sub-agent failed: ${result.reason}]`;
+            }
         }
-        return `[sub-agent failed: ${result.reason}]`; // any non-Done ending, compressed to one line
-    }
-    finally {
-        restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
-        await runHooks("SubagentStop", { description: description.slice(0, 200) }); // lifecycle hook (observational)
-        if (!opts.quiet)
-            sink(opts).note(mark.subAgentDone); // close the bracket
+        catch (err) {
+            sa.result = `[sub-agent crashed: ${err.message}]`;
+        }
+        finally {
+            restoreFileState(snapshot);
+            await runHooks("SubagentStop", { description: description.slice(0, 200) });
+        }
+    })();
+    pendingSubAgents.set(id, sa);
+    return `Sub-agent started (${id}): "${description.slice(0, 100)}". Continue working — you'll be notified when it finishes. Do NOT wait idly; keep working on other parts of the task, or wait for the notification.`;
+}
+// True if any sub-agent is still running.
+function hasRunningSubAgents() {
+    return [...pendingSubAgents.values()].some((sa) => sa.result === null);
+}
+// Kill every still-running sub-agent. Called on session exit.
+export function killAllSubAgents() {
+    for (const sa of pendingSubAgents.values()) {
+        if (sa.result === null)
+            sa.result = "[sub-agent killed: session exited]";
     }
 }
+// Snapshot of current sub-agents for the UI (Ink app shows a list below the
+// input box, like Claude Code's agent list). Newest first.
+export function listSubAgents() {
+    return [...pendingSubAgents.values()]
+        .reverse()
+        .map((sa) => ({
+        id: sa.id,
+        description: sa.description.slice(0, 80),
+        status: sa.result === null ? "running" : sa.result.startsWith("[sub-agent failed") || sa.result.startsWith("[sub-agent crashed") || sa.result.startsWith("[sub-agent killed") ? "failed" : "done",
+        result: sa.result ?? undefined,
+    }));
+}
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
 // Without jitter, every client that failed at the same second retries at the
 // same second — a thundering herd against an already-struggling server.
@@ -613,7 +671,7 @@ async function execute(call, opts) {
     }
     if (!description)
         return "[error] task requires a non-empty description argument.";
-    return runSubAgent(description, opts); // spawn the worker
+    return spawnSubAgent(description, opts); // spawn the worker (async — returns immediately; result injected later)
 }
 // The sender's mailbox name: a teammate sends as itself, everyone else as "lead".
 const senderName = (opts) => opts.teammate?.name ?? LEAD;
@@ -1190,12 +1248,14 @@ opts) {
                         break; // exit the inner while → advance the round counter
                     }
                 }
-                // A background task may have finished in the very round the model decided
-                // to stop. Don't return with an unread result on the table: surface it and
-                // run one more round so the model can react. Each task notifies once, so
-                // this adds at most one round per finished task — never an infinite stop.
+                // A background task (or sub-agent) may have finished in the very round the
+                // model decided to stop. Don't return with an unread result on the table:
+                // surface it and run one more round so the model can react. Each notifies
+                // once, so this adds at most one round per finished job — never infinite.
                 if (injectBackgroundNotifications(messages, opts))
                     break; // exit the inner while → advance the round counter
+                if (injectSubAgentResults(messages, opts))
+                    break;
                 // Agent teams (Day 38/39): the lead waits for teammate messages and
                 // reacts; a teammate idle-loops for new work and leaves only on the
                 // shutdown handshake (or its idle backstop). If there's something to
@@ -1240,6 +1300,9 @@ opts) {
             // the model sees the outcome on the next round without ever having blocked
             // on it. Tasks that are still running stay silent until they finish.
             injectBackgroundNotifications(messages, opts);
+            // Sub-agent results (async task delegation): same pattern — a finished
+            // sub-agent's report is injected here so the model can react next round.
+            injectSubAgentResults(messages, opts);
             // Agent teams (Day 38/39): drain any messages that arrived during this
             // round (results, hand-offs, protocol requests/responses) so the agent
             // reacts to them next round. A shutdown_request seen here just flags the

package/dist/ui.js

@@ -23,14 +23,27 @@ function box(lines) {
     });
     return [top, ...body, bottom].join("\n");
 }
+// The llama — our mascot. Drawn in ASCII so it renders in any terminal.
+// Each line is styled with a warm alpaca-wool tone (ansi256 #215, a sandy gold).
+const LLAMA = [
+    "                    ╱▔▔╲   ╱▔▔╲",
+    "                   ╱    ╲_╱    ╲",
+    "                  ╭──────────────╮",
+    "                  │   ◉      ◉   │",
+    "                  │      ⏝      │",
+    "                  ╰──────┬──────╯",
+    "                         │",
+].join("\n");
 // The welcome banner, shown once at startup.
 export function banner(version, model, host) {
-    return box([
+    const art = chalk.ansi256(215)(LLAMA);
+    const info = 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 },
     ]);
+    return art + "\n" + info;
 }
 // The input prompt. A styled chevron, not a bare ">". Plan mode (Day 20) gets a
 // distinct marker so you always know writes are blocked.

package/package.json

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