agent-from-zero 0.1.0 → 0.27.0

package/dist/mcp.js

@@ -0,0 +1,237 @@
+import { spawn } from "node:child_process"; // stdio servers are subprocesses
+import chalk from "chalk"; // status lines
+import { CONFIG } from "./config.js"; // configured servers
+import { registerExternalTool } from "./tools.js"; // expose discovered tools
+import { emit } from "./telemetry.js"; // observability
+// MCP (Model Context Protocol) lets the agent borrow tools from external
+// servers — a filesystem server, a GitHub server, a database server, anything.
+// The wire protocol is JSON-RPC 2.0. We do the initialize handshake, ask for the
+// server's tools, and register each one so it flows through the SAME dispatch and
+// the SAME permission gate as a built-in. There is one execution path, period.
+//
+// Since Day 24 there are TWO ways to reach a server: spawn it and talk over
+// stdio (local), or POST to a URL (remote, "Streamable HTTP"). The protocol is
+// identical; only the pipe differs. That difference lives behind a Transport
+// interface, so McpClient — handshake, ids, tool flattening — never has to care.
+//
+// Discovered tools are named mcp__<server>__<tool> so they never collide with
+// built-ins and the user can see (and gate) exactly where each came from.
+const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
+const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
+// ---- stdio transport: one JSON object per line, to a subprocess --------------
+class StdioTransport {
+    child;
+    pending = new Map(); // id → resolver (responses arrive async on one stream)
+    buffer = ""; // partial stdout, reassembled into whole lines
+    constructor(def) {
+        this.child = spawn(def.command, def.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"], // we own stdin/stdout; stderr is the server's log
+            env: { ...process.env, ...def.env }, // pass through + extras
+        });
+        // Reassemble newline-delimited JSON from the stdout stream.
+        this.child.stdout.on("data", (chunk) => {
+            this.buffer += chunk.toString();
+            let nl;
+            while ((nl = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, nl).trim(); // one complete message
+                this.buffer = this.buffer.slice(nl + 1); // keep the remainder
+                if (line)
+                    this.onMessage(line);
+            }
+        });
+        this.child.stderr.on("data", () => { }); // the server's stderr is its own logging — never our stdout
+    }
+    onMessage(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return; // ignore anything that isn't valid JSON-RPC
+        }
+        const resolver = this.pending.get(msg.id);
+        if (resolver) {
+            this.pending.delete(msg.id);
+            resolver(msg);
+        }
+    }
+    request(payload, timeoutMs) {
+        const { id } = payload;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(r);
+            };
+            const timer = setTimeout(() => finish({ id, error: { message: `MCP request '${payload.method}' timed out` } }), timeoutMs);
+            this.pending.set(id, finish);
+            this.child.stdin.write(JSON.stringify(payload) + "\n"); // one line, newline-terminated
+        });
+    }
+    notify(method, params) {
+        this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    }
+    close() {
+        this.child.kill(); // best-effort cleanup
+    }
+}
+// Pull JSON-RPC messages out of a Server-Sent-Events body. SSE frames are
+// separated by blank lines; the payload lives on one or more `data:` lines.
+// Exported because parsing is the fiddly part worth testing on its own.
+export function parseSseData(body) {
+    const out = [];
+    for (const frame of body.split(/\r?\n\r?\n/)) {
+        const data = frame
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim()) // strip "data:" and surrounding space
+            .join("\n");
+        if (data)
+            out.push(data);
+    }
+    return out;
+}
+// ---- HTTP transport: POST to a URL, read JSON or SSE back --------------------
+class HttpTransport {
+    url;
+    headers;
+    sessionId; // assigned by the server on initialize, echoed on every later request
+    constructor(def) {
+        this.url = def.url;
+        this.headers = { ...def.headers };
+    }
+    // The response to a POST may come back as a single JSON object OR as an SSE
+    // stream carrying it. Either way we want the JSON-RPC message matching our id.
+    async post(body, timeoutMs, isRequest) {
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream", // we accept either shape
+                ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+                ...this.headers,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const sid = res.headers.get("mcp-session-id"); // initialize hands us a session to keep
+        if (sid)
+            this.sessionId = sid;
+        if (!isRequest)
+            return null; // a notification expects no body (202 Accepted)
+        const raw = await res.text();
+        const payloads = res.headers.get("content-type")?.includes("text/event-stream") ? parseSseData(raw) : [raw];
+        for (const p of payloads) {
+            try {
+                const msg = JSON.parse(p);
+                if (msg && (msg.result !== undefined || msg.error !== undefined))
+                    return msg; // the response we came for
+            }
+            catch {
+                /* skip non-JSON frames (SSE comments, keep-alives) */
+            }
+        }
+        return null;
+    }
+    async request(payload, timeoutMs) {
+        try {
+            const msg = await this.post(payload, timeoutMs, true);
+            return msg ?? { id: payload.id, error: { message: `MCP request '${payload.method}' returned no response` } };
+        }
+        catch (err) {
+            return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
+        }
+    }
+    notify(method, params) {
+        // Fire-and-forget; errors on a notification are not worth surfacing.
+        void this.post({ jsonrpc: "2.0", method, params }, INIT_TIMEOUT_MS, false).catch(() => { });
+    }
+    close() {
+        // Best-effort: tell the server to drop the session. No await, no error care.
+        if (this.sessionId) {
+            void fetch(this.url, { method: "DELETE", headers: { "mcp-session-id": this.sessionId, ...this.headers } }).catch(() => { });
+        }
+    }
+}
+// Choose the pipe from the config: a url means HTTP, otherwise spawn over stdio.
+function makeTransport(def) {
+    return def.url ? new HttpTransport(def) : new StdioTransport(def);
+}
+// The protocol layer: handshake, request ids, tool flattening. It talks to a
+// Transport and is blind to whether that's a subprocess or an HTTP endpoint.
+class McpClient {
+    transport;
+    nextId = 1; // JSON-RPC request id counter
+    constructor(def) {
+        this.transport = makeTransport(def);
+    }
+    request(method, params, timeoutMs) {
+        return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
+    }
+    // The MCP startup dance: initialize → initialized → list tools.
+    async start() {
+        const init = await this.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mini-agent", version: "0" } }, INIT_TIMEOUT_MS);
+        if (init.error)
+            throw new Error(init.error.message); // server refused to initialize
+        this.transport.notify("notifications/initialized", {}); // tell the server we're ready
+        const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS); // ask what it offers
+        if (list.error)
+            throw new Error(list.error.message);
+        return list.result?.tools ?? [];
+    }
+    // Invoke one tool and flatten its content into plain text for the model.
+    async callTool(name, args) {
+        const res = await this.request("tools/call", { name, arguments: args }, CALL_TIMEOUT_MS);
+        if (res.error)
+            return `[error] MCP tool failed: ${res.error.message}`; // surface, don't throw
+        const text = (res.result?.content ?? []).map((c) => c.text ?? `[${c.type} content]`).join("\n"); // flatten parts
+        const body = text || "(no output)";
+        return res.result?.isError ? `[error] ${body}` : body; // MCP can flag a logical error in a successful response
+    }
+    kill() {
+        this.transport.close();
+    }
+}
+// Connect to every configured MCP server, register their tools, and return a
+// cleanup function. Failures are isolated: a server that won't start is logged
+// and skipped — it never stops the agent or the other servers.
+export async function connectMcpServers() {
+    const entries = Object.entries(CONFIG.mcpServers); // [name, def] pairs
+    if (!entries.length)
+        return () => { }; // the common case: nothing configured
+    const clients = []; // for cleanup
+    for (const [serverName, def] of entries) {
+        const client = new McpClient(def);
+        try {
+            const specs = await client.start(); // handshake + discover
+            clients.push(client);
+            for (const spec of specs) {
+                const toolName = `mcp__${serverName}__${spec.name}`; // namespaced, collision-proof
+                const tool = {
+                    definition: {
+                        type: "function",
+                        function: {
+                            name: toolName,
+                            description: `[MCP:${serverName}] ${spec.description ?? spec.name}`, // mark the origin in the manual
+                            parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
+                        },
+                    },
+                    run: async (args) => client.callTool(spec.name, args), // dispatch routes here; the permission gate ran first
+                };
+                registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
+            }
+            emit("agent_mcp_connected", { server: serverName, tools: specs.length, transport: def.url ? "http" : "stdio" });
+            console.log(chalk.dim(`(mcp: ${serverName} — ${specs.length} tools${def.url ? " over http" : ""})`)); // visible at startup
+        }
+        catch (err) {
+            client.kill(); // don't leak the process/session
+            emit("agent_mcp_failed", { server: serverName });
+            console.error(chalk.yellow(`  [mcp] ${serverName} failed to start (skipped): ${err.message}`)); // loud, but not fatal
+        }
+    }
+    return () => clients.forEach((c) => c.kill()); // the caller calls this on exit
+}

package/dist/memory.js

@@ -0,0 +1,186 @@
+import fs from "node:fs"; // memory lives in a file on disk
+import path from "node:path"; // path joining
+// Long-term memory: facts the agent should carry ACROSS sessions, not just
+// within one conversation. Session persistence (Day 12) restores "what we were
+// talking about"; this restores "what I should always know about this project".
+//
+// One Markdown file, project-local, human-readable and human-editable. Not a
+// vector database, not embeddings: a file you can open, read, and fix.
+//
+// Two ways facts get in: the model calls `remember` explicitly, OR — when
+// auto-extract is on — after each turn a cheap model call reads the conversation
+// and saves what's worth keeping (especially turns where the USER corrected the
+// assistant: 90% the model gets right isn't worth saving, the 10% it got wrong
+// and was corrected on is gold). Every fact is TYPED so the model can tell "this
+// is who the user is" from "this is a correction" from "this is a project fact".
+export const MEMORY_PATH = path.resolve(".mini-agent", "MEMORY.md");
+// The four memory types (handbook §17). feedback is the most valuable.
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+// Bounds, because unbounded memory dilutes the model's attention (Ch6: too many
+// rules → worse compliance) and grows the cached prefix forever. On overflow we
+// drop the OLDEST — recent facts are likelier still true.
+const MAX_ENTRIES = 40; // at most this many remembered facts
+const MAX_BYTES = 12_000; // ...and at most this many bytes total
+const HEADER = "# mini-agent long-term memory\n# One fact per line: - [type] fact. Injected at session start. Edit freely.\n";
+// Coerce any string to a valid type, defaulting to "project".
+function asType(t) {
+    return MEMORY_TYPES.includes(t ?? "") ? t : "project";
+}
+// Parse one bullet's text into a typed entry. "[feedback] foo" → feedback; a
+// bare "foo" (legacy / hand-written) → project.
+function parseEntry(text) {
+    const m = text.match(/^\[(\w+)\]\s*(.*)$/);
+    if (m && MEMORY_TYPES.includes(m[1]))
+        return { type: m[1], fact: m[2].trim() };
+    return { type: "project", fact: text.trim() };
+}
+// Read facts WITH their types. The fiddly parsing lives here.
+export function readMemoryTyped() {
+    try {
+        return fs
+            .readFileSync(MEMORY_PATH, "utf8")
+            .split("\n")
+            .filter((l) => l.startsWith("- "))
+            .map((l) => parseEntry(l.slice(2).trim()))
+            .filter((e) => e.fact);
+    }
+    catch {
+        return []; // no memory file yet — fine
+    }
+}
+// Read just the fact text (no type). Kept for callers that only want the facts.
+export function readMemory() {
+    return readMemoryTyped().map((e) => e.fact);
+}
+// The block injected into the system message, grouped by type so the model can
+// weigh "a correction" differently from "a project fact". Empty when there's
+// nothing, so the cached prefix stays clean for projects that never use it.
+export function memoryContext() {
+    const entries = readMemoryTyped();
+    if (!entries.length)
+        return "";
+    const labels = {
+        user: "About the user",
+        feedback: "Guidance & corrections the user gave you (follow these)",
+        project: "Project facts & decisions",
+        reference: "References",
+    };
+    let out = "\n\nLong-term project memory (background from earlier sessions; verify against the code before relying on a specific claim):";
+    for (const type of MEMORY_TYPES) {
+        const group = entries.filter((e) => e.type === type);
+        if (group.length)
+            out += `\n[${labels[type]}]\n${group.map((e) => `- ${e.fact}`).join("\n")}`;
+    }
+    return out;
+}
+// Append a typed fact, then enforce the caps. Self-healing: every write re-applies
+// the bounds, so the file can never grow past them even if hand-edited huge.
+export function addFact(fact, type = "project") {
+    const clean = fact.replace(/\s+/g, " ").trim(); // one line, normalized whitespace
+    if (!clean)
+        return "[error] nothing to remember (empty fact).";
+    const t = asType(type); // coerce a bad type to "project" so the on-disk format stays parseable
+    let entries = readMemoryTyped();
+    if (entries.some((e) => e.fact === clean))
+        return "Already remembered — no change."; // idempotent
+    entries.push({ type: t, fact: clean });
+    if (entries.length > MAX_ENTRIES)
+        entries = entries.slice(entries.length - MAX_ENTRIES); // drop oldest
+    let body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    while (Buffer.byteLength(HEADER + body, "utf8") > MAX_BYTES && entries.length > 1) {
+        entries.shift(); // still too big — drop the oldest until it fits
+        body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
+    }
+    fs.mkdirSync(path.dirname(MEMORY_PATH), { recursive: true });
+    fs.writeFileSync(MEMORY_PATH, HEADER + body + "\n", "utf8");
+    return `Remembered (${t}). (${entries.length} fact${entries.length === 1 ? "" : "s"} stored.)`;
+}
+// The tool the model calls to save something worth keeping.
+export const rememberTool = {
+    definition: {
+        type: "function",
+        function: {
+            name: "remember",
+            description: `Save a durable fact to long-term memory (persists across sessions, shown to you at the start of every future session).
+Use it for things still true next time: the build/test command, a gotcha, a convention, a decision and its reason, a user preference, or a correction the user gave you.
+Do NOT use it for transient state (current task, today's bug). Keep each fact to one sentence. Pick the right "type".`,
+            parameters: {
+                type: "object",
+                properties: {
+                    fact: { type: "string", description: "One durable fact, as a single sentence" },
+                    type: { type: "string", enum: [...MEMORY_TYPES], description: "user (who they are/prefs) · feedback (a correction/guidance) · project (a decision/convention/gotcha) · reference (a URL/doc)" },
+                },
+                required: ["fact"],
+            },
+        },
+    },
+    run: (args) => addFact(args.fact ?? "", asType(args.type)),
+};
+// ---- auto-extract -----------------------------------------------------------
+// After a turn, read the conversation and save what's worth keeping. The high-
+// frequency write path from §17 — so memory captures itself instead of relying
+// on the model to remember to call `remember`.
+const EXTRACT_SYSTEM = `You extract DURABLE memories from a slice of a coding-assistant conversation — facts worth carrying into FUTURE sessions.
+Output ONLY a JSON array. Each item: {"type": "...", "fact": "one sentence"}. No prose, no markdown fences.
+"type" is one of:
+- "user": who the user is — role, preferences, how they like to work.
+- "feedback": guidance or a CORRECTION the user gave the assistant. These are the MOST valuable — prioritize any turn where the user corrected or redirected the assistant.
+- "project": a goal, decision, convention, or non-obvious gotcha about THIS project.
+- "reference": a pointer to an external resource (a URL, a doc, a ticket).
+Do NOT save: transient task state, the bug currently being fixed, or anything obvious from reading the code. Keep each fact to one sentence.
+If nothing is worth saving, output [].`;
+// Parse the model's extraction output into typed entries. Lenient: finds the
+// JSON array even if wrapped in prose/fences, drops malformed items. Pure.
+export function parseExtractedMemories(text) {
+    const m = text.match(/\[[\s\S]*\]/); // the first […] — tolerate surrounding chatter
+    if (!m)
+        return [];
+    let arr;
+    try {
+        arr = JSON.parse(m[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(arr))
+        return [];
+    return arr
+        .filter((x) => !!x && typeof x === "object")
+        .filter((x) => typeof x.fact === "string" && x.fact.trim())
+        .map((x) => ({ type: asType(x.type), fact: String(x.fact).replace(/\s+/g, " ").trim() }));
+}
+// Build the transcript handed to the extractor: the last few user/assistant
+// turns (string content only), each capped, so the extraction stays cheap.
+function buildTranscript(messages) {
+    const turns = messages
+        .filter((m) => (m.role === "user" || m.role === "assistant") && typeof m.content === "string" && m.content.trim())
+        .slice(-12) // recent context is what matters
+        .map((m) => `${m.role}: ${String(m.content).split("\n\n[Referenced files")[0].slice(0, 600)}`);
+    return turns.join("\n\n");
+}
+// Run one extraction pass: a single (cheap) model call, parse, save. Returns the
+// facts it saved. Never throws — a failed extraction must not break the session.
+export async function extractMemories(client, model, messages) {
+    const transcript = buildTranscript(messages);
+    if (!transcript.trim())
+        return [];
+    let text = "";
+    try {
+        const res = await client.chat.completions.create({
+            model,
+            messages: [
+                { role: "system", content: EXTRACT_SYSTEM },
+                { role: "user", content: transcript },
+            ],
+            stream: false,
+        });
+        text = res.choices?.[0]?.message?.content ?? "";
+    }
+    catch {
+        return []; // network/model error — skip silently, try again next turn
+    }
+    const extracted = parseExtractedMemories(text);
+    for (const e of extracted)
+        addFact(e.fact, e.type); // addFact dedups internally
+    return extracted;
+}

package/dist/mentions.js

@@ -0,0 +1,62 @@
+import fs from "node:fs"; // read referenced files
+import path from "node:path"; // resolve mention paths
+import { checkPermission } from "./permissions.js"; // reuse the read_file gate — secret files must never leak in
+// @file mentions: let the user pull a file into the conversation just by naming
+// it — "explain @src/loop.ts" attaches the file's content so the model sees it
+// without a separate read_file round-trip. The point is convenience, but the
+// SAME rule still holds: a secret file (.env, *.pem) must never enter the
+// context. So every mention is routed through the read_file permission gate
+// (Day 4) — if it would deny a read, the mention is refused, not read.
+// @ must start the token (line start or after whitespace) so emails (a@b) and
+// npm scopes inside words don't trigger. The path runs to the next space; we
+// trim trailing sentence punctuation so "see @cart.js." doesn't include the dot.
+const MENTION_RE = /(?:^|\s)@(\S+)/g;
+const MAX_MENTION_BYTES = 100_000; // a referenced file bigger than this is truncated
+// Pull the raw @tokens out of a line (trailing , ; : ! ? ) stripped).
+export function findMentions(line) {
+    const out = [];
+    for (const m of line.matchAll(MENTION_RE)) {
+        const raw = m[1].replace(/[.,;:!?)\]]+$/, ""); // drop trailing punctuation, keep inner dots (cart.js)
+        if (raw)
+            out.push(raw);
+    }
+    return out;
+}
+// Resolve one mention to a file we may attach. Never throws.
+function resolveMention(raw) {
+    const abs = path.resolve(raw);
+    // The gate decides if a read is allowed; a secret file comes back "deny".
+    if (checkPermission("read_file", JSON.stringify({ path: raw })).decision === "deny") {
+        return { raw, path: abs, status: "denied" };
+    }
+    try {
+        const stat = fs.statSync(abs);
+        if (stat.isDirectory())
+            return { raw, path: abs, status: "dir" };
+        let content = fs.readFileSync(abs, "utf8");
+        if (content.length > MAX_MENTION_BYTES)
+            content = content.slice(0, MAX_MENTION_BYTES) + `\n... (truncated, file is ${content.length} chars)`;
+        return { raw, path: abs, status: "ok", content };
+    }
+    catch {
+        return { raw, path: abs, status: "missing" }; // not a file — probably not a reference at all
+    }
+}
+// Expand a user line: find @mentions, attach the readable ones, and refuse the
+// secret ones out loud. Returns the augmented message (file blocks appended) and
+// the mention list (for the REPL to summarize). A line with no resolvable
+// mention is returned unchanged — @tokens that don't name a real file (an email,
+// a stray @) are ignored silently so we don't nag on every "@" in prose.
+export function expandMentions(line) {
+    const mentions = findMentions(line).map(resolveMention);
+    // Only attach files we actually read, and announce refusals (security-relevant).
+    // "missing"/"dir" are dropped silently — likely not file references.
+    const attach = mentions.filter((m) => m.status === "ok" || m.status === "denied");
+    if (!attach.length)
+        return { augmented: line, mentions };
+    const blocks = attach.map((m) => m.status === "ok"
+        ? `--- ${m.raw} ---\n${m.content}`
+        : `--- ${m.raw} (refused: secret file, not included) ---`);
+    const augmented = `${line}\n\n[Referenced files — the user attached these with @mentions]\n${blocks.join("\n\n")}`;
+    return { augmented, mentions };
+}

package/dist/menu.js

@@ -0,0 +1,154 @@
+import readline from "node:readline"; // raw-mode keypress events + the interface to pause
+import { renderMenu, MENU_HINT } from "./ui.js"; // the pure drawing + the footer hint
+import { initFormState, reduceForm, renderForm, collectAnswers } from "./form.js"; // the multi-question form
+// An arrow-key selection menu. The whole point: an approval is one keystroke
+// (↑/↓ then Enter), not "type y, then N, then realize you meant the other".
+// Selecting costs the user less than typing.
+//
+// Coordinating with the session's readline (which owns stdin) is the tricky
+// part: we pause it, switch stdin to raw mode, read keypresses ourselves, then
+// hand stdin back exactly as we found it. The `input` parameter is injected so
+// tests can drive it with a fake stream instead of a real terminal.
+//
+// Returns the chosen index, or -1 if cancelled (Esc / Ctrl+C) or not a TTY —
+// callers treat -1 as "no" (fail closed for an approval).
+export function promptSelect(rl, // the session's line reader, paused while we own the keys
+options, // the choices, top to bottom
+input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY)
+            return resolve(-1); // no interactive selection without a terminal — caller falls back
+        let selected = 0;
+        let done = false;
+        const wasRaw = input.isRaw === true; // the session's readline keeps stdin raw — restore THIS, don't force false
+        // Redraw the menu in place: move the cursor back up over the previous
+        // render (options + the one footer line), clear downward, reprint. The
+        // question above the menu stays put.
+        const lineCount = options.length + 1; // options, plus the hint footer
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up to the menu's top
+            process.stdout.write(`\x1b[J${renderMenu(options, selected)}\n${MENU_HINT}\n`); // clear down, repaint + hint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey); // stop listening
+            try {
+                input.setRawMode(wasRaw); // restore the prior mode — forcing false breaks the live readline → it closes → the REPL exits
+            }
+            catch {
+                /* not all streams support it; ignore */
+            }
+            rl.resume(); // the line reader takes over again
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            switch (key.name) {
+                case "up":
+                case "k":
+                    selected = (selected - 1 + options.length) % options.length; // wrap around the top
+                    draw(false);
+                    break;
+                case "down":
+                case "j":
+                    selected = (selected + 1) % options.length; // wrap around the bottom
+                    draw(false);
+                    break;
+                case "return":
+                case "enter":
+                    finish(selected); // commit the choice
+                    break;
+                case "escape":
+                    finish(-1); // bail
+                    break;
+                default:
+                    if (key.ctrl && key.name === "c")
+                        finish(-1); // Ctrl+C in raw mode arrives as a keypress, not a signal
+            }
+        };
+        try {
+            rl.pause(); // stop the line reader from turning our keystrokes into lines
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input); // turn raw bytes into named keys (real stdin only)
+            input.setRawMode(true); // keys arrive immediately, no Enter needed
+            input.resume(); // CRUCIAL: rl.pause() paused the stream — resume it or no keypresses reach us (menu hangs)
+            input.on("keypress", onKey);
+            draw(true); // first paint
+        }
+        catch {
+            finish(-1); // anything unexpected in setup → cancel, caller falls back to typing
+        }
+    });
+}
+// The multi-question form (Day 30): the agent asks several questions at once,
+// the user answers each and submits, and we hand back organized answers. Same
+// raw-mode borrow/return dance as promptSelect; the state machine is in form.ts.
+// Returns the answers, or null if cancelled / not a TTY.
+export function promptForm(rl, questions, input = process.stdin) {
+    return new Promise((resolve) => {
+        if (!input.isTTY || !questions.length)
+            return resolve(null); // no form without a terminal or questions
+        let state = initFormState(questions);
+        let done = false;
+        const wasRaw = input.isRaw === true; // restore this on exit, not false (see promptSelect)
+        const lineCount = renderForm(questions, state).split("\n").length; // constant for these questions
+        const draw = (first) => {
+            if (!first)
+                process.stdout.write(`\x1b[${lineCount}A`); // up over the whole form
+            process.stdout.write(`\x1b[J${renderForm(questions, state)}\n`); // clear down, repaint
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey);
+            try {
+                input.setRawMode(wasRaw); // restore prior mode; forcing false breaks the live readline → REPL exits
+            }
+            catch {
+                /* ignore */
+            }
+            rl.resume();
+            resolve(result);
+        };
+        const onKey = (_str, key) => {
+            if (!key || done)
+                return;
+            if (key.name === "up" || key.name === "k") {
+                state = reduceForm(questions, state, "up").state;
+                draw(false);
+            }
+            else if (key.name === "down" || key.name === "j" || key.name === "tab") {
+                state = reduceForm(questions, state, "down").state;
+                draw(false);
+            }
+            else if (key.name === "return" || key.name === "enter" || key.name === "space") {
+                const next = reduceForm(questions, state, "select");
+                state = next.state;
+                if (next.done)
+                    finish(collectAnswers(questions, state)); // submitted with all answered
+                else
+                    draw(false);
+            }
+            else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
+                finish(null); // cancel
+            }
+        };
+        try {
+            rl.pause();
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input);
+            input.setRawMode(true);
+            input.resume(); // resume the stream rl.pause() paused, or no keypresses reach the form
+            input.on("keypress", onKey);
+            draw(true);
+        }
+        catch {
+            finish(null);
+        }
+    });
+}