agent-from-zero 0.5.0 → 0.28.0

package/dist/team.js

@@ -0,0 +1,214 @@
+// ============ Agent teams (Day 38) ============
+// The leap past the one-shot sub-agent (the `task` tool). A sub-agent is fire-
+// and-forget: fresh context, runs to completion, returns ONE final report, gone.
+// That breaks down on big work — a teammate restructuring the API can't tell the
+// teammate touching auth what it changed, because they never talk; each only
+// hands back a conclusion at the very end.
+//
+// A TEAM fixes that. A Lead spawns several PERSISTENT teammates that run
+// concurrently and coordinate through ASYNCHRONOUS MAILBOXES: any agent can drop
+// a message in any other agent's inbox at any time, and the recipient sees it on
+// its next round. The Lead injects its inbox into its own conversation, so it
+// reacts to teammate results as they arrive instead of blocking on a single
+// return value.
+//
+// Why mailboxes live ON DISK (落盘), not in a Map: OBSERVABILITY. While the team
+// runs you can `cat .mini-agent/team/<agent>.jsonl` and watch messages in flight
+// — the coordination is a thing you can inspect, not hidden process state. The
+// Python reference guards these files with proper-lockfile because it runs
+// teammates on OS threads; we run them as async tasks on ONE event loop, where a
+// single appendFileSync — or a readFileSync+rmSync pair — runs to completion
+// without yielding, so two agents can never interleave mid-operation. No lock
+// needed. (Cross-process is out of scope: one CLI instance per project.)
+import fs from "node:fs"; // mailboxes are real files
+import path from "node:path"; // path joining
+// The mailbox name of the coordinator. Teammates message "lead" to report back;
+// the Lead reads its own inbox under this name.
+export const LEAD = "lead";
+// At most this many teammates per Lead — a cost/runaway ceiling, like every
+// other loop in this codebase. A handful of specialists is the whole idea; a
+// swarm is a footgun.
+export const MAX_TEAMMATES = 4;
+const pendingRequests = new Map(); // requestId → state
+let reqSeq = 0; // increments per request — seeds the id
+const teammates = new Map(); // name → teammate, for this run
+// ---- The mailbox files ------------------------------------------------------
+// Resolved lazily (a function, not a const) so it tracks the cwd, exactly like
+// session.ts. The first touch this process run wipes any stale mailboxes left by
+// a crashed earlier run — a new team must start with empty inboxes.
+let wiped = false;
+function teamRoot() {
+    const root = path.resolve(".mini-agent", "team");
+    fs.mkdirSync(root, { recursive: true });
+    if (!wiped) {
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".jsonl"))
+                fs.rmSync(path.join(root, f)); // fresh inboxes for this run
+        wiped = true;
+    }
+    return root;
+}
+function inboxPath(agent) {
+    // Keep file names filesystem-safe: agent names come from the model.
+    const safe = agent.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(teamRoot(), `${safe}.jsonl`);
+}
+// Drop a message in the recipient's inbox: one JSON object per line (JSONL), so
+// appends never have to rewrite the file and a half-written line can't corrupt
+// the earlier ones. Synchronous on purpose — see the no-lock note up top.
+export function sendMessage(from, to, content, type = "message") {
+    const msg = { from, to, content, type, ts: Date.now() };
+    fs.appendFileSync(inboxPath(to), JSON.stringify(msg) + "\n");
+}
+// Drop a PROTOCOL message in an inbox — same JSONL bus, but tagged with its
+// contract role, request_id, and (for responses) the decision. This is how a
+// request and its answer travel; the consume step on the other side routes by
+// `kind` and correlates by `requestId`.
+export function sendProtocol(from, to, kind, requestId, content, status) {
+    const msg = { from, to, content, type: "message", ts: Date.now(), kind, requestId, status };
+    fs.appendFileSync(inboxPath(to), JSON.stringify(msg) + "\n");
+}
+// ---- Protocol state (the pending_requests dict) -----------------------------
+// Open a request: store it pending and return its fresh id. The caller then
+// sends the matching *_request message carrying this id.
+export function createRequest(kind, from, to, payload) {
+    const requestId = `req_${String(++reqSeq).padStart(6, "0")}`; // req_000001
+    pendingRequests.set(requestId, { requestId, kind, from, to, status: "pending", payload, createdAt: Date.now() });
+    return requestId;
+}
+export function getRequest(requestId) {
+    return pendingRequests.get(requestId);
+}
+// Correlate a response to its request — the reference's match_response. The
+// guard that matters: the response's contract MUST match the request's kind, so
+// a shutdown_response can never accidentally approve a plan_approval. Returns the
+// updated state, or an error string the caller can hand back to the model.
+export function resolveResponse(requestId, kind, approved) {
+    const state = pendingRequests.get(requestId);
+    if (!state)
+        return { ok: false, error: `No pending request "${requestId}".` };
+    if (state.kind !== kind)
+        return { ok: false, error: `Request "${requestId}" is a ${state.kind} request, not ${kind} — wrong response type.` };
+    if (state.status !== "pending")
+        return { ok: false, error: `Request "${requestId}" was already ${state.status}.` };
+    state.status = approved ? "approved" : "rejected";
+    return { ok: true, state };
+}
+// Requests still awaiting an answer for a given recipient — used by the lead's
+// view and to surface "you still owe an answer" prompts.
+export function openRequestsFor(agent) {
+    return [...pendingRequests.values()].filter((r) => r.to === agent && r.status === "pending");
+}
+// Read and CONSUME an inbox: parse every message, then delete the file. The
+// consumptive pattern (read = remove) means a message is delivered exactly once
+// and the on-disk inbox always shows only what is still pending. Unreadable
+// lines are skipped, never fatal.
+export function readInbox(agent) {
+    const p = inboxPath(agent);
+    if (!fs.existsSync(p))
+        return []; // nothing waiting
+    let raw = "";
+    try {
+        raw = fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return [];
+    }
+    fs.rmSync(p, { force: true }); // consume: the read empties the mailbox
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            out.push(JSON.parse(t));
+        }
+        catch {
+            /* skip a corrupt line, keep the rest */
+        }
+    }
+    return out;
+}
+// Peek at how many messages are waiting WITHOUT consuming them. The loop uses
+// this to decide whether to keep going; reading would empty the inbox before the
+// agent's own turn got to see it.
+export function inboxCount(agent) {
+    const p = inboxPath(agent);
+    if (!fs.existsSync(p))
+        return 0;
+    try {
+        return fs.readFileSync(p, "utf8").split("\n").filter((l) => l.trim()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---- The registry -----------------------------------------------------------
+export function teammateExists(name) {
+    return teammates.has(name);
+}
+export function teammateCount() {
+    return teammates.size;
+}
+// Record a newly spawned teammate. The caller supplies the promise for its loop.
+export function registerTeammate(name, role, done) {
+    teammates.set(name, { name, role, status: "running", state: "active", startedAt: Date.now(), done });
+}
+// Mark a teammate finished. `ok=false` means its loop ended on a non-Done reason.
+export function finishTeammate(name, ok) {
+    const t = teammates.get(name);
+    if (t)
+        t.status = ok ? "done" : "failed";
+}
+// How many teammates are still running — at least one running teammate means the
+// team isn't disbanded yet.
+export function activeTeammateCount() {
+    return [...teammates.values()].filter((t) => t.status === "running").length;
+}
+// ---- Day 39: active/idle + shutdown plumbing --------------------------------
+// A running teammate flips between actively working a round and idling on its
+// inbox. The lead waits while ANY teammate is actively working; once they're all
+// idle (or done), the work has converged and the lead can wrap up the team.
+export function setTeammateState(name, state) {
+    const t = teammates.get(name);
+    if (t && t.status === "running")
+        t.state = state;
+}
+export function anyTeammateBusy() {
+    return [...teammates.values()].some((t) => t.status === "running" && t.state === "active");
+}
+export function runningTeammates() {
+    return [...teammates.values()].filter((t) => t.status === "running").map((t) => t.name);
+}
+// The shutdown handshake: the lead opens a shutdown request against a teammate,
+// stamping it with the request_id; the teammate sees the flag at its next
+// stop-point, replies shutdown_response(approved) with that id, and exits.
+export function markShutdown(name, requestId) {
+    const t = teammates.get(name);
+    if (t)
+        t.shutdownRequestId = requestId;
+}
+export function shutdownRequestId(name) {
+    return teammates.get(name)?.shutdownRequestId;
+}
+// A snapshot for the /team command: newest first, with live state + inbox depth.
+export function listTeam() {
+    return [...teammates.values()]
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .map((t) => ({
+        name: t.name,
+        role: t.role,
+        // While running, show active vs idle (Day 39) — that's the interesting bit.
+        status: t.status === "running" ? t.state : t.status,
+        elapsed: Math.round((Date.now() - t.startedAt) / 1000),
+        pending: inboxCount(t.name),
+    }));
+}
+// Wipe the registry AND the in-flight requests (and let the next touch clear the
+// mailbox files). Called on /clear and /resume, and after the lead disbands the
+// team — a new conversation starts with no team and no dangling protocols.
+export function resetTeam() {
+    teammates.clear();
+    pendingRequests.clear();
+    wiped = false; // the next mailbox touch wipes stale files again
+}

package/dist/todos.js

@@ -0,0 +1,87 @@
+import chalk from "chalk"; // the one color source — match ui.ts's vocabulary
+const STATUSES = ["pending", "in_progress", "completed"];
+// ---- pure: validate the model's argument into a clean Todo[] ----------------
+// The model's arguments are probabilistic, so be strict and return a precise
+// repair message (errors are text the model can act on) rather than trusting it.
+// Rule worth enforcing: AT MOST ONE in_progress — "do one thing at a time" is the
+// whole discipline a plan buys you; many-in-progress is just a relabeled backlog.
+export function parseTodos(raw) {
+    if (!Array.isArray(raw))
+        return { error: "`todos` must be an array of { content, status }" };
+    const todos = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (typeof item !== "object" || item === null)
+            return { error: `todo #${i + 1} must be an object with content + status` };
+        const content = typeof item.content === "string" ? item.content.trim() : "";
+        if (!content)
+            return { error: `todo #${i + 1} is missing non-empty "content"` };
+        if (!STATUSES.includes(item.status))
+            return { error: `todo #${i + 1} has bad status "${String(item.status)}" — use pending | in_progress | completed` };
+        todos.push({ content, status: item.status });
+    }
+    if (todos.filter((t) => t.status === "in_progress").length > 1)
+        return { error: "only one todo may be in_progress at a time — finish or re-queue the others" };
+    return { todos };
+}
+// ---- pure: render the checklist for the terminal ----------------------------
+// Glyphs over words: a column of ✓ / ▶ / ○ scans at a glance. The in-progress
+// item is the loud one (that's where attention belongs); done items fade.
+export function renderTodos(todos) {
+    if (!todos.length)
+        return chalk.dim("  (no todos)");
+    return todos
+        .map((t) => {
+        if (t.status === "completed")
+            return chalk.green("  ✓ ") + chalk.dim.strikethrough(t.content);
+        if (t.status === "in_progress")
+            return chalk.cyan.bold("  ▶ ") + chalk.bold(t.content);
+        return chalk.dim("  ○ " + t.content);
+    })
+        .join("\n");
+}
+// ---- pure: a one-line confirmation for the MODEL (cheap, no ANSI) -----------
+// The pretty list goes to the screen; the model only needs the tally + what it
+// said it's doing now, so we don't burn tokens echoing its own plan back at it.
+export function summarizeTodos(todos) {
+    const done = todos.filter((t) => t.status === "completed").length;
+    const doing = todos.find((t) => t.status === "in_progress");
+    const pending = todos.filter((t) => t.status === "pending").length;
+    const head = `Plan saved — ${done} done, ${doing ? 1 : 0} in progress, ${pending} pending.`;
+    if (doing)
+        return `${head} Now: ${doing.content}`;
+    if (todos.length && done === todos.length)
+        return `${head} All items complete.`;
+    return head;
+}
+// ---- session state + the nag --------------------------------------------------
+// The current plan lives for the session (in process memory, like Claude Code's).
+let current = [];
+let staleRounds = 0; // tool-rounds since the plan was last touched
+export function setTodos(todos) {
+    current = todos;
+    staleRounds = 0; // an update is a fresh signal — restart the patience clock
+}
+export function getTodos() {
+    return current;
+}
+export function clearTodos() {
+    current = [];
+    staleRounds = 0; // /clear and session switches wipe the plan too
+}
+// Call once per tool-round. If there's an unfinished plan the model has stopped
+// touching, return a reminder to inject (else null). This is the "nag": without
+// it the model writes a plan once and never looks back — the list goes stale and
+// stops meaning anything. We re-arm after firing, so it nudges every N rounds,
+// not every round (which would be noise).
+export const NAG_AFTER_ROUNDS = 3;
+export function todoNag() {
+    const unfinished = current.some((t) => t.status !== "completed");
+    if (!current.length || !unfinished)
+        return null; // no plan, or all done → nothing to nag about
+    staleRounds++;
+    if (staleRounds < NAG_AFTER_ROUNDS)
+        return null;
+    staleRounds = 0; // re-arm
+    return "[plan reminder] Your todo list still has unfinished items but you haven't updated it in a few steps. If you've made progress, call todo_write to mark items completed / move the next one to in_progress; if the plan changed, rewrite it. Don't lose the original goal.";
+}

package/dist/tools.js

@@ -2,6 +2,11 @@ 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
+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
@@ -67,6 +72,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 +108,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 +237,133 @@ 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
+// 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.";
+    },
+};
+// ============ 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 ============
-// 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,
+    run_bash_background: runBashBackground,
+    bash_output: bashOutput,
+    exit_plan_mode: exitPlanMode,
+    todo_write: todoWrite,
 };
-// 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,11 +381,19 @@ 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
     // 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/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");
+}