agent-from-zero 0.31.0 → 0.32.0

package/dist/agent.js

@@ -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({

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,435 @@
+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 } 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
+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 [, 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 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;
+        }
+        if (busy)
+            return; // a turn in flight with no prompt — ignore typing for now (type-ahead is later)
+        if (key.return) {
+            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("…") : 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() })] }));
+}

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,
+        });
+    };
+}

package/dist/ink/commands.js

@@ -0,0 +1,103 @@
+import chalk from "chalk";
+import path from "node:path";
+import { CONFIG } from "../config.js";
+import { statsReport } from "../telemetry.js";
+import { readMemoryTyped, MEMORY_PATH } from "../memory.js";
+import { getTodos, renderTodos } from "../todos.js";
+import { listBackground } from "../background.js";
+import { listTeam } from "../team.js";
+import { boardSummary } from "../board.js";
+import { undoLast, sessionChanges } from "../undo.js";
+import { renderDiff } from "../diff.js";
+// The non-interactive slash commands: each produces a block of text to commit as
+// a note. Lifted from agent.ts's handleCommand, with console.log → a returned
+// string so the Ink REPL can render them inside its tree. The stateful commands
+// (/clear, /compact, /plan, /model, /resume, /skill) stay in the App — they
+// mutate the conversation or pop an interactive menu.
+// The in-session command reference shown by /help.
+export const SESSION_HELP = `commands:
+  /help      this text
+  /clear     wipe the conversation (and the file read-state) — fresh start
+  /compact   compact the history into a summary right now (happens automatically near the limit)
+  /model     switch model for THIS session: "/model" to pick from a list, "/model <name>" to set; "/model save <name>" to make it your default
+  /stats     event counts for this session (local telemetry — nothing leaves this machine)
+  /memory    show the durable facts the agent remembers about this project
+  /cost      tokens, cache hit rate and estimated spend this session (local)
+  /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
+  /todos     show the agent's current task plan (it maintains one with todo_write on multi-step work)
+  /bg        list background tasks this session (run_bash_background) and their status
+  /team      list the agent team (spawn_teammate): each teammate's role, status, and pending inbox
+  /tasks     show the shared task board (create_task/claim_task): each task's status, owner, and dependencies
+  /undo      revert the most recent file write (write_file / edit_file) this session
+  /diff      show every file changed this session, as a diff from where it started
+  /resume    list recent sessions in this project and continue one of them
+  /skills    list the reusable skills available in this project
+  /skill <name>  run a skill yourself (works even for user-only skills)
+  exit       leave (Ctrl+C does the same)
+
+keys (at the prompt):
+  Ctrl+R     reveal the model's thinking for the last answer (collapsed behind a spinner by default)
+  Ctrl+T     reveal the folded tool-call trace for the last answer`;
+// Run a non-interactive command. Returns the note text to display, or null if
+// `line` isn't one of these (the App handles the rest).
+export function runInfoCommand(line, ctx) {
+    switch (line) {
+        case "/help":
+            return chalk.dim(SESSION_HELP);
+        case "/cost":
+            return chalk.dim(ctx.costMeter.report()); // tokens, cache hit rate, estimated spend (local)
+        case "/stats":
+            return chalk.dim(statsReport()); // local counters, busiest first
+        case "/memory": {
+            const entries = readMemoryTyped();
+            return chalk.dim(entries.length
+                ? `long-term memory (${MEMORY_PATH}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
+                : `(no long-term memory yet — the model saves facts with the remember tool${CONFIG.memory.autoExtract ? "" : "; turn on settings.memory.autoExtract to capture them automatically"})`);
+        }
+        case "/todos": {
+            const todos = getTodos();
+            return todos.length ? renderTodos(todos) : chalk.dim("(no plan yet — the agent writes one with todo_write on multi-step tasks)");
+        }
+        case "/bg": {
+            const bg = listBackground();
+            if (!bg.length)
+                return chalk.dim("(no background tasks — the agent starts them with run_bash_background for slow commands)");
+            const icon = { running: chalk.yellow("●"), completed: chalk.green("✓"), failed: chalk.red("✗"), killed: chalk.dim("∅") };
+            return chalk.dim("background tasks this session:\n") + bg.map((t) => chalk.dim(`  ${icon[t.status]} ${t.id} [${t.status}, ${t.elapsed}s] — ${t.command.slice(0, 70)}`)).join("\n");
+        }
+        case "/team": {
+            const team = listTeam();
+            if (!team.length)
+                return chalk.dim("(no team — the agent forms one with spawn_teammate for large parallel tasks)");
+            const icon = { active: chalk.yellow("●"), idle: chalk.cyan("◐"), done: chalk.green("✓"), failed: chalk.red("✗") };
+            return (chalk.dim("agent team this session:\n") +
+                team.map((t) => chalk.dim(`  ${icon[t.status] ?? "?"} ${t.name} [${t.status}, ${t.elapsed}s] — ${t.role.slice(0, 60)}${t.pending ? chalk.yellow(` · ${t.pending} unread`) : ""}`)).join("\n"));
+        }
+        case "/tasks": {
+            const summary = boardSummary();
+            return summary === "(the task board is empty)" ? chalk.dim("(no tasks — the lead adds them with create_task; teammates claim them autonomously)") : chalk.dim(`task board:\n${summary}`);
+        }
+        case "/skills": {
+            if (!ctx.skills.length)
+                return chalk.dim("(no skills — add one at .mini-agent/skills/<name>/SKILL.md or ~/.config/mini-agent/skills/)");
+            return (chalk.dim("skills in this project:\n") +
+                ctx.skills.map((s) => chalk.dim(`  ${s.name} [${s.disableModelInvocation ? chalk.yellow("user-only") : chalk.green("model+user")}${chalk.dim("]")} — ${(s.whenToUse || s.description).slice(0, 70)}`)).join("\n"));
+        }
+        case "/undo": {
+            const undone = undoLast();
+            if (!undone)
+                return chalk.dim("(nothing to undo — no file writes recorded this session)");
+            return chalk.dim(`↩ ${undone.summary}`) + "\n" + renderDiff(undone.after ?? "", undone.before ?? "");
+        }
+        case "/diff": {
+            const changes = sessionChanges();
+            if (!changes.length)
+                return chalk.dim("(no file changes this session)");
+            const verb = { created: chalk.green("created"), modified: chalk.yellow("modified"), deleted: chalk.red("deleted") };
+            const head = chalk.dim(`${changes.length} file${changes.length === 1 ? "" : "s"} changed this session:`);
+            return head + "\n" + changes.map((c) => `\n${verb[c.status]} ${path.relative(process.cwd(), c.path) || c.path}\n${renderDiff(c.baseline, c.current)}`).join("");
+        }
+        default:
+            return null; // not an info command — the App handles it (or it's a normal task line)
+    }
+}

package/dist/ink/launch.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { buildInkSession } from "./setup.js"; // the front-end-agnostic session bootstrap
+import { makeRunTurn } from "./chat.js"; // drives one turn through the real loop
+import { App } from "./app.js"; // the Ink REPL
+// Launch the Ink REPL and resolve when it exits. buildInkSession does the same
+// wiring agent.ts does (MCP, skills, judge, memory, cost, hooks, telemetry,
+// optional resume); App renders it and runs the loop. Exported so BOTH the
+// `npm run ink` entry (main.tsx) and agent.ts (the default `mini-agent` entry,
+// once it hands interactive sessions to Ink) can start it.
+export async function launchInk(opts = {}) {
+    const session = await buildInkSession({ resume: opts.resume });
+    const { waitUntilExit } = render(_jsx(App, { session: session, runTurn: makeRunTurn(session.client, session.messages) }));
+    await waitUntilExit(); // keep the process alive until the user quits
+}

package/dist/ink/main.js

@@ -0,0 +1,4 @@
+import { launchInk } from "./launch.js"; // the reusable launcher (shared with agent.ts)
+// Direct entry for the Ink REPL: npm run ink. agent.ts launches the same thing
+// for a normal `mini-agent` interactive session.
+await launchInk({ resume: process.argv.includes("-r") || process.argv.includes("--resume") });

package/dist/ink/setup.js

@@ -0,0 +1,102 @@
+import OpenAI from "openai";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { CONFIG, requireApiKey } from "../config.js";
+import { buildSystemMessage } from "../prompt.js";
+import { estimateHistoryTokens } from "../context.js";
+import { initCostMeter, DEFAULT_PRICING } from "../cost.js";
+import { gitBranch } from "../tui.js";
+import { newSessionId, latestSession } from "../session.js";
+import { initTelemetry, emit } from "../telemetry.js";
+import { runHooks } from "../hooks.js";
+import { connectMcpServers } from "../mcp.js";
+import { Judge } from "../judge.js";
+import { registerExternalTool } from "../tools.js";
+import { rememberTool, readMemory } from "../memory.js";
+import { loadSkills, buildSkillTool } from "../skills.js";
+import { killAllBackground } from "../background.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
+// readline/editLine, just the shared modules (MCP, skills, judge, memory, cost,
+// hooks, telemetry, session). It returns everything the Ink App needs to run a
+// real session, so main.tsx stays a thin render() call. (agent.ts is left
+// untouched so `npm start` keeps working until 2d flips the default.)
+const pkg = createRequire(import.meta.url)("../../package.json");
+// Build the session. `resume` mirrors `-r/--resume`: fold the most recent
+// conversation in this directory into the fresh constitution.
+export async function buildInkSession(opts = {}) {
+    requireApiKey();
+    const client = new OpenAI({ baseURL: CONFIG.baseURL, apiKey: CONFIG.apiKey, maxRetries: 0 });
+    const systemMessage = buildSystemMessage(); // stable prefix = cache hits every request
+    const messages = [{ role: "system", content: systemMessage }];
+    const notices = [];
+    let sessionId = newSessionId();
+    const startedAt = Date.now();
+    if (opts.resume) {
+        const prev = latestSession();
+        if (prev) {
+            messages.push(...prev.messages);
+            sessionId = prev.id; // keep appending to the same file
+            notices.push(`(resumed session ${prev.id} — ${prev.messages.length} messages; files must be re-read before editing)`);
+        }
+        else {
+            notices.push("(no previous session here — starting fresh)");
+        }
+    }
+    initTelemetry(sessionId);
+    emit("agent_session_start", { mode: "repl" });
+    // MCP servers — must finish before the first model call so their tools appear
+    // in the manual. A server that fails to start is skipped, never fatal.
+    const disconnectMcp = await connectMcpServers();
+    process.on("exit", disconnectMcp);
+    process.on("exit", killAllBackground); // SIGKILL any background job so it never outlives the agent
+    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})`);
+    // The remember tool flows through the same permission gate as any tool.
+    registerExternalTool(rememberTool);
+    const memCount = readMemory().length;
+    if (memCount)
+        notices.push(`(long-term memory: ${memCount} facts loaded)`);
+    // Skills: model-invocable ones get the single `skill` tool; user-only ones are
+    // reachable via /skill <name>.
+    const skills = loadSkills();
+    if (skills.some((s) => !s.disableModelInvocation))
+        registerExternalTool(buildSkillTool(skills));
+    if (skills.length)
+        notices.push(`(skills: ${skills.length} loaded — ${skills.map((s) => s.name).join(", ")})`);
+    const costMeter = initCostMeter({
+        inputPerM: CONFIG.pricing.inputPerM ?? DEFAULT_PRICING.inputPerM,
+        cachedInputPerM: CONFIG.pricing.cachedInputPerM ?? DEFAULT_PRICING.cachedInputPerM,
+        outputPerM: CONFIG.pricing.outputPerM ?? DEFAULT_PRICING.outputPerM,
+    });
+    // SessionStart hooks run once; their stdout becomes context on the first turn.
+    const sessionStart = await runHooks("SessionStart", {});
+    if (sessionStart.stdout)
+        messages.push({ role: "user", content: `[SessionStart hook]\n${sessionStart.stdout}` });
+    const dir = path.basename(process.cwd());
+    const branch = gitBranch();
+    const getStatus = () => ({
+        ctxPct: Math.min(100, Math.round((estimateHistoryTokens(messages) / CONFIG.contextWindow) * 100)),
+        cost: costMeter.cost(),
+        elapsedMs: Date.now() - startedAt,
+    });
+    return {
+        client,
+        messages,
+        systemMessage,
+        initialSessionId: sessionId,
+        startedAt,
+        costMeter,
+        skills,
+        judge,
+        model: CONFIG.model,
+        dir,
+        branch,
+        bannerText: banner(pkg.version, CONFIG.model, new URL(CONFIG.baseURL).host),
+        notices,
+        getStatus,
+        disconnectMcp,
+    };
+}

package/dist/ink/sink.js

@@ -0,0 +1,50 @@
+// Build a LoopOutput backed by Ink state. Pure glue: every method maps a loop
+// event to a state change.
+export function makeInkSink(api) {
+    return {
+        // A spinner becomes the single "status" line below the conversation. A fresh
+        // handle per model call (the loop makes one per round); `active` mirrors
+        // ora's isSpinning so the loop's `spinner?.spinning` checks behave the same.
+        spinner(text) {
+            api.setStatus(text);
+            let active = true;
+            return {
+                set: (t) => {
+                    if (active)
+                        api.setStatus(t);
+                },
+                stop: () => {
+                    if (active) {
+                        active = false;
+                        api.setStatus(null);
+                    }
+                },
+                get spinning() {
+                    return active;
+                },
+            };
+        },
+        // The "💭 thought for Ns" indicator is just a committed line.
+        reasoning: (line) => api.pushItem({ kind: "note", text: line }),
+        // The streamed answer accumulates in the dynamic region as raw text (live,
+        // "it's typing"), then commits as ONE markdown-rendered item when it ends —
+        // partial markdown mid-stream renders badly, so we format only once it's whole.
+        answer() {
+            let buf = "";
+            api.setLive("");
+            return {
+                push: (tok) => {
+                    buf += tok;
+                    api.setLive(buf);
+                },
+                end: () => {
+                    api.setLive(null); // clear the live preview first, then commit (no flicker/duplicate)
+                    if (buf.trim())
+                        api.pushItem({ kind: "answer", text: buf });
+                },
+            };
+        },
+        // Generic narration — already chalk-formatted by the loop; just commit it.
+        note: (line) => api.pushItem({ kind: "note", text: line }),
+    };
+}

package/dist/loop.js

@@ -1,5 +1,4 @@
 import chalk from "chalk"; // terminal colors for status lines
-import ora from "ora"; // the "thinking..." spinner while waiting for the first token
 import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
@@ -13,7 +12,7 @@ import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / Pos
 import { recordUsage } from "./cost.js"; // meter token usage from the stream
 import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
 import { recordToolCall, recordReasoning } from "./tui.js"; // folded tool-call trace (Ctrl+T) + the model's hidden thinking (Ctrl+R)
-import { MarkdownStream } from "./markdown.js"; // render the streamed answer as terminal markdown
+import { STDOUT_OUTPUT } from "./output.js"; // where the loop's screen output goes (stdout by default, Ink REPL passes its own)
 import { todoNag, getTodos, renderTodos } from "./todos.js"; // the agent's plan: show it on screen + nag when it goes stale
 import { pendingNotifications } from "./background.js"; // background tasks (Day 37): surface finished jobs as a turn
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
@@ -36,6 +35,11 @@ export var TerminateReason;
     TerminateReason["FatalApiError"] = "fatal_api_error";
     TerminateReason["UserInterrupt"] = "user_interrupt";
 })(TerminateReason || (TerminateReason = {}));
+// Resolve the output sink for a loop: the caller's sink, or stdout (the old
+// behaviour) when none was passed. Centralised so every site reads the same way.
+function sink(opts) {
+    return opts.output ?? STDOUT_OUTPUT;
+}
 // Which model should a delegated sub-agent run on? The configured sub-agent
 // model if set and non-blank, otherwise the same model as the orchestrator.
 // Pulled out as a pure function so the tiering rule is testable on its own.
@@ -281,7 +285,7 @@ async function runSubAgent(description, opts) {
     // 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.
     if (!opts.quiet)
-        console.log(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
+        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)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
     try {
@@ -301,7 +305,7 @@ async function runSubAgent(description, opts) {
         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)
-            console.log(mark.subAgentDone); // close the bracket
+            sink(opts).note(mark.subAgentDone); // close the bracket
     }
 }
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
@@ -335,7 +339,7 @@ opts) {
     let reasoningShown = false; // have we printed the "thought for Ns" indicator yet?
     const spinner = opts.quiet
         ? null // the eval harness wants silence
-        : ora({ text: spinnerText(word, 0, !!opts.subAgent, opts.model), discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+        : sink(opts).spinner(spinnerText(word, 0, !!opts.subAgent, opts.model)); // a fresh spinner from the sink (stdout → ora; Ink → React state)
     let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
     let stallWarned = false; // only warn once per quiet stretch
     // The two-level watchdog, checked once per second:
@@ -345,8 +349,8 @@ opts) {
     const watchdog = setInterval(() => {
         // While the model is reasoning, prefix the spinner with 💭 so "it's thinking"
         // reads differently from "it's waiting on the first token".
-        if (spinner?.isSpinning)
-            spinner.text = (reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4));
+        if (spinner?.spinning)
+            spinner.set((reasoningActive ? chalk.dim("💭 ") : "") + spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4)));
         const quietMs = Date.now() - lastEvent; // ms since the last event
         if (quietMs > IDLE_TIMEOUT_MS) {
             emit("agent_watchdog_idle"); // record the cut — these should be rare
@@ -355,7 +359,7 @@ opts) {
         else if (quietMs > STALL_WARN_MS && !stallWarned) {
             stallWarned = true; // don't repeat the warning every second
             emit("agent_watchdog_stall"); // record the slowness — pattern-spotting data
-            console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
+            sink(opts).note(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
         }
     }, 1000);
     try {
@@ -370,8 +374,7 @@ opts) {
         // teammate's manual simply omits spawn_teammate and task.
         { model: opts.model, messages, tools: toolsFor(opts), stream: true, stream_options: { include_usage: true } }, { signal });
         let content = ""; // accumulated answer text
-        let printedPrefix = false; // have we printed the answer prefix yet?
-        let md = null; // renders the streamed answer as markdown, block by block
+        let ans = null; // renders the streamed answer (stdout: markdown block by block; Ink: React state) — non-null once the answer starts
         const calls = []; // tool calls under assembly, indexed by delta.index
         // The model has finished thinking and is about to say/do something. Close out
         // the spinner, stash the trace, and print a single one-line indicator with the
@@ -382,7 +385,7 @@ opts) {
                 return;
             reasoningShown = true;
             reasoningActive = false;
-            if (spinner?.isSpinning)
+            if (spinner?.spinning)
                 spinner.stop();
             if (opts.quiet || opts.subAgent)
                 return; // no UI for silent / nested runs
@@ -390,7 +393,7 @@ opts) {
             const secs = Math.round((Date.now() - startedAt) / 1000);
             const toks = Math.round(reasoningBuf.length / 4); // same ~chars/4 estimate as the spinner
             const tokStr = toks >= 1000 ? `${(toks / 1000).toFixed(1)}k` : `${toks}`;
-            process.stdout.write(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`) + "\n");
+            sink(opts).reasoning(chalk.dim(`💭 thought for ${secs}s (~${tokStr} tokens) · Ctrl+R to view`));
         };
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
@@ -414,27 +417,24 @@ opts) {
             if (delta.content) {
                 flushReasoning(); // thinking is over — show the one-line indicator first
                 streamedChars += delta.content.length; // count the answer toward the live token estimate
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // first token: replace the spinner with real output
                 if (!opts.quiet && !opts.subAgent) {
                     // Only the top-level agent streams to the screen — a sub-agent's
-                    // inner monologue would be mistaken for the answer.
-                    if (!printedPrefix) {
-                        // Stream the answer through the markdown renderer: it buffers a block
-                        // (paragraph / heading / list / table) and prints it formatted the
-                        // moment that block completes — still live, but no raw `##`/`|---|`.
-                        // The ⏺ marker leads the first line; wrapped lines align under it.
-                        md = new MarkdownStream((s) => process.stdout.write(s), { firstPrefix: "\n" + mark.answer, indent: "  " });
-                        printedPrefix = true;
-                    }
-                    md.push(delta.content); // hand the token to the renderer (it decides when to paint)
+                    // inner monologue would be mistaken for the answer. The sink decides
+                    // how to paint: the stdout sink buffers a markdown block (paragraph /
+                    // heading / list / table) and flushes it whole — live, but no raw
+                    // `##`/`|---|`; the Ink sink accumulates into React state.
+                    if (!ans)
+                        ans = sink(opts).answer(); // first token: start the answer renderer
+                    ans.push(delta.content); // hand the token to the renderer (it decides when to paint)
                 }
                 content += delta.content; // always keep it for the history (the answer only, never the reasoning)
             }
             if (delta.tool_calls?.length)
                 flushReasoning(); // thinking is over — indicator before the tool logs (which print after we return)
             for (const tc of delta.tool_calls ?? []) {
-                if (spinner?.isSpinning)
+                if (spinner?.spinning)
                     spinner.stop(); // tool call starting — spinner served its purpose
                 const slot = (calls[tc.index] ??= { id: "", name: "", args: "" }); // create the slot on first fragment
                 if (tc.id)
@@ -446,15 +446,13 @@ opts) {
             }
         }
         flushReasoning(); // a reasoning-only turn (no content, no tools) still records + indicates
-        if (md)
-            md.end(); // flush the final (un-terminated) block through the renderer
-        if (printedPrefix)
-            process.stdout.write("\n"); // end the streamed line cleanly
+        if (ans)
+            ans.end(); // flush the final (un-terminated) block + end the line cleanly (the sink owns the trailing newline)
         return { content, toolCalls: calls.filter(Boolean) }; // sparse array → dense
     }
     finally {
         clearInterval(watchdog); // always stop the timer
-        if (spinner?.isSpinning)
+        if (spinner?.spinning)
             spinner.stop(); // and never leave a zombie spinner
     }
 }
@@ -487,13 +485,13 @@ async function runOneCall(call, opts) {
     if (!opts.quiet && v.decision !== "deny" && (call.name === "write_file" || call.name === "edit_file")) {
         const preview = previewChange(call.name, call.args);
         if (preview)
-            console.log(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
+            sink(opts).note(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
     }
     let content; // what goes back to the model as the tool result
     if (v.decision === "deny") {
         emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
         if (!opts.quiet)
-            console.log(mark.denied(v.reason)); // tell the user we blocked it
+            sink(opts).note(mark.denied(v.reason)); // tell the user we blocked it
         content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
     }
     else if (v.decision === "ask") {
@@ -510,14 +508,14 @@ async function runOneCall(call, opts) {
             if (cmd && (await opts.judge.classify(cmd)) === "allow") {
                 autoAllowed = true;
                 if (!opts.quiet)
-                    console.log(mark.judge); // visible — the user can see the judge worked
+                    sink(opts).note(mark.judge); // visible — the user can see the judge worked
             }
         }
         const ok = autoAllowed || (await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`, call.name)); // judge-allowed, or pause and ask the human
         if (!ok)
             emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
         if (!ok && !opts.quiet)
-            console.log(mark.declined); // make the refusal visible
+            sink(opts).note(mark.declined); // make the refusal visible
         content = ok
             ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
             : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
@@ -528,7 +526,7 @@ async function runOneCall(call, opts) {
     // todo_write's whole point is the VISIBLE plan: the model got a one-line tally,
     // the human gets the rendered checklist (quiet runs — eval/sub-agents — stay silent).
     if (call.name === "todo_write" && !opts.quiet && !content.startsWith("[error]")) {
-        console.log(renderTodos(getTodos()));
+        sink(opts).note(renderTodos(getTodos()));
     }
     return { id: call.id, content }; // paired by id for the API
 }
@@ -546,7 +544,7 @@ async function runWithHooks(call, opts) {
     if (pre.block) {
         emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
         if (!opts.quiet)
-            console.log(mark.hookBlock("PreToolUse")); // make it visible
+            sink(opts).note(mark.hookBlock("PreToolUse")); // make it visible
         return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
     }
     // A PreToolUse hook may REWRITE the arguments (e.g. add a commit trailer). The
@@ -556,7 +554,7 @@ async function runWithHooks(call, opts) {
         try {
             JSON.parse(pre.rewrite); // must be valid JSON args
             if (!opts.quiet)
-                console.log(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
+                sink(opts).note(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
             call = { ...call, args: pre.rewrite };
         }
         catch {
@@ -744,7 +742,7 @@ async function runCreateTask(call, opts) {
         return "[error] create_task needs a 'subject'.";
     const task = createTask(subject, description, blockedBy);
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} created ${task.id}: ${subject.slice(0, 50)}`));
+        sink(opts).note(chalk.magenta(`  ⎿ ${boardActor(opts)} created ${task.id}: ${subject.slice(0, 50)}`));
     return `Created ${task.id}: "${subject}"${blockedBy.length ? ` (blockedBy: ${blockedBy.join(", ")})` : ""}. It's on the board for a teammate to claim.`;
 }
 async function runListTasks(_call, opts) {
@@ -781,7 +779,7 @@ async function runCompleteTask(call, opts) {
     if (!res.ok)
         return `[error] ${res.error}`;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
+        sink(opts).note(chalk.magenta(`  ⎿ ${boardActor(opts)} completed ${taskId}`));
     const unblocked = res.unblocked?.length ? ` Unblocked: ${res.unblocked.join(", ")}.` : "";
     return `Completed ${taskId}.${unblocked} Claim the next ready task, or idle until the lead shuts you down.`;
 }
@@ -817,7 +815,7 @@ async function runSpawnTeammate(call, opts) {
     const done = runTeammate(name, role, task, opts);
     registerTeammate(name, role, done);
     if (!opts.quiet)
-        console.log(mark.teammateStart(name, role));
+        sink(opts).note(mark.teammateStart(name, role));
     return `Teammate "${name}" (${role}) spawned and is now working in parallel. It will message you (as "lead") with progress and its final result. Reply with send_message; keep coordinating the rest of the team. Do not wait idly — continue your own work.`;
 }
 // Run one teammate to completion: a fresh conversation seeded with its task, a
@@ -847,7 +845,7 @@ async function runTeammate(name, role, task, opts) {
             subAgent: true,
             teammate: { name },
             maxRounds: TEAMMATE_MAX_ROUNDS,
-            confirm: teammateConfirm(name),
+            confirm: teammateConfirm(name, sink(opts)),
             askUser: undefined, // teammates have no line to the human
         });
         // How it ended decides what the lead hears. A shutdown handshake gets a
@@ -861,7 +859,7 @@ async function runTeammate(name, role, task, opts) {
             sendMessage(name, LEAD, summary, "result");
         finishTeammate(name, result.reason === TerminateReason.Done);
         if (!opts.quiet)
-            console.log(mark.teammateDone(name, result.reason === TerminateReason.Done));
+            sink(opts).note(mark.teammateDone(name, result.reason === TerminateReason.Done));
     }
     catch (err) {
         // A teammate must never take the whole process down. Report the failure to
@@ -885,11 +883,11 @@ const SHUTDOWN_GRACE_MS = 30_000; // how long the lead waits for teammates to ex
 // DENY rules (the no-fly zone) are enforced by the gate before confirm is ever
 // called, so they always hold. Production Claude Code instead "bubbles" the
 // request up to the lead and on to the human — omitted here, like the reference.
-function teammateConfirm(name) {
+function teammateConfirm(name, output) {
     return async (_question, toolName) => {
         const ok = toolName === "write_file" || toolName === "edit_file";
         if (!ok)
-            console.log(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
+            output.note(chalk.yellow(`  ⎿ [${name}] declined ${toolName ?? "an action"} (teammates can't prompt you; do it yourself or allowlist it)`));
         return ok;
     };
 }
@@ -925,7 +923,7 @@ compaction) {
     try {
         if (!opts.subAgent)
             await runHooks("PreCompact", {}); // lifecycle hook (top-level only; hooks are the human's project policy)
-        await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
+        await compactHistory(messages, opts.client, opts.model, opts.signal, (s) => sink(opts).note(s)); // do the actual work — narration through the sink (so it doesn't corrupt an Ink live region)
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
         emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
@@ -956,7 +954,7 @@ function injectBackgroundNotifications(messages, opts) {
     const count = (note.match(/<task_notification>/g) ?? []).length; // for the one-line on-screen mark
     messages.push({ role: "user", content: note }); // the model reacts to it on the next round
     if (!opts.quiet)
-        console.log(mark.bgNote(count));
+        sink(opts).note(mark.bgNote(count));
     return true;
 }
 // Consume this agent's mailbox into its conversation, ROUTING protocol messages
@@ -1005,7 +1003,7 @@ function consumeInbox(messages, opts) {
     const header = opts.teammate ? "Messages from your team — read and act on them:" : "Team inbox — react to these (RESULT = that teammate finished a part):";
     messages.push({ role: "user", content: `${header}\n\n${lines.join("\n\n")}` });
     if (!opts.quiet)
-        console.log(opts.teammate ? chalk.dim(`  ⎿ [${me}] received ${msgs.length} message(s)`) : mark.inbox(msgs.length));
+        sink(opts).note(opts.teammate ? chalk.dim(`  ⎿ [${me}] received ${msgs.length} message(s)`) : mark.inbox(msgs.length));
     return true;
 }
 // At a stop-point (no tool calls), decide whether the TEAM keeps this agent's
@@ -1041,7 +1039,7 @@ async function continueForTeam(messages, opts) {
                 // reference's identity-reinjection, folded into the work hand-off).
                 messages.push({ role: "user", content: `You are ${me}. You claimed task ${claimed.id} from the board: "${claimed.subject}".\n${claimed.description}\nWhen it is done and verified, call complete_task("${claimed.id}") — then you'll be offered the next ready task.` });
                 if (!opts.quiet)
-                    console.log(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
+                    sink(opts).note(chalk.magenta(`  ⎿ [${me}] claimed ${claimed.id}: ${claimed.subject.slice(0, 50)}`));
                 setTeammateState(me, "active");
                 return true;
             }
@@ -1069,7 +1067,7 @@ async function shutdownTeam(opts) {
     if (!running.length)
         return;
     if (!opts.quiet)
-        console.log(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
+        sink(opts).note(chalk.magenta(`  ⎿ disbanding team — shutting down ${running.length} teammate(s)`));
     for (const name of running) {
         const id = createRequest("shutdown", LEAD, name, "task complete");
         markShutdown(name, id);
@@ -1152,7 +1150,7 @@ opts) {
                 if (attempts.total >= MAX_RETRIES)
                     return { reason: TerminateReason.RetryBudgetExhausted, detail: `${e.kind}: ${e.message}` };
                 const wait = backoffMs(attempts.consecutive); // how long to back off this time
-                console.log(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
+                sink(opts).note(chalk.dim(`  [retry] ${e.kind} — attempt ${attempts.total}/${MAX_RETRIES}, waiting ${wait}ms`)); // retries must be visible, or the app just looks frozen
                 await interruptibleSleep(wait, opts.isInterrupted); // wait, but stay responsive to Ctrl+C
                 continue; // retry the same round
             }
@@ -1187,7 +1185,7 @@ opts) {
                     if (stop.block) {
                         emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
                         if (!opts.quiet)
-                            console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
+                            sink(opts).note(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
                         messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
                         break; // exit the inner while → advance the round counter
                     }
@@ -1235,7 +1233,7 @@ opts) {
             // Fold this round's tool calls into ONE tally line instead of one line per
             // call (the per-call announcements were recorded for Ctrl+T in runOneCall).
             if (!opts.quiet && out.toolCalls.length) {
-                console.log(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
+                sink(opts).note(agentIndent(opts) + mark.toolTally(out.toolCalls.map((c) => c.name)) + chalk.dim(" · Ctrl+T"));
             }
             // Background tasks (Day 37): if a job the model started has finished, slip
             // its <task_notification> in here, right after this round's tool results —
@@ -1255,7 +1253,7 @@ opts) {
                 if (nag) {
                     messages.push({ role: "user", content: nag });
                     if (!opts.quiet)
-                        console.log(chalk.dim("  ⎿ plan reminder injected"));
+                        sink(opts).note(chalk.dim("  ⎿ plan reminder injected"));
                 }
             }
             break; // round complete, move to the next one

package/dist/output.js

@@ -0,0 +1,50 @@
+import ora from "ora"; // the "thinking…" spinner the default sink drives
+import { MarkdownStream } from "./markdown.js"; // the default sink renders the streamed answer as terminal markdown
+import { mark } from "./ui.js"; // the ⏺ answer marker, kept consistent with the rest of the UI
+// ---- the default sink: stdout, identical to the pre-sink behaviour -----------
+class StdoutSpinner {
+    s;
+    constructor(text) {
+        // discardStdin:false — ora would otherwise swallow Ctrl+C while spinning.
+        this.s = ora({ text, discardStdin: false }).start();
+    }
+    set(text) {
+        if (this.s.isSpinning)
+            this.s.text = text;
+    }
+    stop() {
+        if (this.s.isSpinning)
+            this.s.stop();
+    }
+    get spinning() {
+        return this.s.isSpinning;
+    }
+}
+// The sink the readline REPL (and every non-Ink caller) gets when it passes no
+// `output`. Each method is the exact line the loop used to run inline.
+export const STDOUT_OUTPUT = {
+    spinner: (text) => new StdoutSpinner(text),
+    reasoning: (line) => process.stdout.write(line + "\n"),
+    answer: () => {
+        // Lazily build the MarkdownStream on the first token (so a tool-only or
+        // empty turn prints nothing), then end with a single trailing newline —
+        // exactly the old `if (printedPrefix) process.stdout.write("\n")`.
+        let md = null;
+        let printed = false;
+        return {
+            push(token) {
+                if (!md)
+                    md = new MarkdownStream((s) => process.stdout.write(s), { firstPrefix: "\n" + mark.answer, indent: "  " });
+                printed = true;
+                md.push(token);
+            },
+            end() {
+                if (md)
+                    md.end();
+                if (printed)
+                    process.stdout.write("\n");
+            },
+        };
+    },
+    note: (line) => console.log(line),
+};

package/dist/tui.js

@@ -107,6 +107,18 @@ export function revealToolCalls() {
     process.stdout.write(toolCallLog.join("\n") + "\n");
     return true;
 }
+// Ink variants of the two reveals: RETURN the formatted block (or null) instead
+// of writing to stdout, so the Ink REPL can commit it as a note in its tree.
+export function getReasoning() {
+    if (!reasoningTrace.length)
+        return null;
+    return chalk.dim("💭 model's thinking:\n") + chalk.dim(reasoningTrace.join("\n\n— — —\n\n").replace(/^/gm, "  "));
+}
+export function getToolCalls() {
+    if (!toolCallLog.length)
+        return null;
+    return chalk.dim(`tool calls this turn (${toolCallLog.length}):\n`) + toolCallLog.join("\n");
+}
 // ---- 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

package/dist/ui.js

@@ -1,4 +1,5 @@
 import chalk from "chalk"; // the one place color lives
+import { displayWidth } from "./editor.js"; // CJK-/ANSI-aware width, to pad the sent-message bar to the full row
 // The app's visual theme, in one place. Before this, emoji and colors were
 // sprinkled across agent.ts and loop.ts — no coherent look, and impossible to
 // restyle without hunting. This module owns "what the tool looks like": the
@@ -124,11 +125,18 @@ export function inputRule() {
 export function framedPrompt(planMode) {
     return planMode ? chalk.yellow.bold("⏸ plan ❯ ") : chalk.cyan.bold("❯ ");
 }
-// How a SUBMITTED message is echoed into the scrollback once you hit Enter: a
-// distinct, muted "> …" line (not the bright ❯ prompt) so each turn reads like a
-// sent chat message scrolling up, leaving the input box empty below.
+// How a SUBMITTED message is echoed into the scrollback once you hit Enter:
+// a "> …" line on a full-width highlight BAR (like Claude Code), so each turn
+// reads as a distinct sent message scrolling up — not just faint text. The line
+// is padded to the terminal width so the background spans the whole row; if the
+// message is longer than the row it just wraps (the tail line won't be padded,
+// a minor cosmetic). Colors fall back gracefully when the terminal lacks 256.
 export function sentMessage(text) {
-    return chalk.dim("> " + text);
+    const cols = Math.max(20, process.stdout.columns || 80);
+    const content = "> " + text;
+    const w = displayWidth(content);
+    const padded = w < cols ? content + " ".repeat(cols - w) : content; // fill the row when it fits
+    return chalk.bgAnsi256(237).ansi256(252)(padded); // light-grey text on a subtle dark-grey bar
 }
 // ---- the selection menu -----------------------------------------------------
 // Render a numbered list of options with one highlighted. The interactive part

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Build a Claude Code-style CLI agent from scratch, with AI as your pair programmer — companion code for a 10-day tutorial (DeepSeek by default, any OpenAI-compatible model)",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "start": "tsx --env-file=.env src/agent.ts",
+    "ink": "tsx --env-file=.env src/ink/main.tsx",
     "typecheck": "tsc --noEmit",
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
@@ -25,14 +26,17 @@
   "dependencies": {
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
+    "ink": "^5.2.1",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
     "openai": "^6.42.0",
     "ora": "^9.4.0",
+    "react": "^18.3.1",
     "wrap-ansi": "^10.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
+    "@types/react": "^18.3.31",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
   }