agent-from-zero 0.31.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
@@ -27,6 +27,7 @@ import { normalizeDroppedPaths } from "./drop.js"; // drag-and-drop: a dropped f
 import { rememberTool, readMemory, readMemoryTyped, extractMemories, MEMORY_PATH } from "./memory.js"; // long-term project memory + auto-extract
 import { loadSkills, buildSkillTool, findSkill, skillInstructions } from "./skills.js"; // Markdown-as-plugin skills
 import { initCostMeter, DEFAULT_PRICING } from "./cost.js"; // token & cost accounting for /cost
+import { launchInk } from "./ink/launch.js"; // the Ink REPL — the default front-end for interactive sessions
 import { listBackground, hasRunningBackground, killAllBackground } from "./background.js"; // background tasks: /bg view + kill-on-exit (Day 37)
 import { listTeam, resetTeam } from "./team.js"; // agent teams: /team view + reset on clear/resume (Day 38)
 import { boardSummary, resetBoard } from "./board.js"; // task board: /tasks view + reset on clear/resume (Day 40)
@@ -107,6 +108,17 @@ async function main() {
         process.exitCode = 2;
         return;
     }
+    // Interactive sessions default to the Ink REPL (a pinned input box, the
+    // conversation scrolling above it — like Claude Code). It does its OWN full
+    // setup (MCP, skills, judge, cost, hooks, session), so we hand off here before
+    // the readline path below ever runs. Print mode (-p) is a non-interactive
+    // one-shot that streams to stdout, so it stays on the readline path. Set
+    // MINI_AGENT_NO_INK=1 to use the readline REPL below instead (a simpler
+    // reference front-end, and an escape hatch for terminals Ink misbehaves in).
+    if (printTask === null && process.env.MINI_AGENT_NO_INK !== "1") {
+        await launchInk({ resume: argv.includes("-r") || argv.includes("--resume") });
+        return;
+    }
     requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
     // Build the API client once, for the whole session.
     const client = new OpenAI({
@@ -143,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/context.js

@@ -80,9 +80,10 @@ export function recoverFileState() {
 export async function compactHistory(messages, // the history, mutated in place
 client, // the same client the loop uses
 model, // the same model summarizes its own conversation
-signal) {
+signal, // Ctrl+C must abort compaction too
+log = (s) => console.log(s)) {
     const before = estimateHistoryTokens(messages); // for the log line
-    console.log(chalk.magenta(`📦 compacting context (~${before} tokens)...`)); // automatic behavior must be visible
+    log(chalk.magenta(`📦 compacting context (~${before} tokens)...`)); // automatic behavior must be visible
     const res = await client.chat.completions.create({
         model, // same model — no need for a fancier one to summarize
         messages: [...messages, { role: "user", content: SUMMARY_PROMPT }], // full history + the summary instruction
@@ -103,5 +104,5 @@ signal) {
     const recoveredNote = recoverFileState(); // restore working-file contents from disk
     if (recoveredNote)
         messages.push({ role: "user", content: recoveredNote }); // attach as a second message
-    console.log(chalk.magenta(`📦 compacted: ~${before} → ~${estimateHistoryTokens(messages)} tokens`)); // report the result
+    log(chalk.magenta(`📦 compacted: ~${before} → ~${estimateHistoryTokens(messages)} tokens`)); // report the result
 }

package/dist/ink/app.js

@@ -0,0 +1,518 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState, useEffect, useRef } from "react";
+import { Box, Text, Static, useInput, useApp } from "ink";
+import chalk from "chalk";
+import { formatElapsed, renderMenu, MENU_HINT, formatModelChoices } from "../ui.js"; // status format + the SAME pure menu renderer the readline REPL uses
+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, 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";
+import { clearTodos } from "../todos.js";
+import { resetTeam } from "../team.js";
+import { resetBoard } from "../board.js";
+import { clearReasoning, clearToolCalls, getReasoning, getToolCalls, cleanup as tuiCleanup } from "../tui.js";
+import { expandMentions } from "../mentions.js"; // @file mentions → attach file contents
+import { normalizeDroppedPaths } from "../drop.js"; // drag-and-drop a file → its absolute path in the input
+import { newSessionId, saveSession, listSessions, loadSession } from "../session.js";
+import { isPlanMode, setPlanMode } from "../permissions.js";
+import { findSkill, skillInstructions } from "../skills.js";
+import { extractMemories } from "../memory.js";
+import { runHooks } from "../hooks.js";
+import { emit } from "../telemetry.js";
+import { makeInkSink } from "./sink.js"; // turns the loop's output into React state
+import { runInfoCommand } from "./commands.js"; // the non-interactive slash commands
+// 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(() => {
+        const id = setInterval(() => setF((x) => (x + 1) % SPINNER_FRAMES.length), 80);
+        return () => clearInterval(id);
+    }, []);
+    return _jsx(Text, { color: "cyan", children: SPINNER_FRAMES[f] });
+}
+// One committed line of conversation. `user` is a highlight bar; `answer` is a
+// finished reply rendered as markdown; `note` is already-formatted narration.
+function ItemView({ item }) {
+    if (item.kind === "user") {
+        return (_jsx(Box, { marginTop: 1, children: _jsx(Text, { backgroundColor: "gray", color: "whiteBright", children: `> ${item.text}` }) }));
+    }
+    if (item.kind === "answer") {
+        return (_jsxs(Box, { marginTop: 1, flexDirection: "row", children: [_jsx(Text, { color: "green", children: "\u23FA " }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { children: renderMarkdown(item.text) }) })] }));
+    }
+    return (_jsx(Box, { children: _jsx(Text, { children: item.text }) }));
+}
+// The bottom status bar — same content + colours as the non-Ink statusLine():
+// [model] · 📁 dir · 🌿 branch · ctx N% · $cost · ⏱ time.
+function StatusBar({ model, dir, branch, status }) {
+    const parts = [
+        _jsxs(Text, { color: "cyan", children: ["[", model, "]"] }, "m"),
+        _jsxs(Text, { dimColor: true, children: ["\uD83D\uDCC1 ", dir] }, "d"),
+        ...(branch ? [_jsxs(Text, { color: "green", children: ["\uD83C\uDF3F ", branch] }, "b")] : []),
+        _jsxs(Text, { dimColor: true, children: ["ctx ", status.ctxPct, "%"] }, "c"),
+        _jsxs(Text, { color: "yellow", children: ["$", status.cost.toFixed(status.cost < 1 ? 4 : 2)] }, "$"),
+        _jsxs(Text, { dimColor: true, children: ["\u23F1 ", formatElapsed(status.elapsedMs)] }, "t"),
+    ];
+    return (_jsx(Box, { children: parts.map((p, i) => (_jsxs(React.Fragment, { children: [i > 0 && _jsx(Text, { dimColor: true, children: "  ·  " }), p] }, i))) }));
+}
+// One human note per non-Done ending, so the user always learns why a turn stopped.
+const EXIT_NOTES = {
+    [TerminateReason.CircuitBreaker]: "3 API failures in a row — stopping here.",
+    [TerminateReason.RetryBudgetExhausted]: "Too many failed API calls — giving up. Check your network.",
+    [TerminateReason.RateLimitBudgetExhausted]: "The provider keeps rate-limiting us. Wait a minute, then retry.",
+    [TerminateReason.ContextTooLong]: "The conversation no longer fits the context window. Use /clear.",
+    [TerminateReason.CompactionFailed]: "Automatic compaction kept failing. Use /clear to start fresh.",
+    [TerminateReason.FatalApiError]: "Unrecoverable API error — check your API key and request.",
+    [TerminateReason.UserInterrupt]: "Interrupted — back at the prompt.",
+};
+export function App({ session, runTurn }) {
+    const { client, messages, systemMessage, costMeter, skills, judge, model, dir, branch, getStatus } = session;
+    // Seed the scrollback with the welcome banner + the dim startup notices.
+    const [items, setItems] = useState(() => [{ kind: "note", text: session.bannerText }, ...session.notices.map((n) => ({ kind: "note", text: chalk.dim(n) }))]);
+    const [status, setStatus] = useState(null); // the live spinner line
+    const [live, setLive] = useState(null); // the streaming answer
+    const [input, setInput] = useState(""); // the current input buffer
+    const [busy, setBusy] = useState(false); // a turn is in flight
+    const [pending, setPending] = useState(null); // a prompt/menu blocking input
+    const [menuSel, setMenuSel] = useState(0); // the select menu's cursor
+    const [formState, setFormState] = useState(null); // the ask_user form's state
+    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;
+    const note = (text) => pushItem({ kind: "note", text });
+    const sink = useRef(makeInkSink({ setStatus, setLive, pushItem })).current;
+    const history = useRef([]).current; // past prompts, for ↑/↓ recall
+    const turn = useRef(null); // the in-flight turn, for Esc-interrupt
+    useEffect(() => {
+        const id = setInterval(() => setTick((t) => t + 1), 1000);
+        return () => clearInterval(id);
+    }, []);
+    // Open a one-of-N menu and run `onChoose` with the picked index (-1 = cancel).
+    const openSelect = (header, options, onChoose) => {
+        setMenuSel(0);
+        setPending({ kind: "select", header, options, onChoose });
+    };
+    // Run one conversation turn through the real loop. `display` is what scrolls up
+    // as the prompt (a user highlight bar, or a note for /skill); the loop appends
+    // `content` to `messages` itself. The permission menu + ask_user form raise a
+    // `pending` prompt that returns a promise the loop awaits.
+    const runConversationTurn = (content, display) => {
+        pushItem(display);
+        clearReasoning(); // Ctrl+R should reveal THIS turn's thinking
+        clearToolCalls(); // ...and Ctrl+T THIS turn's tool calls
+        setBusy(true);
+        const controller = new AbortController();
+        const tstate = { controller, interrupted: false };
+        turn.current = tstate; // expose it so Esc can interrupt this turn
+        const hooks = {
+            output: sink,
+            confirm: (question, toolName) => new Promise((resolve) => {
+                const allowLabel = toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session";
+                openSelect(`⚠ approval needed — ${question}`, ["Yes", allowLabel, "No — let me tell the agent what to do instead"], (i) => {
+                    const approved = i === 0 || i === 1;
+                    if (approved && i === 1 && toolName)
+                        CONFIG.permissions.allow.push(`tool:${toolName}`); // "don't ask again" → session allowlist
+                    note(`${chalk.yellow("⚠ approval")} — ${question.split("\n")[0]} → ${approved ? chalk.green("✓ approved") : chalk.yellow("✗ declined")}`);
+                    resolve(approved);
+                });
+            }),
+            askUser: (questions) => new Promise((resolve) => {
+                if (!questions.length)
+                    return resolve(null);
+                setFormState(initFormState(questions));
+                setPending({ kind: "form", questions, resolve });
+            }),
+            signal: controller.signal,
+            isInterrupted: () => tstate.interrupted, // polled between steps for a clean stop
+            judge,
+        };
+        runTurn(content, hooks)
+            .then(async (result) => {
+            if (result.reason !== TerminateReason.Done)
+                note(chalk.yellow(`⚠️ ${EXIT_NOTES[result.reason] ?? result.reason}`));
+            saveSession(sessionId, model, messages); // snapshot after every turn — crash-safe by construction
+            if (CONFIG.memory.autoExtract && result.reason === TerminateReason.Done) {
+                try {
+                    const got = await extractMemories(client, CONFIG.subAgentModel || model, messages);
+                    if (got.length)
+                        note(chalk.dim(`(remembered ${got.length}: ${got.map((g) => g.fact.slice(0, 50)).join("; ")})`));
+                }
+                catch {
+                    /* memory extraction must never break the session */
+                }
+            }
+        })
+            .catch((e) => note(chalk.red(`[error] ${e.message}`)))
+            .finally(() => {
+            turn.current = null;
+            setBusy(false);
+            setStatus(null);
+            setLive(null);
+        });
+    };
+    // A normal (non-command) prompt: run UserPromptSubmit hooks, expand @file
+    // mentions, then start the turn. Mirrors agent.ts's submit path.
+    const submitLine = async (text) => {
+        if (text === "exit" || text === "quit")
+            return doExit();
+        if (await handleCommand(text))
+            return; // slash commands never reach the model
+        const hook = await runHooks("UserPromptSubmit", { prompt: text });
+        if (hook.block)
+            return note(chalk.yellow(`(prompt blocked by a UserPromptSubmit hook: ${hook.feedback.slice(0, 150)})`));
+        const injected = hook.stdout ? `\n\n[context added by a UserPromptSubmit hook]\n${hook.stdout}` : "";
+        const { augmented, mentions } = expandMentions(text);
+        const attached = mentions.filter((m) => m.status === "ok").map((m) => m.raw);
+        const refused = mentions.filter((m) => m.status === "denied").map((m) => m.raw);
+        if (attached.length)
+            note(chalk.dim(`(attached ${attached.length} file${attached.length === 1 ? "" : "s"}: ${attached.join(", ")})`));
+        if (refused.length)
+            note(chalk.yellow(`(refused secret file${refused.length === 1 ? "" : "s"}: ${refused.join(", ")})`));
+        runConversationTurn(augmented + injected, { kind: "user", text }); // show the original line; send the augmented content
+    };
+    // Handle a /slash command. Returns true if the line was a command (handled).
+    const handleCommand = async (line) => {
+        const info = runInfoCommand(line, { skills, costMeter }); // /help /cost /memory /stats /todos /bg /team /tasks /skills /undo /diff
+        if (info !== null) {
+            note(info);
+            return true;
+        }
+        // /model [name|save <name>]
+        if (line === "/model" || line.startsWith("/model ")) {
+            const arg = line.slice("/model".length).trim();
+            const save = arg === "save" || arg.startsWith("save ");
+            const name = save ? arg.slice(4).trim() : arg;
+            const apply = (next) => {
+                const prev = CONFIG.model;
+                CONFIG.model = next;
+                if (save) {
+                    saveGlobalSetting("model", next);
+                    note(chalk.dim(`(model: ${prev} → ${next} · saved as your default)`));
+                }
+                else {
+                    note(chalk.dim(`(model: ${prev} → ${next} · this session only — use "/model save ${next}" to keep it)`));
+                }
+            };
+            if (name) {
+                apply(name);
+                return true;
+            }
+            note(chalk.dim(`model: ${CONFIG.model}\nendpoint: ${CONFIG.baseURL}\ncontext window: ${CONFIG.contextWindow} tokens (compaction at ~${COMPACT_AT})`));
+            let models = [];
+            try {
+                const page = await client.models.list();
+                models = [...new Set((page.data ?? []).map((m) => m.id).filter(Boolean))].sort();
+            }
+            catch {
+                /* not every endpoint lists models */
+            }
+            if (!models.length) {
+                note(chalk.dim("(couldn't list models from this endpoint — switch with: /model <name>)"));
+                return true;
+            }
+            openSelect("switch model (this session):", formatModelChoices(models, CONFIG.model), (i) => {
+                if (i < 0 || models[i] === CONFIG.model)
+                    return note(chalk.dim("(model unchanged)"));
+                apply(models[i]);
+            });
+            return true;
+        }
+        // /skill <name> — run a skill on the user's behalf (works for user-only skills)
+        if (line === "/skill" || line.startsWith("/skill ")) {
+            const name = line.slice("/skill".length).trim();
+            if (!name) {
+                note(chalk.dim(skills.length ? `usage: /skill <name> — available: ${skills.map((s) => s.name).join(", ")}` : "(no skills in this project — add one at .mini-agent/skills/<name>/SKILL.md)"));
+                return true;
+            }
+            const s = findSkill(skills, name);
+            if (!s) {
+                note(chalk.yellow(`(no skill named "${name}")`));
+                return true;
+            }
+            runConversationTurn(`Run the "${s.name}" skill.\n\n${skillInstructions(s)}`, { kind: "note", text: chalk.dim(`(running skill: ${s.name})`) });
+            return true;
+        }
+        switch (line) {
+            case "/clear":
+                messages.length = 0; // mutate in place — same array ref the loop holds
+                messages.push({ role: "system", content: systemMessage });
+                forgetFilesExcept([]);
+                clearUndo();
+                clearTodos();
+                resetTeam();
+                resetBoard();
+                clearReasoning();
+                clearToolCalls();
+                setSessionId(newSessionId());
+                note(chalk.dim("(history cleared)"));
+                return true;
+            case "/plan":
+                if (isPlanMode()) {
+                    setPlanMode(false);
+                    setPlan(false);
+                    note(chalk.dim("(plan mode OFF — writing and executing tools enabled again)"));
+                }
+                else {
+                    setPlanMode(true);
+                    setPlan(true);
+                    messages.push({ role: "user", content: PLAN_MODE_NOTICE });
+                    note(chalk.dim("(plan mode ON — read-only research; the agent will present a plan for you to approve)"));
+                }
+                return true;
+            case "/compact": {
+                if (messages.length <= 1) {
+                    note(chalk.dim("(nothing to compact yet)"));
+                    return true;
+                }
+                setBusy(true);
+                try {
+                    await compactHistory(messages, client, CONFIG.model, new AbortController().signal, note);
+                }
+                catch (err) {
+                    note(chalk.yellow(`compaction failed: ${err.message}`));
+                }
+                finally {
+                    setBusy(false);
+                }
+                return true;
+            }
+            case "/resume": {
+                const sessions = listSessions(10);
+                if (!sessions.length) {
+                    note(chalk.dim("(no saved sessions in this project yet)"));
+                    return true;
+                }
+                const labels = sessions.map((s) => `${s.savedAt.slice(0, 16).replace("T", " ")} · ${s.messageCount} msg · ${s.title.slice(0, 60)}`);
+                openSelect("recent sessions in this project:", labels, (i) => {
+                    if (i < 0)
+                        return note(chalk.dim("(cancelled)"));
+                    const chosen = loadSession(sessions[i].id);
+                    if (!chosen)
+                        return note(chalk.yellow("(could not load that session — it may be corrupt)"));
+                    messages.length = 0;
+                    messages.push({ role: "system", content: systemMessage }, ...chosen.messages);
+                    setSessionId(chosen.id);
+                    forgetFilesExcept([]);
+                    clearUndo();
+                    clearTodos();
+                    resetTeam();
+                    resetBoard();
+                    note(chalk.dim(`(resumed ${chosen.id} — ${chosen.messages.length} messages; files must be re-read before editing)`));
+                });
+                return true;
+            }
+            default:
+                if (line.startsWith("/")) {
+                    note(chalk.dim(`unknown command: ${line} — try /help`));
+                    return true; // consumed — don't send typos to the model
+                }
+                return false; // a normal task line
+        }
+    };
+    // Graceful exit: SessionEnd hooks (tiny budget — the user may be leaving), then unmount.
+    const doExit = async () => {
+        try {
+            await runHooks("SessionEnd", {});
+        }
+        catch {
+            /* never block exit on a hook */
+        }
+        emit("agent_session_end");
+        tuiCleanup();
+        exit();
+    };
+    useInput((char, key) => {
+        if (key.ctrl && char === "c") {
+            tuiCleanup();
+            return exit(); // Ctrl+C quits immediately (process.on exit cleans up MCP/background)
+        }
+        // Ctrl+R / Ctrl+T: reveal the LAST answer's collapsed thinking / tool calls.
+        if (key.ctrl && char === "r")
+            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) {
+            const t = turn.current;
+            if (t && !t.interrupted) {
+                t.interrupted = true; // the loop polls this between steps
+                t.controller.abort(); // cancel the in-flight API request
+                note(chalk.yellow("(esc — interrupting; back at the prompt)"));
+            }
+            return;
+        }
+        // A select menu is up (approval / model / resume): ↑↓ move, Enter choose, Esc cancel.
+        if (pending?.kind === "select") {
+            const n = pending.options.length;
+            if (key.upArrow)
+                setMenuSel((i) => (i - 1 + n) % n);
+            else if (key.downArrow)
+                setMenuSel((i) => (i + 1) % n);
+            else if (key.return || key.escape) {
+                const choice = key.escape ? -1 : menuSel;
+                const onChoose = pending.onChoose;
+                setPending(null);
+                onChoose(choice);
+            }
+            return;
+        }
+        // The ask_user form is up: reuse form.ts's pure state machine verbatim.
+        if (pending?.kind === "form" && formState) {
+            if (key.upArrow)
+                setFormState(reduceForm(pending.questions, formState, "up").state);
+            else if (key.downArrow || key.tab)
+                setFormState(reduceForm(pending.questions, formState, "down").state);
+            else if (key.return || char === " ") {
+                const next = reduceForm(pending.questions, formState, "select");
+                setFormState(next.state);
+                if (next.done) {
+                    pending.resolve(collectAnswers(pending.questions, next.state));
+                    setPending(null);
+                    setFormState(null);
+                }
+            }
+            else if (key.escape) {
+                pending.resolve(null);
+                setPending(null);
+                setFormState(null);
+            }
+            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);
+            if (!text)
+                return;
+            if (text.trim())
+                history.push(text); // remember non-empty entries for ↑/↓
+            void submitLine(text);
+        }
+        else if (key.upArrow) {
+            // ↑ recall an earlier prompt (newest-first), like a shell.
+            if (!history.length)
+                return;
+            const idx = histIdx === null ? history.length - 1 : Math.max(0, histIdx - 1);
+            setHistIdx(idx);
+            setInput(history[idx]);
+        }
+        else if (key.downArrow) {
+            // ↓ walk back toward the fresh line.
+            if (histIdx === null)
+                return;
+            const idx = histIdx + 1;
+            if (idx >= history.length) {
+                setHistIdx(null);
+                setInput("");
+            }
+            else {
+                setHistIdx(idx);
+                setInput(history[idx]);
+            }
+        }
+        else if (key.backspace || key.delete) {
+            setInput((s) => s.slice(0, -1));
+        }
+        else if (char && !key.ctrl && !key.meta) {
+            // A bulk chunk (a paste / a dropped file path) is normalized: a dropped
+            // file becomes a clean absolute path; ordinary pasted prose is unchanged.
+            const add = char.length > 1 ? normalizeDroppedPaths(char) : char;
+            setHistIdx(null);
+            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("…") : 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/chat.js

@@ -0,0 +1,22 @@
+import { runLoop } from "../loop.js"; // the REAL agent loop — tools, permissions, retries, the lot
+import { CONFIG } from "../config.js"; // model + sub-agent tier
+// Drive one real turn through the loop. The loop mutates `messages` in place
+// (appends the assistant reply + any tool messages), exactly as the readline
+// REPL relies on — so we only push the user turn here and let the loop do the
+// rest. All screen output flows through hooks.output (the Ink sink).
+export function makeRunTurn(client, messages) {
+    return async (input, hooks) => {
+        messages.push({ role: "user", content: input });
+        return runLoop(messages, {
+            client,
+            model: CONFIG.model,
+            signal: hooks.signal,
+            isInterrupted: hooks.isInterrupted,
+            confirm: hooks.confirm,
+            askUser: hooks.askUser,
+            judge: hooks.judge,
+            subAgentModel: CONFIG.subAgentModel,
+            output: hooks.output,
+        });
+    };
+}