agent-from-zero 0.27.0 → 0.29.0

package/dist/board.js

@@ -0,0 +1,179 @@
+// ============ The shared task board (Day 40) ============
+// Day 38/39 gave us a team, but the LEAD still had to hand every teammate its
+// work by message. That doesn't scale: with twenty tasks the lead becomes a
+// dispatcher, and a teammate that finishes early sits idle while the lead is
+// busy. s17's fix: a shared TASK BOARD that agents pull from THEMSELVES. The
+// lead (or a teammate) drops tasks on the board; any idle teammate scans it,
+// CLAIMS a ready one, does it, marks it complete, and scans again — autonomous
+// work distribution with no dispatcher in the middle.
+//
+// Like the mailboxes, the board is ON DISK (落盘) for observability: each task is
+// a .mini-agent/tasks/<id>.json file you can read while the team runs. And like
+// the mailboxes, it needs NO lock despite "concurrent" claimers: claimTask is a
+// synchronous read-check-write, and on one event loop a synchronous function
+// runs to completion without yielding — so two teammates can never both win the
+// same task. (The Python reference uses proper-lockfile because its teammates are
+// OS threads; production CC adds fs.watch + atomic claim-with-busy-check.)
+//
+// Not to be confused with todo_write (Day 36): that is one agent's PRIVATE
+// checklist; this is the team's SHARED, claimable work queue.
+import fs from "node:fs"; // tasks are real files
+import path from "node:path"; // path joining
+let seq = 0; // increments per task — seeds the id
+let wiped = false; // wipe stale board files once per process run (like team.ts)
+// Resolved lazily so it tracks the cwd, exactly like the session + team dirs.
+function boardRoot() {
+    const root = path.resolve(".mini-agent", "tasks");
+    fs.mkdirSync(root, { recursive: true });
+    if (!wiped) {
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".json"))
+                fs.rmSync(path.join(root, f)); // fresh board for this run
+        wiped = true;
+    }
+    return root;
+}
+const taskPath = (id) => path.join(boardRoot(), `${id}.json`);
+function saveTask(task) {
+    fs.writeFileSync(taskPath(task.id), JSON.stringify(task, null, 2)); // pretty, so `cat` is readable
+}
+export function getTask(id) {
+    try {
+        return JSON.parse(fs.readFileSync(taskPath(id), "utf8"));
+    }
+    catch {
+        return undefined; // missing or corrupt
+    }
+}
+// Every task on the board, oldest first (creation order = the natural reading
+// order for a dependency graph).
+export function listTasks() {
+    const root = boardRoot();
+    return fs
+        .readdirSync(root)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(root, f), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((t) => t !== null)
+        .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+// Create a task. `blockedBy` may reference ids that don't exist yet — canStart
+// treats an unknown dependency as "not satisfied", so order of creation is free.
+export function createTask(subject, description = "", blockedBy = []) {
+    const task = { id: `task_${++seq}`, subject, description, status: "pending", owner: null, blockedBy, createdAt: Date.now() };
+    saveTask(task);
+    return task;
+}
+// Resolve a blockedBy entry to a task. Models naturally reference a dependency
+// by its SUBJECT ("alpha") rather than its id ("task_1"), so we accept either —
+// id first, then a unique subject match. Returns undefined if it matches nothing
+// (or an ambiguous subject), which canStart then treats as still-blocking.
+export function resolveDep(dep) {
+    const byId = getTask(dep);
+    if (byId)
+        return byId;
+    const bySubject = listTasks().filter((t) => t.subject === dep);
+    return bySubject.length === 1 ? bySubject[0] : undefined; // ignore an ambiguous subject
+}
+// Can this task be started? Only if every blockedBy dependency resolves to a
+// COMPLETED task. A missing/ambiguous dependency counts as blocking (fail closed).
+export function canStart(id) {
+    const task = getTask(id);
+    if (!task)
+        return false;
+    return task.blockedBy.every((dep) => resolveDep(dep)?.status === "completed");
+}
+// Claim a task for `owner`. The critical section: read, check it's still
+// pending+unowned+ready, then write owner+in_progress — all synchronous, so it
+// is atomic against any other agent on this event loop. Returns ok=false (with a
+// reason) if someone else got there first or a dependency isn't done.
+export function claimTask(id, owner) {
+    const task = getTask(id);
+    if (!task)
+        return { ok: false, error: `No task "${id}".` };
+    if (task.status !== "pending")
+        return { ok: false, error: `Task ${id} is ${task.status}${task.owner ? ` (owner ${task.owner})` : ""}, not claimable.` };
+    if (task.owner)
+        return { ok: false, error: `Task ${id} is already owned by ${task.owner}.` };
+    if (!canStart(id))
+        return { ok: false, error: `Task ${id} is blocked by unfinished tasks: ${task.blockedBy.filter((d) => resolveDep(d)?.status !== "completed").join(", ")}.` };
+    task.owner = owner;
+    task.status = "in_progress";
+    saveTask(task);
+    return { ok: true, task };
+}
+// Complete a task and report which downstream tasks it just unblocked (so the
+// claimer can mention them, and the board moves forward).
+export function completeTask(id, by) {
+    const task = getTask(id);
+    if (!task)
+        return { ok: false, error: `No task "${id}".` };
+    if (task.status !== "in_progress")
+        return { ok: false, error: `Task ${id} is ${task.status}, not in progress.` };
+    if (by && task.owner && task.owner !== by)
+        return { ok: false, error: `Task ${id} is owned by ${task.owner}, not ${by}.` };
+    task.status = "completed";
+    saveTask(task);
+    // Tasks that listed this one as a dependency (by id or subject) and are now
+    // ready just opened up.
+    const unblocked = listTasks()
+        .filter((t) => t.status === "pending" && !t.owner && t.blockedBy.some((d) => resolveDep(d)?.id === id) && canStart(t.id))
+        .map((t) => t.id);
+    return { ok: true, unblocked };
+}
+// Scan for the next task this agent can take and CLAIM it, atomically. Returns
+// the claimed task, or null if nothing is available right now. This is the heart
+// of autonomy: an idle teammate calls this and either gets work or keeps waiting.
+// Trying each candidate (rather than just the first) closes the race where two
+// agents scanned the same "available" task — the loser simply tries the next.
+export function claimNextAvailable(owner) {
+    for (const t of listTasks()) {
+        if (t.status !== "pending" || t.owner || !canStart(t.id))
+            continue;
+        const res = claimTask(t.id, owner);
+        if (res.ok)
+            return res.task;
+    }
+    return null;
+}
+// Is there pending-and-ready work nobody has claimed? Used to tell "the board is
+// genuinely drained" from "a teammate is briefly between tasks".
+export function hasClaimableWork() {
+    return listTasks().some((t) => t.status === "pending" && !t.owner && canStart(t.id));
+}
+// Any task not yet completed — the board still has open work (claimed or not).
+export function hasOpenTasks() {
+    return listTasks().some((t) => t.status !== "completed");
+}
+// A compact, human-readable board snapshot — for the list_tasks tool result and
+// the /tasks command. One line per task: status, id, owner, deps.
+export function boardSummary() {
+    const tasks = listTasks();
+    if (!tasks.length)
+        return "(the task board is empty)";
+    const icon = { pending: "○", in_progress: "◐", completed: "✓" };
+    return tasks
+        .map((t) => {
+        const owner = t.owner ? ` @${t.owner}` : "";
+        const deps = t.blockedBy.length ? ` (blockedBy: ${t.blockedBy.join(", ")})` : "";
+        return `${icon[t.status]} ${t.id} [${t.status}${owner}] ${t.subject}${deps}`;
+    })
+        .join("\n");
+}
+// Wipe the board: delete every task file and reset the counter. Called on
+// /clear, /resume, and when the lead disbands the team — each task starts fresh.
+export function resetBoard() {
+    const root = path.resolve(".mini-agent", "tasks");
+    if (fs.existsSync(root))
+        for (const f of fs.readdirSync(root))
+            if (f.endsWith(".json"))
+                fs.rmSync(path.join(root, f));
+    seq = 0;
+    wiped = true; // we just cleared it; don't re-wipe on the next touch this run
+}

package/dist/drop.js

@@ -0,0 +1,104 @@
+// Drag-and-drop a file onto the terminal and it pastes the file's path into the
+// input — but as a SHELL token: backslash-escaped spaces (/Users/me/my\ file.txt)
+// or wrapped in quotes, and usually with a trailing space. That's noisy to read
+// and clumsy to hand to the agent. This turns a dropped path (or several) into
+// clean ABSOLUTE paths, so the user never types a long path by hand.
+//
+// It is deliberately conservative: it only rewrites text that is, after
+// unescaping, one or more EXISTING ABSOLUTE paths (that's exactly what a terminal
+// drag produces). Anything else — ordinary pasted prose, a relative snippet — is
+// returned untouched, so this can run on every paste without surprising anyone.
+import fs from "node:fs"; // confirm the tokens are real paths (the drag signal)
+import os from "node:os"; // expand a leading ~
+import path from "node:path"; // resolve + normalize to absolute
+// Terminals with "bracketed paste" wrap the text in these markers; strip them so
+// a drop still parses if the mode happens to be on.
+const BRACKET_PASTE = /\x1b\[20[01]~/g;
+// Split a dropped string into path tokens, honoring the escaping a terminal adds:
+// backslash escapes (\<space>, \( …) and single/double quotes. Whitespace OUTSIDE
+// a quote/escape separates tokens (so several dropped files become several paths).
+function splitTokens(raw) {
+    const s = raw.replace(BRACKET_PASTE, "").trim();
+    const tokens = [];
+    let cur = "";
+    let started = false; // did the current token get any character? (distinguishes "" from absent)
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === "\\" && i + 1 < s.length) {
+            cur += s[i + 1];
+            i += 2;
+            started = true;
+            continue;
+        } // \x → literal x
+        if (c === "'") { // single quotes: everything literal until the next '
+            i++;
+            while (i < s.length && s[i] !== "'")
+                cur += s[i++];
+            i++;
+            started = true;
+            continue;
+        }
+        if (c === '"') { // double quotes: backslash still escapes inside
+            i++;
+            while (i < s.length && s[i] !== '"') {
+                if (s[i] === "\\" && i + 1 < s.length) {
+                    cur += s[i + 1];
+                    i += 2;
+                }
+                else
+                    cur += s[i++];
+            }
+            i++;
+            started = true;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\n" || c === "\r") { // a separator between tokens
+            if (started) {
+                tokens.push(cur);
+                cur = "";
+                started = false;
+            }
+            i++;
+            continue;
+        }
+        cur += c;
+        i++;
+        started = true;
+    }
+    if (started)
+        tokens.push(cur);
+    return tokens;
+}
+// A drop produces ABSOLUTE paths (macOS/Linux terminals). Treat a leading ~ as
+// home. Anything not absolute-ish is not a drop — we leave it alone.
+const looksAbsolute = (t) => t.startsWith("/") || t === "~" || t.startsWith("~/");
+const expandTilde = (t) => (t === "~" || t.startsWith("~/") ? os.homedir() + t.slice(1) : t);
+// Quote a path that contains whitespace so several dropped paths stay separable
+// (and the whole thing survives being read as shell-ish tokens later). Prefer
+// single quotes; fall back to double if the path itself contains a single quote.
+function quoteIfNeeded(p) {
+    if (!/\s/.test(p))
+        return p;
+    return p.includes("'") ? `"${p}"` : `'${p}'`;
+}
+// The entry point: given a pasted string, return clean absolute path(s) if it is
+// a drop, otherwise the original text unchanged. A successful normalization ends
+// with a single trailing space, so the cursor lands ready to type the question.
+export function normalizeDroppedPaths(raw) {
+    if (!raw)
+        return raw;
+    const tokens = splitTokens(raw);
+    if (!tokens.length)
+        return raw;
+    const abs = [];
+    for (const t of tokens) {
+        if (!looksAbsolute(t))
+            return raw; // not a dragged absolute path → leave the paste as-is
+        const resolved = path.resolve(expandTilde(t)); // normalize (//, .., trailing /) → canonical absolute
+        if (!fs.existsSync(resolved))
+            return raw; // a path that doesn't exist isn't a real drop
+        abs.push(resolved);
+    }
+    return abs.map(quoteIfNeeded).join(" ") + " ";
+}

package/dist/editor.js

@@ -0,0 +1,319 @@
+import readline from "node:readline"; // raw-mode keypress decoding + the interface we pause
+// ---- pure editing logic -----------------------------------------------------
+// Map a keypress onto a new state + an action. Emacs-style bindings, the ones a
+// terminal user expects. Everything printable (letters, digits, punctuation,
+// pasted text, CJK) falls through to insertion at the cursor.
+export function reduceEditor(s, str, key) {
+    const { buffer, cursor } = s;
+    const name = key?.name;
+    if (key?.ctrl) {
+        switch (name) {
+            case "c":
+                return { state: s, action: "cancel" }; // Ctrl+C → caller decides (at the prompt: quit)
+            case "d":
+                return buffer.length === 0 ? { state: s, action: "eof" } : forwardDelete(s); // Ctrl+D empty → EOF, else delete
+            case "a":
+                return { state: { buffer, cursor: 0 }, action: "edit" }; // start of line
+            case "e":
+                return { state: { buffer, cursor: buffer.length }, action: "edit" }; // end of line
+            case "u":
+                return { state: { buffer: buffer.slice(cursor), cursor: 0 }, action: "edit" }; // kill to start
+            case "k":
+                return { state: { buffer: buffer.slice(0, cursor), cursor }, action: "edit" }; // kill to end
+            case "w":
+                return killWordBack(s); // kill the word before the cursor
+            case "b":
+                return { state: { buffer, cursor: Math.max(0, cursor - 1) }, action: "edit" }; // back one char
+            case "f":
+                return { state: { buffer, cursor: Math.min(buffer.length, cursor + 1) }, action: "edit" }; // forward one char
+            case "r":
+                return { state: s, action: "reveal" }; // Ctrl+R → reveal the model's collapsed thinking
+            default:
+                return { state: s, action: "none" };
+        }
+    }
+    switch (name) {
+        case "return":
+        case "enter":
+            return { state: s, action: "submit" };
+        case "backspace":
+            return cursor > 0
+                ? { state: { buffer: buffer.slice(0, cursor - 1) + buffer.slice(cursor), cursor: cursor - 1 }, action: "edit" }
+                : { state: s, action: "none" };
+        case "delete":
+            return forwardDelete(s);
+        case "left":
+            return { state: { buffer, cursor: Math.max(0, cursor - 1) }, action: "edit" };
+        case "right":
+            return { state: { buffer, cursor: Math.min(buffer.length, cursor + 1) }, action: "edit" };
+        case "home":
+            return { state: { buffer, cursor: 0 }, action: "edit" };
+        case "end":
+            return { state: { buffer, cursor: buffer.length }, action: "edit" };
+        case "up":
+            return { state: s, action: "histPrev" };
+        case "down":
+            return { state: s, action: "histNext" };
+        case "escape":
+            return { state: { buffer: "", cursor: 0 }, action: "edit" }; // Esc clears the line
+        case "tab":
+            return { state: s, action: "tab" };
+        default:
+            // Printable insertion. A paste arrives as a multi-char string; insert it whole.
+            if (str && !key?.meta && isPrintable(str)) {
+                return { state: { buffer: buffer.slice(0, cursor) + str + buffer.slice(cursor), cursor: cursor + str.length }, action: "edit" };
+            }
+            return { state: s, action: "none" };
+    }
+}
+function forwardDelete(s) {
+    const { buffer, cursor } = s;
+    return cursor < buffer.length ? { state: { buffer: buffer.slice(0, cursor) + buffer.slice(cursor + 1), cursor }, action: "edit" } : { state: s, action: "none" };
+}
+function killWordBack(s) {
+    const { buffer, cursor } = s;
+    let i = cursor;
+    while (i > 0 && /\s/.test(buffer[i - 1]))
+        i--; // skip trailing spaces
+    while (i > 0 && !/\s/.test(buffer[i - 1]))
+        i--; // then the word
+    return { state: { buffer: buffer.slice(0, i) + buffer.slice(cursor), cursor: i }, action: "edit" };
+}
+function isPrintable(str) {
+    return [...str].every((c) => c >= " " && c !== "\x7f"); // no control chars (incl. lone newlines/DEL)
+}
+// ---- width + wrapping math --------------------------------------------------
+const ANSI = /\x1b\[[0-9;]*m/g; // SGR color codes — they take zero display columns
+// Display width of a string, ANSI-aware and CJK-aware (full-width glyphs are 2
+// columns; String.length would miscount them and break wrapping/cursor math).
+export function displayWidth(s) {
+    let w = 0;
+    for (const ch of s.replace(ANSI, ""))
+        w += charWidth(ch.codePointAt(0));
+    return w;
+}
+function charWidth(cp) {
+    if (cp >= 0x1100 &&
+        (cp <= 0x115f || // Hangul Jamo
+            cp === 0x2329 ||
+            cp === 0x232a ||
+            (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) || // CJK … Yi
+            (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+            (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+            (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+            (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+            (cp >= 0xffe0 && cp <= 0xffe6) ||
+            (cp >= 0x1f300 && cp <= 0x1faff) || // emoji
+            (cp >= 0x20000 && cp <= 0x3fffd)) // CJK extension B+
+    )
+        return 2;
+    return 1;
+}
+// Clip a (possibly ANSI-styled) string to a display width: keep escape codes
+// (zero width) intact, never split a wide glyph. This stops a long status footer
+// from wrapping — a wrapped footer row occupies TWO physical rows, which would
+// desync the editor's row math and drop the caret a line too low (and then every
+// repaint clears from the wrong row, stacking a fresh prompt each keystroke).
+export function truncateToWidth(s, width) {
+    let w = 0;
+    let out = "";
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === "\x1b") {
+            const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i)); // an SGR colour code — copy it, it has no width
+            if (m) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        const cp = s.codePointAt(i);
+        const ch = String.fromCodePoint(cp);
+        const cw = charWidth(cp);
+        if (w + cw > width)
+            return out + "\x1b[0m"; // would overflow → stop, closing any open colour
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return out;
+}
+// Wrap the input across the terminal width and find where the cursor lands.
+// Row 0 begins after the prompt (promptW columns); continuation rows start at 0.
+// Returns the buffer text per row (the driver prepends the prompt to row 0) plus
+// the cursor's (row, col) — so a wrapped line keeps the caret exactly right.
+export function layout(buffer, cursor, promptW, cols) {
+    const width = Math.max(2, cols);
+    const rows = [""];
+    let row = 0;
+    let col = promptW;
+    let cursorRow = 0;
+    let cursorCol = promptW;
+    let set = false;
+    let cu = 0; // code-unit offset, to match `cursor`
+    for (const ch of buffer) {
+        if (!set && cu === cursor) {
+            cursorRow = row;
+            cursorCol = col;
+            set = true;
+        }
+        const w = charWidth(ch.codePointAt(0));
+        if (col + w > width) {
+            row++;
+            col = 0;
+            rows[row] = "";
+        }
+        rows[row] += ch;
+        col += w;
+        cu += ch.length;
+    }
+    if (!set) {
+        cursorRow = row;
+        cursorCol = col; // cursor at the very end
+    }
+    if (cursorCol >= width) {
+        // caret sat exactly at the right edge — it belongs at the start of the next row
+        cursorRow++;
+        cursorCol = 0;
+        if (rows.length <= cursorRow)
+            rows.push("");
+    }
+    return { rows, cursorRow, cursorCol };
+}
+// Read one line with the full editor + pinned footer. Resolves with the line, or
+// cancel (Ctrl+C) / eof (Ctrl+D on an empty line) for the caller to interpret.
+export function editLine(rl, opts) {
+    return new Promise((resolve) => {
+        const input = opts.input ?? process.stdin;
+        const out = process.stdout;
+        if (!input.isTTY)
+            return resolve({ type: "eof" }); // caller guards, but be safe
+        const promptW = displayWidth(opts.prompt);
+        const footerRows = opts.footer ? opts.footer.split("\n") : [];
+        const history = opts.history ?? [];
+        let hi = history.length; // history cursor; == length means "the live draft"
+        let draft = "";
+        let state = { buffer: opts.initial ?? "", cursor: (opts.initial ?? "").length };
+        let done = false;
+        let first = true;
+        let prevCursorRow = 0; // where the caret sits within the block, to climb back next repaint
+        const wasRaw = input.isRaw === true; // restore THIS on exit (forcing false would close the live readline)
+        const cols = () => out.columns || 80;
+        // The session's readline keeps its OWN 'keypress' handler on stdin. Once
+        // readline has been activated (after the first resume), that handler fires on
+        // every key alongside ours and fights us for the cursor — the line stacks
+        // instead of redrawing in place. Detach the other keypress listeners while we
+        // own the input, and restore them exactly on exit (menu/confirm still need them).
+        let otherKeypress = [];
+        // Repaint the whole block in place: climb to its top, clear downward, reprint
+        // input rows + footer, then drop the caret onto its computed (row, col).
+        const draw = () => {
+            const { rows, cursorRow, cursorCol } = layout(state.buffer, state.cursor, promptW, cols());
+            if (!first) {
+                if (prevCursorRow > 0)
+                    out.write(`\x1b[${prevCursorRow}A`); // up to the block's top row
+                out.write("\r");
+            }
+            out.write("\x1b[0J"); // clear from the top of the block to end of screen
+            const inputRows = rows.map((r, i) => (i === 0 ? opts.prompt + r : r));
+            // Truncate each footer row so it can't wrap — otherwise its extra physical
+            // row throws off the cursor math below (caret lands low → prompts stack).
+            const fr = footerRows.map((f) => truncateToWidth(f, Math.max(1, cols() - 1)));
+            const all = [...inputRows, ...fr];
+            out.write(all.join("\r\n"));
+            const lastRow = all.length - 1; // every row is now exactly one physical line
+            if (lastRow > cursorRow)
+                out.write(`\x1b[${lastRow - cursorRow}A`); // up from the last footer row
+            out.write("\r");
+            if (cursorCol > 0)
+                out.write(`\x1b[${cursorCol}C`); // right to the caret column
+            prevCursorRow = cursorRow;
+            first = false;
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey);
+            for (const l of otherKeypress)
+                input.on("keypress", l); // give readline its keypress handler back
+            // Leave the typed command on screen, drop the footer, land on a fresh line.
+            const { rows } = layout(state.buffer, state.cursor, promptW, cols());
+            if (prevCursorRow > 0)
+                out.write(`\x1b[${prevCursorRow}A`);
+            out.write("\r\x1b[0J");
+            const inputRows = rows.map((r, i) => (i === 0 ? opts.prompt + r : r));
+            out.write(inputRows.join("\r\n") + "\r\n");
+            try {
+                input.setRawMode(wasRaw); // hand stdin back exactly as we found it
+            }
+            catch {
+                /* not all streams support it */
+            }
+            rl.resume();
+            resolve(result);
+        };
+        const onKey = (str, key) => {
+            if (done)
+                return;
+            // A drag-and-drop (or any paste) arrives as one multi-char string. Give the
+            // caller a chance to rewrite it — e.g. turn dropped file paths into clean
+            // absolute paths — before it lands in the buffer. No-op for normal text.
+            if (str && str.length > 1 && !key?.ctrl && !key?.meta && opts.transformPaste) {
+                str = opts.transformPaste(str);
+            }
+            const next = reduceEditor(state, str, key || {});
+            state = next.state;
+            switch (next.action) {
+                case "submit":
+                    return finish({ type: "line", value: state.buffer });
+                case "cancel":
+                    return finish({ type: "cancel" });
+                case "eof":
+                    return finish({ type: "eof" });
+                case "histPrev":
+                    if (hi > 0) {
+                        if (hi === history.length)
+                            draft = state.buffer; // stash the live draft on the way up
+                        hi--;
+                        state = { buffer: history[hi], cursor: history[hi].length };
+                    }
+                    return draw();
+                case "histNext":
+                    if (hi < history.length) {
+                        hi++;
+                        const b = hi === history.length ? draft : history[hi];
+                        state = { buffer: b, cursor: b.length };
+                    }
+                    return draw();
+                case "tab":
+                    opts.onTab?.(); // may print above us (e.g. expand a collapsed block) and scroll
+                    first = true; // so the next paint lands fresh at the cursor, not a stale climb-up
+                    return draw();
+                case "reveal":
+                    opts.onReveal?.(); // print the model's collapsed thinking above us, then repaint
+                    first = true; // the next paint lands fresh, not a stale climb-up
+                    return draw();
+                case "edit":
+                    return draw();
+                case "none":
+                    return;
+            }
+        };
+        try {
+            rl.pause(); // stop the session reader from turning our keystrokes into lines
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input); // decode raw bytes into named keys
+            otherKeypress = input.listeners("keypress"); // readline's handler(s)…
+            for (const l of otherKeypress)
+                input.off("keypress", l); // …detached so only we drive the cursor
+            input.setRawMode(true);
+            input.resume(); // rl.pause() also paused the stream — resume it or no keys arrive
+            input.on("keypress", onKey);
+            draw();
+        }
+        catch {
+            finish({ type: "eof" }); // setup failed (non-TTY etc.) → behave like EOF
+        }
+    });
+}