@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/tools/workflow.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/engine/tools/workflow.mjs — the Workflow and WorkflowStatus tools
+ * (workflow/runtime.mjs does the work).
+ *
+ * Workflow {script?, scriptPath?, args?, resumeFromRunId?} starts a run in the
+ * background and returns {runId, scriptPath}; the script's return value
+ * arrives in a later message. WorkflowStatus {run_id, block?, timeout?} reads
+ * a run's progress (phases, agents done/running/failed) or its result.
+ *
+ * Posture (as Task, CF-47): both are read-only to the permission engine. They
+ * touch no file or network themselves; every agent() child a script starts
+ * passes its own guard, clamped to the session's rules and mode, and is checked
+ * against `Task(<type>)` rules for its agent type.
+ *
+ * Tool descriptions are original (see docs/engine/clean-room.md).
+ * Authorship: written for Cohort Engine by the Cohort team, 2026-09-14.
+ *
+ * @module lib/engine/tools/workflow
+ */
+
+import { TASK_OUTPUT_MAX_TIMEOUT_MS } from "../agents/runtime.mjs";
+import { MAX_ITEMS } from "../workflow/sandbox.mjs";
+import { MAX_SCRIPT_BYTES } from "../workflow/meta.mjs";
+
+export const WORKFLOW_DESCRIPTION =
+  "Run a JavaScript orchestration script that coordinates several subagents in a fixed, repeatable way — fan-out and fan-in, staged pipelines, retries — in the background. " +
+  "The call returns {runId, scriptPath} at once; the script's return value arrives in a later message. WorkflowStatus reads progress meanwhile.\n\n" +
+  "The script's first statement must be `export const meta = { name: \"…\", description: \"…\", phases: [\"…\"] }` written as a plain literal (phases optional). " +
+  "The rest runs as the body of an async function (top-level await and return work), with these globals and nothing else (no require, import, process, fs, network, timers or console):\n" +
+  "- `await agent(prompt, {label, phase, schema, model, effort, isolation: \"worktree\", agentType})` runs a subagent on a self-contained prompt and resolves to its final text; with `schema` (a JSON Schema) to an object that matches it; null if the agent failed.\n" +
+  `- \`await parallel([() => agent(…), …])\` runs thunks together and waits for all; a failed one is null. At most ${MAX_ITEMS} items.\n` +
+  "- `await pipeline(items, async (prev, item, index) => …, …)` sends each item through the stages on its own (no waiting between items); a stage that throws makes that item null.\n" +
+  "- `phase(title)` names the current stage; `log(message)` records a progress note; `args` is the args value; `budget.total`, `budget.spent()`, `budget.remaining()` are tokens (total null = no limit).\n" +
+  "- `await workflow(ref, args)` runs another workflow script (a path, a run id, or a name in .cohort/workflows) and resolves to its return value; one level only.\n" +
+  "`Date.now()`, `new Date()` without an argument and `Math.random()` throw: pass anything time- or chance-dependent in `args`. The return value must be JSON. " +
+  `Scripts are limited to ${MAX_SCRIPT_BYTES} bytes.\n\n` +
+  "Every run keeps a journal. `resumeFromRunId` starts a new run that answers agent() calls matching the earlier run's completed calls from the journal at once and runs the rest live; " +
+  "pair it with `scriptPath` (for example the earlier run's saved script, edited) or `script` to change what follows.";
+
+/** @param {ReturnType<typeof import('../workflow/runtime.mjs').createWorkflowRuntime>} runtime */
+export function createWorkflowTools(runtime) {
+  const workflowTool = {
+    name: "Workflow",
+    readOnly: true,
+    description: WORKFLOW_DESCRIPTION,
+    input_schema: {
+      type: "object",
+      properties: {
+        script: { type: "string", description: "The workflow script's JavaScript source." },
+        scriptPath: { type: "string", description: "A file holding the script (relative to the project directory), instead of script." },
+        args: { description: "Any JSON value; the script reads it as `args`." },
+        resumeFromRunId: { type: "string", description: "An earlier run's id: its completed agent calls are replayed from its journal." },
+      },
+    },
+    /** @param {{script?:string, scriptPath?:string, args?:unknown, resumeFromRunId?:string}} input @param {any} ctx */
+    async run(input, ctx) {
+      const r = runtime.start(input, { toolUseId: ctx?.toolUseId ?? null, signal: ctx?.signal });
+      if (!r.ok) return { ok: false, error: `Workflow not started: ${r.error}` };
+      const resumed = r.resumedFrom ? ` It resumes ${r.resumedFrom}: ${r.replayable} completed agent call${r.replayable === 1 ? "" : "s"} can be replayed from its journal.` : "";
+      return {
+        ok: true,
+        content:
+          `${JSON.stringify({ runId: r.runId, scriptPath: r.scriptPath })}\n\n` +
+          `Started workflow "${r.name}" as ${r.runId} in the background.${resumed} Its result arrives in a later message. ` +
+          `WorkflowStatus {"run_id":"${r.runId}"} shows progress; the script is saved at ${r.scriptPath} for a later resume.`,
+      };
+    },
+  };
+
+  const statusTool = {
+    name: "WorkflowStatus",
+    readOnly: true,
+    description:
+      "Show a workflow run's progress — status, phases, agents done, running and failed, recent log lines — or, once it has ended, its result. " +
+      "With `block`, wait up to `timeout` milliseconds for it to end first. A run whose result is read here is not reported again later.",
+    input_schema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string", description: "The run id Workflow returned." },
+        block: { type: "boolean", description: "Wait for the run to end. Default false." },
+        timeout: { type: "integer", minimum: 0, maximum: TASK_OUTPUT_MAX_TIMEOUT_MS, description: "How long to wait, in milliseconds (default 30000)." },
+      },
+      required: ["run_id"],
+    },
+    /** @param {{run_id:string, block?:boolean, timeout?:number}} input @param {any} ctx */
+    async run(input, ctx) {
+      const r = await runtime.status(input.run_id, { block: input.block === true, timeoutMs: Math.min(input.timeout ?? 30_000, TASK_OUTPUT_MAX_TIMEOUT_MS), signal: ctx?.signal });
+      if (!r.ok) return r;
+      const body = JSON.stringify(r.view, null, 2);
+      return { ok: true, content: r.result === null ? body : `${body}\n\nResult:\n${r.result}` };
+    },
+  };
+
+  return [workflowTool, statusTool];
+}

package/lib/engine/tools/write.mjs

@@ -0,0 +1,76 @@
+/**
+ * lib/engine/tools/write.mjs — the Write tool.
+ *
+ * Input contract: `{ file_path, content }`. Creates parent directories. An
+ * EXISTING file may only be overwritten after it has been Read in this run and
+ * has not changed since — the model must not clobber what it has not seen.
+ *
+ * The write itself goes through `writeFileAtomic` (temp → fsync → rename), and
+ * keeps an existing file's permission bits, so an executable script stays
+ * executable after a rewrite.
+ *
+ * @module lib/engine/tools/write
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "../../fs-atomic.mjs";
+
+/**
+ * Shared freshness check for Write and Edit (pure over its inputs).
+ * @param {string} file
+ * @param {{ mtimeMs:number } | null} stat   current stat, null when absent
+ * @param {Map<string, {mtimeMs:number}>} fileState
+ * @returns {{ ok:true } | { ok:false, error:string }}
+ */
+export function checkFresh(file, stat, fileState) {
+  if (!stat) return { ok: true };
+  const seen = fileState.get(file);
+  if (!seen) return { ok: false, error: `${file} already exists. Read it first, then change it.` };
+  if (stat.mtimeMs > seen.mtimeMs) {
+    return { ok: false, error: `${file} changed on disk after it was read. Read it again before changing it.` };
+  }
+  return { ok: true };
+}
+
+export const writeTool = {
+  name: "Write",
+  readOnly: false,
+  description:
+    "Create a file, or replace a file's entire contents. `file_path` must be absolute; missing parent directories are created. " +
+    "An existing file must be Read first. Prefer Edit for changing part of a file.",
+  input_schema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "Absolute path of the file to write." },
+      content: { type: "string", description: "The complete new contents of the file." },
+    },
+    required: ["file_path", "content"],
+  },
+
+  /**
+   * @param {{file_path:string, content:string}} input
+   * @param {import('./index.mjs').ToolContext} ctx
+   */
+  async run(input, ctx) {
+    const file = input.file_path;
+    if (!path.isAbsolute(file)) return { ok: false, error: `file_path must be absolute, got "${file}"` };
+    let st = null;
+    try {
+      st = statSync(file);
+    } catch {
+      st = null; // absent: a create, which needs no prior Read
+    }
+    if (st?.isDirectory()) return { ok: false, error: `${file} is a directory.` };
+    const fresh = checkFresh(file, st, ctx.fileState);
+    if (!fresh.ok) return fresh;
+    try {
+      writeFileAtomic(file, input.content, st ? { mode: st.mode & 0o7777 } : {});
+    } catch (e) {
+      return { ok: false, error: `Could not write ${file}: ${e instanceof Error ? e.message : e}` };
+    }
+    ctx.fileState.set(file, { mtimeMs: statSync(file).mtimeMs });
+    const lines = input.content === "" ? 0 : input.content.split("\n").length;
+    return { ok: true, content: `${st ? "Updated" : "Created"} ${file} (${lines} lines).` };
+  },
+};

package/lib/engine/tui/line-editor.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/engine/tui/line-editor.mjs — the session terminal's input line.
+ *
+ * Fed raw terminal bytes (as strings), it keeps the line being typed and
+ * reports what the user did:
+ *
+ *   Enter            submit the line (an empty line is not submitted)
+ *   \ then Enter     continue on a new line
+ *   paste            keeps its line breaks: bracketed paste (ESC[200~ … ESC[201~),
+ *                    or — for terminals without it — line breaks inside one chunk
+ *                    of input are text; only a line break that ends the chunk submits
+ *   Backspace        delete a character;  Ctrl-U clears the line;  Ctrl-W deletes a word
+ *   Ctrl-C           `interrupt` (the line, if any, is cleared)
+ *   Ctrl-D           `eof` on an empty line
+ *   other escape sequences (arrows, function keys) are ignored
+ *
+ * Pure state; no I/O.
+ *
+ * @module lib/engine/tui/line-editor
+ */
+
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+
+/**
+ * @typedef {{type:'submit', text:string}|{type:'interrupt', hadText:boolean}|{type:'eof'}} EditorAction
+ */
+
+export function createLineEditor() {
+  let buffer = "";
+  let pasting = false;
+  /** An escape sequence split across chunks. */
+  let pendingEscape = "";
+
+  /** @param {string} s @returns {number} length of a complete escape sequence at the start, 0 if incomplete, -1 if not one */
+  const escapeLength = (s) => {
+    if (s.startsWith(PASTE_START) || s.startsWith(PASTE_END)) return PASTE_START.length;
+    if (s.length < 2) return 0;
+    if (s[1] === "[") {
+      for (let i = 2; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0x40 && c <= 0x7e) return i + 1;
+      }
+      return s.length > 16 ? 1 : 0;
+    }
+    if (s[1] === "O") return s.length >= 3 ? 3 : 0;
+    return 2; // ESC + one key (Alt-x)
+  };
+
+  return {
+    get buffer() {
+      return buffer;
+    },
+    /** The line as a single row for display. */
+    display() {
+      const rows = buffer.split("\n");
+      return rows.length === 1 ? buffer : `${rows[rows.length - 1]}  [+${rows.length - 1} line${rows.length > 2 ? "s" : ""} above]`;
+    },
+    clear() {
+      buffer = "";
+    },
+    /**
+     * @param {string} chunk
+     * @returns {EditorAction[]}
+     */
+    feed(chunk) {
+      /** @type {EditorAction[]} */
+      const actions = [];
+      let s = pendingEscape + String(chunk);
+      pendingEscape = "";
+      const chunkHasText = /[^\r\n]/.test(s.replace(/\x1b\[[0-9;?]*[@-~]/g, ""));
+      let i = 0;
+      while (i < s.length) {
+        const ch = s[i];
+        if (ch === "\x1b") {
+          const rest = s.slice(i);
+          if (rest.startsWith(PASTE_START)) {
+            pasting = true;
+            i += PASTE_START.length;
+            continue;
+          }
+          if (rest.startsWith(PASTE_END)) {
+            pasting = false;
+            i += PASTE_END.length;
+            continue;
+          }
+          const n = escapeLength(rest);
+          if (n === 0) {
+            pendingEscape = rest;
+            break;
+          }
+          i += n;
+          continue;
+        }
+        if (pasting) {
+          buffer += ch === "\r" ? "\n" : ch;
+          i += ch === "\r" && s[i + 1] === "\n" ? 2 : 1; // CRLF counts once
+          continue;
+        }
+        if (ch === "\r" || ch === "\n") {
+          // CRLF counts once.
+          if (ch === "\r" && s[i + 1] === "\n") i++;
+          const endsChunk = !/[^\r\n]/.test(s.slice(i + 1).replace(/\x1b\[[0-9;?]*[@-~]/g, ""));
+          if (!endsChunk && chunkHasText) {
+            buffer += "\n"; // a line break inside pasted text
+          } else if (buffer.endsWith("\\")) {
+            buffer = `${buffer.slice(0, -1)}\n`;
+          } else {
+            const text = buffer;
+            buffer = "";
+            if (text.trim() !== "") actions.push({ type: "submit", text });
+          }
+          i++;
+          continue;
+        }
+        if (ch === "\x03") {
+          actions.push({ type: "interrupt", hadText: buffer !== "" });
+          buffer = "";
+        } else if (ch === "\x04") {
+          if (buffer === "") actions.push({ type: "eof" });
+        } else if (ch === "\x7f" || ch === "\b") {
+          buffer = [...buffer].slice(0, -1).join("");
+        } else if (ch === "\x15") {
+          buffer = "";
+        } else if (ch === "\x17") {
+          buffer = buffer.replace(/\S+\s*$|\s+$/, "");
+        } else if (ch === "\t") {
+          buffer += "  ";
+        } else if (ch.charCodeAt(0) >= 0x20) {
+          buffer += ch;
+        }
+        i++;
+      }
+      return actions;
+    },
+  };
+}

package/lib/engine/tui/render.mjs

@@ -0,0 +1,86 @@
+/**
+ * lib/engine/tui/render.mjs — the session terminal's lines, as text. Pure.
+ *
+ * The look is the engine's own: a `»` input prompt, one compact line per tool
+ * call (`▹ Tool · what`), one status line per result (`ok ·` / `failed ·`),
+ * a footer rule per turn, and marked lines for approvals, messages and wakeups.
+ *
+ * @module lib/engine/tui/render
+ */
+
+export const PROMPT = "» ";
+
+/** One line of at most `max` characters; line breaks shown as ⏎. @param {unknown} s @param {number} [max] */
+export function oneLine(s, max = 96) {
+  const t = String(s ?? "")
+    .replace(/\s*\n\s*/g, " ⏎ ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+const INPUT_KEYS = ["command", "file_path", "notebook_path", "pattern", "url", "query", "skill", "description", "prompt", "bash_id", "shell_id", "task_id"];
+
+/** What a tool call is about, in a few words. @param {string} name @param {unknown} input */
+export function summarizeToolInput(name, input) {
+  const i = input && typeof input === "object" ? /** @type {Record<string, unknown>} */ (input) : {};
+  if (name === "SendMessage" && typeof i.to === "string") return oneLine(`to ${i.to}: ${i.summary ?? i.message ?? ""}`, 80);
+  if (name === "ScheduleWakeup") return oneLine(`in ${i.delaySeconds}s: ${i.reason ?? i.prompt ?? ""}`, 80);
+  for (const k of INPUT_KEYS) if (typeof i[k] === "string" && i[k] !== "") return oneLine(i[k], 80);
+  return Object.keys(i).length > 0 ? oneLine(JSON.stringify(i), 80) : "";
+}
+
+/** @param {string} name @param {unknown} input */
+export function toolCallLine(name, input) {
+  const what = summarizeToolInput(name, input);
+  return `  ▹ ${name}${what ? ` · ${what}` : ""}`;
+}
+
+/** @param {unknown} content */
+function resultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((b) => (b && typeof b.text === "string" ? b.text : "")).join("\n");
+  return "";
+}
+
+/** @param {{content?:unknown, is_error?:boolean}} block */
+export function toolResultLine(block) {
+  const text = resultText(block.content).trim();
+  const lines = text === "" ? [] : text.split("\n");
+  const first = oneLine(lines.find((l) => l.trim() !== "") ?? "", 80);
+  if (block.is_error) return `    failed · ${first || "(no reason given)"}`;
+  const more = lines.length > 1 ? ` (+${lines.length - 1} lines)` : "";
+  return `    ok · ${first || "(no output)"}${more}`;
+}
+
+/** @param {any} r  a stream-json result event */
+export function turnFooter(r) {
+  const parts = [`${r.num_turns ?? 0} model turn${r.num_turns === 1 ? "" : "s"}`];
+  if (Number.isFinite(r.duration_ms)) parts.push(`${(r.duration_ms / 1000).toFixed(1)}s`);
+  if (typeof r.total_cost_usd === "number") parts.push(`$${r.total_cost_usd.toFixed(4)}`);
+  if (r.is_error) parts.push(`${r.cohort?.stop?.kind ?? r.subtype ?? "error"}: ${oneLine(r.result, 100)}`);
+  return `  ── ${parts.join(" · ")}`;
+}
+
+/** @param {{toolName:string, input:unknown, reason:string, agentId?:string|null}} q */
+export function askLine(q) {
+  const what = summarizeToolInput(q.toolName, q.input);
+  const who = q.agentId ? ` (subagent ${q.agentId})` : "";
+  const scope = q.agentId ? `for ${q.toolName} from this subagent` : `for ${q.toolName} in this session`;
+  return `  ? ${q.toolName}${what ? ` · ${what}` : ""}${who}\n    ${oneLine(q.reason, 120)}. Allow it?  y yes · n no · a always ${scope} — then Enter`;
+}
+
+/** The answer line under an ask. @param {string} typed */
+export function askPromptLine(typed) {
+  return `    answer › ${typed}`;
+}
+
+/** @param {{from:string|null, summary?:string|null, text:string, status:string}} m */
+export function inboundLine(m) {
+  return `  ✉ ${m.from ?? "message"}: ${oneLine(m.summary ?? m.text, 80)}${m.status === "queued" ? "  (after the current turn)" : ""}`;
+}
+
+/** @param {{name:string, sessionId:string}} o */
+export function bannerLine({ name, sessionId }) {
+  return `cohort session ${name} (${sessionId})\n  Enter sends · \\ then Enter for a new line · Ctrl-C interrupts · Ctrl-D exits`;
+}

package/lib/engine/tui/tui.mjs

@@ -0,0 +1,274 @@
+/**
+ * lib/engine/tui/tui.mjs — the minimal interactive terminal for `cohort session`.
+ *
+ * Reads raw keys from `input` (a TTY in raw mode, bracketed paste on) through
+ * the line editor, and renders the session's stream-json events on `output`:
+ * assistant text as it streams, a compact line per tool call and per result, a
+ * footer per turn. While a turn runs the prompt is hidden; what is typed and
+ * sent then waits for the next turn.
+ *
+ * Approvals are asked inline, one at a time (later asks wait in order). An
+ * answer is a word typed on its own line — `y`, `n` or `a`, then Enter — so
+ * nothing typed for another purpose can grant a tool:
+ *   · keys arriving within `askGraceMs` of the ask appearing are dropped (they
+ *     were already on their way — type-ahead, not an answer);
+ *   · a chunk of more than one key (a paste, a burst of buffered input) never
+ *     answers and clears what was typed, and bracketed paste is ignored whole;
+ *   · a line that is not y / yes / n / no / a / always answers nothing;
+ *   · Ctrl-C or Esc on its own answers no.
+ * The line editor's half-typed text is kept and comes back after the answer.
+ *
+ * The edge is only `input`/`output` (and the clock); tests drive it with fake
+ * streams.
+ *
+ * @module lib/engine/tui/tui
+ */
+
+import { createLineEditor } from "./line-editor.mjs";
+import { PROMPT, askLine, askPromptLine, bannerLine, inboundLine, oneLine, toolCallLine, toolResultLine, turnFooter } from "./render.mjs";
+
+export const ASK_GRACE_MS = 400;
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+/** One printable key, optionally followed by Enter; or Enter alone. */
+const ONE_KEY_RE = /^([^\x00-\x1f\x7f])?(\r\n|\r|\n)?$/;
+
+/**
+ * @typedef {'allow'|'deny'|'always'} AskAnswer
+ * @typedef {{q:{toolName:string, input:unknown, reason:string, agentId?:string|null}, resolve:(a:AskAnswer)=>void, shownAt:number, typed:string}} PendingAsk
+ */
+
+/**
+ * @param {{input:NodeJS.ReadableStream & {setRawMode?:(b:boolean)=>void, isTTY?:boolean},
+ *          output:{write:(s:string)=>unknown, isTTY?:boolean},
+ *          name:string, sessionId:string,
+ *          onSubmit:(text:string)=>string, onInterrupt:()=>void, onExit:()=>void, color?:boolean,
+ *          askGraceMs?:number, now?:()=>number}} o
+ */
+export function createTui({ input, output, name, sessionId, onSubmit, onInterrupt, onExit, color = Boolean(output.isTTY), askGraceMs = ASK_GRACE_MS, now = Date.now }) {
+  const editor = createLineEditor();
+  let busy = false;
+  let promptShown = false;
+  let textOpen = false;
+  let sawDelta = false;
+  let closed = false;
+  /** Inside a bracketed paste that arrived while an ask was pending. */
+  let askPasting = false;
+  /** @type {PendingAsk[]} the first is on screen */
+  const asks = [];
+
+  const dim = (/** @type string */ s) => (color ? `\x1b[2m${s}\x1b[22m` : s);
+  const write = (/** @type string */ s) => {
+    if (!closed) output.write(s);
+  };
+  const clearPrompt = () => {
+    if (promptShown) write("\r\x1b[2K");
+    promptShown = false;
+  };
+  const endText = () => {
+    if (textOpen) write("\n");
+    textOpen = false;
+  };
+  const line = (/** @type string */ s) => {
+    clearPrompt();
+    endText();
+    write(`${s}\n`);
+  };
+  const drawPrompt = () => {
+    if (closed) return;
+    const head = asks[0];
+    if (head) {
+      write(`\r\x1b[2K${askPromptLine(head.typed)}`);
+      promptShown = true;
+      return;
+    }
+    if (busy) return;
+    write(`\r\x1b[2K${PROMPT}${editor.display()}`);
+    promptShown = true;
+  };
+  const showHead = () => {
+    const head = asks[0];
+    if (!head) return;
+    head.shownAt = now();
+    head.typed = "";
+    line(askLine(head.q));
+  };
+
+  /** @param {PendingAsk} item @param {AskAnswer} a */
+  const settle = (item, a) => {
+    const i = asks.indexOf(item);
+    if (i === -1) return;
+    asks.splice(i, 1);
+    if (i === 0) line(dim(a === "allow" ? "    allowed" : a === "always" ? `    allowed ${item.q.agentId ? "for this subagent" : "for this session"}` : "    not allowed"));
+    item.resolve(a);
+    if (i === 0) showHead();
+    drawPrompt();
+  };
+
+  /** Input while an ask is on screen. @param {string} s */
+  const onAskInput = (s) => {
+    const head = asks[0];
+    if (s === "\x03" || s === "\x1b") return settle(head, "deny");
+    if (askPasting) {
+      if (s.includes(PASTE_END)) askPasting = false;
+      return;
+    }
+    if (s.includes(PASTE_START)) {
+      askPasting = !s.slice(s.indexOf(PASTE_START)).includes(PASTE_END);
+      head.typed = "";
+      return drawPrompt();
+    }
+    if (now() - head.shownAt < askGraceMs) return;
+    if (s === "\x7f" || s === "\b") {
+      head.typed = head.typed.slice(0, -1);
+      return drawPrompt();
+    }
+    if (s.startsWith("\x1b")) return;
+    const m = ONE_KEY_RE.exec(s);
+    if (!m || (!m[1] && !m[2])) {
+      // More than one key at once: pasted or buffered text, never an answer.
+      head.typed = "";
+      return drawPrompt();
+    }
+    if (m[1] && head.typed.length < 16) head.typed += m[1];
+    if (!m[2]) return drawPrompt();
+    const word = head.typed.trim().toLowerCase();
+    head.typed = "";
+    if (word === "y" || word === "yes") return settle(head, "allow");
+    if (word === "n" || word === "no") return settle(head, "deny");
+    if (word === "a" || word === "always") return settle(head, "always");
+    if (word) line(dim("    answer y, n or a, then Enter"));
+    drawPrompt();
+  };
+
+  const onData = (/** @type {Buffer|string} */ chunk) => {
+    const s = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    if (asks.length > 0) return onAskInput(s);
+    for (const act of editor.feed(s)) {
+      if (act.type === "submit") {
+        clearPrompt();
+        write(`${PROMPT}${act.text.replace(/\n/g, "\n  ")}\n`);
+        const status = onSubmit(act.text);
+        if (status === "queued") line(dim("  (sent after the current turn)"));
+      } else if (act.type === "interrupt") {
+        if (act.hadText) continue;
+        if (busy) {
+          line(dim("  (interrupting)"));
+          onInterrupt();
+        } else {
+          line(dim("  (Ctrl-D exits)"));
+        }
+      } else if (act.type === "eof") {
+        line(dim("  (exiting)"));
+        onExit();
+      }
+    }
+    drawPrompt();
+  };
+
+  return {
+    start() {
+      input.setRawMode?.(true);
+      input.on("data", onData);
+      input.resume?.();
+      write("\x1b[?2004h");
+      line(dim(bannerLine({ name, sessionId })));
+      drawPrompt();
+    },
+    /** @param {boolean} b */
+    setBusy(b) {
+      busy = b;
+      if (b) clearPrompt();
+      else endText();
+      drawPrompt();
+    },
+    /** Render one stream-json event. @param {any} ev */
+    event(ev) {
+      const top = ev.parent_tool_use_id == null;
+      if (ev.type === "stream_event" && top) {
+        const e = ev.event;
+        if (e?.type === "message_start") sawDelta = false;
+        if (e?.type === "content_block_delta" && e.delta?.type === "text_delta" && e.delta.text) {
+          clearPrompt();
+          write(e.delta.text);
+          textOpen = true;
+          sawDelta = true;
+        }
+      } else if (ev.type === "assistant") {
+        const blocks = Array.isArray(ev.message?.content) ? ev.message.content : [];
+        if (top && !sawDelta) {
+          const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("");
+          if (text) {
+            clearPrompt();
+            write(text);
+            textOpen = true;
+          }
+        }
+        for (const b of blocks.filter((b) => b.type === "tool_use")) line(top ? toolCallLine(b.name, b.input) : dim(`  ${toolCallLine(b.name, b.input)}`));
+        if (top) sawDelta = false;
+      } else if (ev.type === "user" && top) {
+        for (const b of ev.message?.content ?? []) if (b.type === "tool_result") line(dim(toolResultLine(b)));
+      } else if (ev.type === "result") {
+        if (ev.cohort?.error?.code === "no_input") return;
+        endText();
+        line(dim(turnFooter(ev)));
+      } else if (ev.type === "system" && ev.subtype === "init") {
+        line(dim(`  ${ev.model} · ${Array.isArray(ev.tools) ? ev.tools.length : 0} tools · ${ev.permission_mode}`));
+      }
+      drawPrompt();
+    },
+    /** A message that arrived on the control socket. @param {{from:string|null, summary?:string|null, text:string, status:string}} m */
+    inbound(m) {
+      line(inboundLine(m));
+      drawPrompt();
+    },
+    /** A diagnostic line (the run's stderr, a wakeup). @param {string} text */
+    note(text) {
+      for (const l of String(text).trimEnd().split("\n")) line(dim(`  ${oneLine(l, 400)}`));
+      drawPrompt();
+    },
+    /**
+     * Ask whether a tool call may run. Asks are answered one at a time, in order.
+     * @param {{toolName:string, input:unknown, reason:string, signal?:AbortSignal, agentId?:string|null}} q
+     * @returns {Promise<AskAnswer>}
+     */
+    ask(q) {
+      if (closed) return Promise.resolve("deny");
+      return new Promise((resolve) => {
+        /** @type {PendingAsk} */
+        const item = {
+          q,
+          shownAt: now(),
+          typed: "",
+          resolve: (a) => {
+            q.signal?.removeEventListener("abort", onAbort);
+            resolve(a);
+          },
+        };
+        const onAbort = () => settle(item, "deny");
+        if (q.signal?.aborted) return resolve("deny");
+        q.signal?.addEventListener("abort", onAbort, { once: true });
+        asks.push(item);
+        if (asks.length === 1) {
+          showHead();
+          drawPrompt();
+        }
+      });
+    },
+    close() {
+      if (closed) return;
+      while (asks.length > 0) settle(asks[0], "deny");
+      endText();
+      clearPrompt();
+      write("\x1b[?2004l");
+      closed = true;
+      input.off?.("data", onData);
+      input.setRawMode?.(false);
+      input.pause?.();
+    },
+    /** For tests. */
+    get editor() {
+      return editor;
+    },
+  };
+}