@cruxy/cli 1.2.1 → 1.4.0

package/dist/tui/app.js

@@ -0,0 +1,508 @@
+import { DEFAULT_MODE, MODE_LABELS, modeAutoApproves, } from "../agent/index.js";
+import { completeLine } from "../components/autocomplete.js";
+import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
+import { selectList } from "../components/select.js";
+import { viewLabel, viewOrder } from "./views.js";
+import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
+import { openPalette } from "./palette.js";
+import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
+import { CLOSABLE_PANELS, columnOf, RAIL_PANELS, } from "./layout.js";
+import { COLUMN_LABELS, PANEL_LABELS } from "./panels.js";
+/**
+ * The TUI's input loop (P1) — the piece that replaces `repl.ts`'s readline
+ * loop. It owns exactly two things: the edit buffer and command dispatch.
+ * Everything visible is the renderer's; everything the agent does is the
+ * session's.
+ *
+ * The stdin discipline is inherited from the REPL for the same reason it
+ * existed there: while a turn runs, the approval prompt grabs stdin in raw mode
+ * through the shared `readSingleKey`. Two raw-mode readers on one stdin would
+ * contend, so this loop takes stdin only while collecting a line and RELEASES it
+ * (`restore()` in a `finally`) before `session.send` — the approval prompt then
+ * has uncontested ownership, exactly as with the per-line readline interface.
+ *
+ * P5 track 1 keeps that behaviour and changes what enforces it. The loop now
+ * reads through a {@link KeyLease} rather than a reader of its own: one reader
+ * for the whole session, refcounted, so releasing between lines still leaves
+ * raw mode (the count returns to zero, and the approval prompt's ownership is
+ * unchanged) while a modal opened DURING a read borrows the live reader instead
+ * of opening a second one. Release-before-send stops being the only thing
+ * standing between the TUI and two readers on one stdin.
+ */
+/**
+ * Every command the TUI completes on Tab — the shared set plus this shell's own
+ * panel commands (P5 track 5).
+ *
+ * This constant existed before and was consumed by NOTHING: exported from
+ * `tui/index.ts`, imported nowhere, while the TUI had no completion at all.
+ * It is wired to Tab now rather than deleted, because the thing it was reaching
+ * for — the REPL's readline completer, which the TUI cannot use — is real.
+ */
+export const TUI_COMMANDS = [
+    ...SHARED_COMMANDS,
+    "/close",
+    "/open",
+    "/view",
+].sort();
+const HELP = [
+    "commands:",
+    ...SHARED_HELP,
+    "  /close <panel>   hide a panel (sidebar | context | model | git | tools)",
+    "                   or a whole column (rail = all four rail panels)",
+    "  /open <panel>    show a hidden panel",
+    "  /view [name]     show a main-pane view, or list them",
+    "  Tab              complete a slash command",
+    "  Ctrl+K           open the command palette",
+    "  Ctrl+B           focus the sidebar nav (arrows switch view, Esc leaves)",
+    "  Shift+Tab        cycle mode (manual · auto-approve · plan · full-auto)",
+    "  PgUp / PgDn      scroll the pane; Esc returns to the live view",
+    "  Ctrl+D           leave cruxy",
+];
+/**
+ * Group names `/close` and `/open` accept beside individual panels. `rail` is
+ * the one that matters for compatibility: it is what P1 shipped and what users
+ * already have in their fingers, so it keeps working — as the whole stack.
+ */
+const PANEL_GROUPS = {
+    rail: RAIL_PANELS,
+};
+const emptyEditor = () => ({ text: "", cursor: 0 });
+/**
+ * Render the input row: mode chip, prompt, text, and a visible caret at the
+ * cursor. The caret is drawn rather than moved, because the frame owns the real
+ * cursor — it parks after the last painted row so a repaint can erase upward.
+ *
+ * The chip is shown for every mode EXCEPT `manual` (P5 track 4). Manual is the
+ * default and asks about everything, so a chip there would be noise on every
+ * session; the modes worth a permanent marker are the ones where the agent is
+ * doing something you did not individually agree to, and those must never be
+ * inferable only from what has already happened. `full-auto` and `auto-approve`
+ * carry the warning role rather than the muted one for the same reason.
+ */
+export function renderInput(editor, theme, mode = DEFAULT_MODE) {
+    const chip = mode === DEFAULT_MODE
+        ? ""
+        : `${modeAutoApproves(mode) ? theme.warning(`[${MODE_LABELS[mode]}]`) : theme.muted(`[${MODE_LABELS[mode]}]`)} `;
+    const prompt = `${chip}${theme.accent("cruxy")} ${theme.muted(theme.glyph.caret)} `;
+    const before = editor.text.slice(0, editor.cursor);
+    const at = editor.text.slice(editor.cursor, editor.cursor + 1);
+    const after = editor.text.slice(editor.cursor + 1);
+    const caret = at === "" ? theme.accent(theme.glyph.cursorBar) : theme.strong(at);
+    return prompt + before + caret + after;
+}
+/**
+ * Parse `/close git` → ["git"], `/close rail` → the four rail panels. Returns
+ * null when the argument is missing or unknown — never a guess, so a typo can
+ * not close something the user did not name.
+ */
+function panelArg(input, command) {
+    const arg = input.slice(command.length).trim().toLowerCase();
+    const group = PANEL_GROUPS[arg];
+    if (group)
+        return { label: arg, panels: group };
+    const match = CLOSABLE_PANELS.find((p) => p === arg);
+    return match ? { label: PANEL_LABELS[match], panels: [match] } : null;
+}
+/**
+ * Keys the focused sidebar nav claims (P7 track 2). Returns whether it took
+ * the key — anything it declines falls through to the input line untouched.
+ *
+ * The set is deliberately small. Up/down move the selection and Enter is not
+ * needed to commit it: selecting a view IS the action, and a two-step
+ * move-then-confirm would make the arrows do nothing visible on their own.
+ * Esc and Ctrl+B both hand the keyboard back, so the way out is whichever of
+ * the two the user reaches for first.
+ *
+ * A PRINTABLE CHARACTER RETURNS FOCUS AND IS NOT SWALLOWED. Someone who starts
+ * typing has stopped navigating, and losing the first letter of a prompt to a
+ * focus mode they forgot they were in is the failure that makes people stop
+ * using the binding.
+ */
+function handleNavKey(key, renderer) {
+    switch (key.kind) {
+        case "up":
+            renderer.cycleView(-1);
+            return true;
+        case "down":
+            renderer.cycleView(1);
+            return true;
+        case "escape":
+        case "ctrl-b":
+        case "enter":
+            renderer.focusSidebar(false);
+            return true;
+        case "char":
+            // Claim the focus change only; the character itself falls through to the
+            // editor on this same keypress.
+            renderer.focusSidebar(false);
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Read one line from the TUI's input row. Takes raw stdin for the duration and
+ * always releases it. Resolves `null` on Ctrl+D / EOF.
+ */
+async function readLine(keys, renderer, hooks) {
+    const editor = emptyEditor();
+    const paint = () => renderer.setInput(renderInput(editor, renderer.theme, hooks.mode()));
+    paint();
+    keys.begin();
+    try {
+        for (;;) {
+            const key = await keys.read();
+            // FOCUS IS A ROUTING DECISION, resolved before the editor sees anything
+            // (P7 track 2). While the sidebar holds the keyboard the arrows move the
+            // view selection instead of the cursor — but only the keys that mean
+            // something there are claimed, so scrolling, the palette and the mode ring
+            // keep working exactly as they do at the input line. A view is persistent
+            // and NON-EXCLUSIVE; this is not a modal, and nothing here blocks.
+            if (renderer.sidebarHasFocus() && handleNavKey(key, renderer)) {
+                paint();
+                continue;
+            }
+            switch (key.kind) {
+                case "enter": {
+                    const text = editor.text;
+                    editor.text = "";
+                    editor.cursor = 0;
+                    // Submitting returns to the live view (P7 track 1). Scrollback holds
+                    // its position against output arriving on its own, which is the point
+                    // — but the user asking for that output is not "on its own", and
+                    // answering into a pane they cannot see is the one case where holding
+                    // still is wrong.
+                    renderer.scrollToLive();
+                    paint();
+                    return text;
+                }
+                case "eof":
+                    return null;
+                case "ctrl-c":
+                    // A populated buffer: clear it (an escape hatch from a half-typed
+                    // line). An empty one: Ctrl-C means leave, same as the REPL.
+                    if (editor.text === "")
+                        return null;
+                    editor.text = "";
+                    editor.cursor = 0;
+                    paint();
+                    break;
+                case "backspace":
+                    if (editor.cursor > 0) {
+                        editor.text =
+                            editor.text.slice(0, editor.cursor - 1) +
+                                editor.text.slice(editor.cursor);
+                        editor.cursor--;
+                        paint();
+                    }
+                    break;
+                case "left":
+                    if (editor.cursor > 0) {
+                        editor.cursor--;
+                        paint();
+                    }
+                    break;
+                case "right":
+                    if (editor.cursor < editor.text.length) {
+                        editor.cursor++;
+                        paint();
+                    }
+                    break;
+                case "char":
+                    editor.text =
+                        editor.text.slice(0, editor.cursor) +
+                            key.char +
+                            editor.text.slice(editor.cursor);
+                    editor.cursor += key.char.length;
+                    paint();
+                    break;
+                case "tab": {
+                    // Complete a slash command in place (P5 track 5). Only the leading
+                    // word of a `/…` line completes — everything else is prose bound for
+                    // the model, and Tab must never mangle it. Completing REWRITES the
+                    // buffer and never submits: Enter stays the only trigger, exactly as
+                    // the REPL's readline completer behaves.
+                    const head = editor.text.slice(0, editor.cursor);
+                    if (head.startsWith("/") && !/\s/.test(head)) {
+                        const { line, suggestions } = completeLine(head, TUI_COMMANDS);
+                        if (suggestions.length > 1) {
+                            renderer.println(renderer.theme.muted(suggestions.join("  ")));
+                        }
+                        if (line !== head) {
+                            editor.text = line + editor.text.slice(editor.cursor);
+                            editor.cursor = line.length;
+                        }
+                        paint();
+                    }
+                    break;
+                }
+                case "ctrl-k": {
+                    // The command palette (P5 track 6). It runs on the SAME reader this
+                    // loop is holding — track 1's lease makes the nested claim a no-op —
+                    // and paints into the same frame, so the conversation stays behind it.
+                    const picked = await hooks.openPalette();
+                    if (picked !== null) {
+                        // Inserted at the cursor, not appended: the palette is reachable
+                        // mid-line, and a command pasted onto the end of a half-typed
+                        // sentence is not what anyone meant by it.
+                        editor.text =
+                            editor.text.slice(0, editor.cursor) +
+                                picked +
+                                editor.text.slice(editor.cursor);
+                        editor.cursor += picked.length;
+                    }
+                    // Repaint either way: the drawer coming down leaves rows to reclaim.
+                    paint();
+                    break;
+                }
+                case "shift-tab":
+                    // Cycle the mode WITHOUT disturbing the line being typed (P5 track 4).
+                    // Mode is a property of the session, not of the message — losing a
+                    // half-written prompt to a mode switch would make the binding one
+                    // people learn not to press.
+                    hooks.cycleMode();
+                    paint();
+                    break;
+                case "page-up":
+                case "page-down":
+                    // Scroll the conversation (P7 track 1). Like Shift+Tab, this leaves
+                    // the line being typed completely alone: reading back over what was
+                    // said is the most ordinary thing to do WHILE composing a reply, and
+                    // a scroll that cost the draft would be unusable for exactly that.
+                    //
+                    // No `paint()`: the input row has not changed, and the renderer
+                    // schedules its own repaint for the rows that did.
+                    renderer.scrollPage(key.kind === "page-up" ? 1 : -1);
+                    break;
+                case "escape":
+                    // Esc leaves the scrolled view — a mode needs a visible exit, and the
+                    // notice names this key. It stays inert at the live tail rather than
+                    // being claimed unconditionally, so the binding remains free for
+                    // whatever a later track wants Esc to mean when nothing is scrolled.
+                    renderer.scrollToLive();
+                    break;
+                case "ctrl-b":
+                    // Take the keyboard to the sidebar nav (P7 track 2). Refused when the
+                    // sidebar is closed or dropped for width, and SAID rather than
+                    // silently ignored: focus the user cannot see would make the arrows
+                    // change meaning with nothing on screen to account for it.
+                    if (!renderer.focusSidebar(true)) {
+                        renderer.println(renderer.theme.muted("(no sidebar to focus — /open sidebar, or widen the terminal)"));
+                    }
+                    paint();
+                    break;
+                default:
+                    // arrows: no binding yet, deliberately inert rather than leaking a
+                    // control char into the buffer.
+                    break;
+            }
+        }
+    }
+    finally {
+        keys.restore();
+    }
+}
+/** Render a failed turn into the conversation and carry on — never exit. */
+function printTurnError(renderer, err) {
+    const cruxy = fromUnknown(err);
+    const text = formatError(cruxy, {
+        verbose: isVerbose(),
+        color: shouldUseColor(process.stdout),
+    });
+    for (const line of text.split("\n"))
+        renderer.println(line);
+}
+/** Echo the submitted line into the conversation, the way the REPL echoes a turn. */
+function echoPrompt(renderer, text) {
+    const t = renderer.theme;
+    renderer.println(`${t.accent("cruxy")} ${t.muted(t.glyph.caret)} ${text}`);
+}
+/**
+ * Dispatch one submitted line. Returns `"exit"` when the loop should end,
+ * `null` to continue.
+ */
+async function dispatch(input, session, renderer, out, slashCommands, checkpoints, pick) {
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return null;
+    // This shell's own commands first — they are about panels, which the REPL
+    // has none of.
+    if (trimmed === "/help") {
+        for (const line of HELP)
+            renderer.println(renderer.theme.muted(line));
+        renderer.println();
+        return null;
+    }
+    if (trimmed === "/close" || trimmed.startsWith("/close ")) {
+        handlePanel(trimmed, "/close", false, renderer);
+        return null;
+    }
+    if (trimmed === "/open" || trimmed.startsWith("/open ")) {
+        handlePanel(trimmed, "/open", true, renderer);
+        return null;
+    }
+    if (trimmed === "/view" || trimmed.startsWith("/view ")) {
+        handleView(trimmed, renderer);
+        return null;
+    }
+    // Everything else is the SHARED implementation (P5 track 5). P1 forked this
+    // loop out of `repl.ts` and left every one of these behind — including
+    // `/plan`, which was then the only way to reach plan mode at all.
+    const outcome = await dispatchCommand(input, {
+        session,
+        out,
+        slashCommands,
+        tty: true, // the TUI only runs on a terminal
+        ...(pick ? { pick } : {}),
+    });
+    if (outcome.kind === "exit")
+        return "exit";
+    if (outcome.kind === "handled")
+        return null;
+    // A real turn. Assistant text streams into the main column through the
+    // renderer; the loop below owns nothing but input.
+    echoPrompt(renderer, outcome.text);
+    try {
+        checkpoints?.beginRun(outcome.text);
+        await session.send(outcome.text, renderer);
+    }
+    catch (err) {
+        printTurnError(renderer, err);
+    }
+    return null;
+}
+/**
+ * `/view [name]` — select a main-pane view, or list what there is (P7 track 2).
+ *
+ * Exists so switching views never depends on the sidebar. The nav is the
+ * discoverable path, but it can be closed or dropped for width, and a UI whose
+ * only route to a surface can vanish is one that strands people. This is also
+ * the scriptable path, which is what makes the register testable end to end.
+ */
+function handleView(input, renderer) {
+    const t = renderer.theme;
+    const sources = renderer.viewSources();
+    const arg = input.slice("/view".length).trim().toLowerCase();
+    const ids = viewOrder(sources);
+    if (arg === "") {
+        renderer.println(t.muted("views:"));
+        for (const id of ids) {
+            const mark = id === renderer.view() ? t.glyph.pointer : " ";
+            renderer.println(t.muted(`  ${mark} ${viewLabel(id, sources)}`));
+        }
+        return;
+    }
+    // Matched on the id AND the label, because the sidebar shows the label and
+    // that is what a user will type back. They are the same string for every
+    // view so far; keeping both accepted means they can diverge without the
+    // command quietly becoming wrong.
+    const target = ids.find((id) => id === arg || viewLabel(id, sources).toLowerCase() === arg);
+    if (target === undefined || !renderer.setView(target)) {
+        renderer.println(t.muted(`unknown view: ${arg}`));
+        renderer.println(t.muted(`try: ${ids.map((id) => viewLabel(id, sources)).join(" | ")}`));
+        return;
+    }
+    renderer.println(t.muted(`showing ${viewLabel(target, sources)}`));
+}
+/** `/close <panel>` and `/open <panel>` share everything but the target state. */
+function handlePanel(input, command, open, renderer) {
+    const t = renderer.theme;
+    const target = panelArg(input, command);
+    if (target === null) {
+        const names = [...CLOSABLE_PANELS.map((p) => PANEL_LABELS[p]), "rail"].join(" | ");
+        renderer.println(t.muted(`usage: ${command} <${names}>`));
+        return;
+    }
+    const { label, panels } = target;
+    // A group counts as changed when ANY of its panels moved, so `/open rail`
+    // with one panel already open still opens the other three.
+    const changed = panels
+        .map((p) => renderer.setPanelOpen(p, open))
+        .some(Boolean);
+    if (!changed) {
+        renderer.println(t.muted(`${label} is already ${open ? "open" : "closed"}`));
+        return;
+    }
+    const verb = open ? "opened" : "closed";
+    const restore = open ? "/close" : "/open";
+    renderer.println(t.muted(`${label} ${verb} — ${restore} ${label} to undo`));
+    if (!open)
+        return;
+    // Opening a panel the screen cannot show must SAY so; silently painting
+    // nothing would read as a broken command. Width and height fail differently
+    // and are fixed differently, so they are reported separately rather than
+    // collapsed into one vague "doesn't fit".
+    const columns = renderer.droppedColumns();
+    const lost = columns.find((c) => panels.some((p) => columnOf(p) === c));
+    if (lost !== undefined) {
+        renderer.println(t.muted(`(not enough width for the ${COLUMN_LABELS[lost]} — widen the terminal)`));
+        return;
+    }
+    const short = renderer.droppedRailPanels();
+    if (panels.some((p) => p !== "sidebar" && short.includes(p))) {
+        renderer.println(t.muted(`(not enough height to show it yet — make the terminal taller)`));
+    }
+}
+/**
+ * Drive the TUI: paint the shell, then prompt → read → dispatch until the user
+ * leaves. `initialMessage` (from `cruxy "<message>"`) runs as the first turn
+ * before the first prompt, so the shell is already on screen while it streams.
+ */
+export async function runTui(session, renderer, opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    renderer.setInput(renderInput(emptyEditor(), renderer.theme, session.getMode()));
+    if (opts.initialMessage && opts.initialMessage.trim() !== "") {
+        const first = opts.initialMessage.trim();
+        echoPrompt(renderer, first);
+        try {
+            opts.checkpoints?.beginRun(first);
+            await session.send(first, renderer);
+        }
+        catch (err) {
+            printTurnError(renderer, err);
+        }
+    }
+    // One reader for the whole session, leased per line. Released before any turn
+    // runs — see the stdin note at the top of this file.
+    const lease = opts.lease ?? createKeyLease(stdin);
+    // The TUI's command output: committed into the conversation column. No
+    // width fitting — `main` reflows at paint time, so truncating here would
+    // clip a line the column was about to wrap correctly.
+    const out = {
+        print: (line = "") => renderer.println(line),
+        theme: renderer.theme,
+        fit: (line) => line,
+    };
+    const hooks = {
+        mode: () => session.getMode(),
+        cycleMode: () => announceMode(out, session.cycleMode()),
+        openPalette: () => openPalette(renderer, lease, opts.slashCommands ?? []),
+    };
+    // The TUI's picker (P6 track 1): an overlay drawer on the SAME reader this
+    // loop holds, exactly like the palette. Declines rather than painting into a
+    // terminal with no room for a drawer — a modal that renders nothing while
+    // still eating every keystroke is indistinguishable from a hang.
+    const pick = async (items, pickOpts) => {
+        if (!canOverlay(renderer))
+            return null;
+        const result = await selectList(items, {
+            title: pickOpts.title,
+            toLabel: pickOpts.toLabel,
+            ...(pickOpts.initialIndex === undefined
+                ? {}
+                : { initialIndex: pickOpts.initialIndex }),
+            // The drawer's budget, minus the title row and the key hint the
+            // component draws around the list.
+            maxVisible: Math.max(1, renderer.overlayRows() - 2),
+        }, createOverlayIO(renderer, lease));
+        return result.kind === "selected" ? result.value : null;
+    };
+    for (;;) {
+        const line = await readLine(lease.handle(), renderer, hooks);
+        if (line === null)
+            return "eof";
+        const outcome = await dispatch(line, session, renderer, out, opts.slashCommands ?? [], opts.checkpoints, pick);
+        if (outcome !== null)
+            return outcome;
+    }
+}

package/dist/tui/approval-overlay.js

@@ -0,0 +1,160 @@
+/**
+ * The approval prompt as an in-viewport modal (P5 track 2).
+ *
+ * Before this, the prompt was the one thing in the TUI that could not be drawn:
+ * it wrote to stderr, so the renderer's only way to keep those bytes legible was
+ * to clear the entire shell for the duration. You answered "may I overwrite
+ * this file?" with the diff, the conversation, and the file's own name gone from
+ * the screen. The question survived; everything that made it answerable did not.
+ *
+ * Nothing about the prompt's LOGIC changes here — `promptForApproval` still
+ * renders the same bytes, reads the same 4-way choice, and default-denies on
+ * anything unrecognized. Only the surface moves: `write` composes overlay rows
+ * instead of terminal bytes, and the reads come from the session's key lease
+ * rather than a reader of their own.
+ *
+ * The displaced-state latch is untouched and still lives in the renderer:
+ * `beginPrompt` sets `awaiting-approval` (stashing the phase and its clock) and
+ * `endPrompt` calls `promptResolved` to put them back. That part was already
+ * correct — this only stops the phase from meaning "blank the screen".
+ */
+/**
+ * Build a {@link PromptIO} that draws into the TUI's overlay drawer.
+ *
+ * The write model is append-and-recompose, which is what lets the existing
+ * prompt code run unmodified: `promptForApproval` emits its block, then a
+ * newline, then possibly a follow-up label, treating `write` as a terminal that
+ * remembers. Buffering the whole transcript and re-splitting it on every write
+ * gives exactly that behaviour without the prompt knowing it is in a modal.
+ */
+export function createOverlayPromptIO(surface, lease, color) {
+    /** Everything the prompt has written this interaction, verbatim. */
+    let transcript = "";
+    /** The line being typed into a `readLine` follow-up, if one is open. */
+    let typing = null;
+    /** This interaction's claim on the shared reader; null while none is open. */
+    let keys = null;
+    const paint = () => {
+        // A trailing "\n" from the prompt means "that line is done", not "add a
+        // blank row" — `split` would produce an empty last element and the drawer
+        // would grow a dead row under the choices.
+        const body = transcript.replace(/\n$/, "");
+        const rows = body === "" ? [] : body.split("\n");
+        // The caret is drawn, not moved: the frame parks the real cursor after the
+        // last painted row so a repaint can erase upward, exactly as the input row
+        // does. An invisible cursor in a text field reads as a hang, so the field
+        // always shows where the next character lands.
+        if (typing !== null) {
+            rows[Math.max(0, rows.length - 1)] =
+                `${rows[rows.length - 1] ?? ""}${typing}▏`;
+        }
+        surface.setOverlay(rows);
+    };
+    return {
+        color,
+        // The drawer spans the viewport, so the prompt reflows against the width it
+        // is actually painted at — not stderr's, which is what it measured when it
+        // was writing to stderr.
+        get columns() {
+            return surface.overlayWidth();
+        },
+        beginPrompt() {
+            transcript = "";
+            typing = null;
+            // Borrow the session's reader. When the input loop is between lines this
+            // is the first claim and enters raw mode; when a modal is opened from
+            // inside a read it is a no-op on a terminal already in raw mode.
+            keys = lease.handle();
+            keys.begin();
+        },
+        endPrompt() {
+            // Take the drawer down and hand the reader back on EVERY path, including
+            // a default-deny on EOF. A modal that yields nothing back leaves the
+            // conversation permanently short a few rows.
+            surface.setOverlay(null);
+            transcript = "";
+            typing = null;
+            keys?.restore();
+            keys = null;
+        },
+        write(text) {
+            transcript += text;
+            paint();
+        },
+        async readKey() {
+            const key = await read(keys);
+            return keyToChar(key);
+        },
+        /**
+         * The follow-up line for `n` (reason) and `t` (instruction), edited in the
+         * drawer. Append-only plus backspace: this is a one-line reason field, not
+         * the input row, and cursor movement inside it would be the first thing to
+         * need a second editor implementation for no user-visible gain.
+         *
+         * Escape and Ctrl-C resolve "" — which `promptForApproval` reads as "no
+         * reason given", collapsing `instruct` to a plain reject. Backing out of the
+         * reason field can only ever make the decision MORE conservative.
+         */
+        async readLine() {
+            typing = "";
+            paint();
+            try {
+                for (;;) {
+                    const key = await read(keys);
+                    switch (key.kind) {
+                        case "enter":
+                            return typing;
+                        case "eof":
+                        case "ctrl-c":
+                        case "escape":
+                            return "";
+                        case "backspace":
+                            if (typing.length > 0)
+                                typing = typing.slice(0, -1);
+                            break;
+                        case "char":
+                            typing += key.char;
+                            break;
+                        default:
+                            // Arrows and tab: inert rather than leaking a control char into
+                            // text that is sent verbatim to the agent.
+                            break;
+                    }
+                    paint();
+                }
+            }
+            finally {
+                typing = null;
+                paint();
+            }
+        },
+    };
+}
+/**
+ * Read one key, or EOF when no reader is open.
+ *
+ * A read outside a `beginPrompt`/`endPrompt` bracket is a wiring bug, and EOF is
+ * the only safe answer to it: the prompt maps EOF to default-deny, so the
+ * failure mode is a refused action rather than a hang or an approval nobody gave.
+ */
+async function read(keys) {
+    if (keys === null)
+        return { kind: "eof" };
+    return keys.read();
+}
+/**
+ * The {@link PromptIO.readKey} contract, matching `readSingleKey` exactly: the
+ * printable character, `"\n"` for enter, and `""` for everything that means "no
+ * answer" — so the prompt's default-deny mapping is identical in the drawer and
+ * on a bare terminal.
+ */
+function keyToChar(key) {
+    switch (key.kind) {
+        case "char":
+            return key.char;
+        case "enter":
+            return "\n";
+        default:
+            return "";
+    }
+}