@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/utility/src/answer/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @pi-unipi/utility — /unipi:answer
+ *
+ * Answer the questions in the agent's last reply without scrolling:
+ *   editor — pi's editor pre-filled with a Q/A template (Ctrl+G → $EDITOR)
+ *   web    — a local form with the full reply beside the answer boxes
+ * `/unipi:answer editor|web` overrides the configured default. Over SSH the
+ * web form prints a port-forward command instead of opening a browser.
+ */
+
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { ExtensionEditorComponent, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { boxInnerWidth, frameOverlay, HUB_OVERLAY_OPTIONS, hubBoldText as bold, hubDimText as dim, hubExactRow, hubTheme, setHubTheme, UNIPI_PREFIX, UTILITY_COMMANDS } from "@pi-unipi/core";
+import { readUtilSettings } from "../settings.js";
+import { ReplyPanel, type ReplyPanelResult } from "./reply.js";
+import { buildTemplate, composeAnswers, extractQuestions, messageText, parseTemplate } from "./extract.js";
+import { startWebForm, type WebAnswer } from "./web.js";
+
+/** Fixed port tried first over SSH, so one `ssh -L` keeps working. */
+export const SSH_DEFAULT_PORT = 47321;
+
+export function isSsh(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT);
+}
+
+function lastAssistantText(ctx: ExtensionContext): string {
+  const sm = ctx.sessionManager as unknown as { getBranch?: () => unknown[]; getEntries: () => unknown[] };
+  const entries = (sm.getBranch?.() ?? sm.getEntries()) as Array<{ type?: string; message?: { role?: string; content?: unknown } }>;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const m = entries[i]!.message;
+    if (entries[i]!.type === "message" && m?.role === "assistant") {
+      const text = messageText(m.content).trim();
+      if (text) return text;
+    }
+  }
+  return "";
+}
+
+function openBrowser(url: string): void {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {}).unref();
+  } catch {
+    // no browser — the URL is on screen
+  }
+}
+
+/**
+ * pi's own editor dialog (Enter submits, Ctrl+G opens $EDITOR), hosted here so
+ * the cursor can start on the first answer line instead of the end.
+ */
+function answerEditor(ctx: ExtensionContext, title: string, template: string): Promise<string | undefined> {
+  const target = template.split("\n").findIndex((l) => l.startsWith("A1:"));
+  return ctx.ui.custom<string | undefined>((tui, _theme, keybindings, done) => {
+    const component = new ExtensionEditorComponent(tui, keybindings, title, template, (text: string) => done(text), () => done(undefined));
+    const editor = (component as unknown as { editor: { getCursor(): { line: number }; getText(): string; handleInput(d: string): void } }).editor;
+    const goTo = (line: number) => {
+      for (let i = 0; i < 500 && editor.getCursor().line > line; i++) editor.handleInput("\x1b[A");
+      for (let i = 0; i < 500 && editor.getCursor().line < line; i++) editor.handleInput("\x1b[B");
+      editor.handleInput("\x1b[F");
+    };
+    if (target >= 0) goTo(target);
+    // Tab / Shift+Tab jump between answer lines (wrapping around).
+    const inner = component.handleInput.bind(component);
+    component.handleInput = (data: string) => {
+      if (data !== "\t" && data !== "\x1b[Z") return inner(data);
+      const answers = editor.getText().split("\n").map((l, i) => (/^A\d+:/.test(l) ? i : -1)).filter((i) => i >= 0);
+      if (answers.length === 0) return;
+      const at = editor.getCursor().line;
+      const next = data === "\t"
+        ? answers.find((i) => i > at) ?? answers[0]!
+        : [...answers].reverse().find((i) => i < at) ?? answers.at(-1)!;
+      goTo(next);
+      tui.requestRender();
+    };
+    return component;
+  });
+}
+
+/** Small capturing overlay while the browser form is open; Esc cancels. */
+function waitForWeb(ctx: ExtensionContext, lines: string[], result: Promise<WebAnswer | null>, cancel: () => void): Promise<WebAnswer | null> {
+  return ctx.ui.custom<WebAnswer | null>((tui, theme, _kb, done) => {
+    setHubTheme(theme);
+    void result.then((r) => done(r));
+    return {
+      focused: true,
+      render: (width: number) => {
+        const inner = boxInnerWidth(width);
+        return frameOverlay([...lines.map((l) => hubExactRow(`  ${l}`, inner)), hubExactRow(dim("  Waiting for your answers… esc cancels"), inner)], width, {
+          title: bold(" answer — web form "),
+          borderFg: (t) => hubTheme.fg("borderMuted", t),
+        });
+      },
+      invalidate: () => tui.requestRender(),
+      handleInput: (data: string) => {
+        // matchesKey: kitty-protocol terminals send Esc as a CSI sequence, not a bare \x1b.
+        if (matchesKey(data, Key.escape) || data === "\x1b" || data === "\x03") {
+          cancel();
+          done(null);
+        }
+      },
+    };
+  }, HUB_OVERLAY_OPTIONS);
+}
+
+const METHODS = [
+  { value: "reply", label: "reply", description: "The reply above a fixed input box — scroll it while you type" },
+  { value: "questions", label: "questions", description: "One answer per detected question (Q/A template)" },
+  { value: "web", label: "web", description: "Answer the questions in a browser form (works over SSH)" },
+];
+
+/** Reply panel in place of the input area (no overlay: pi restores the editor). */
+function replyPanel(ctx: ExtensionContext, reply: string, questions: number): Promise<ReplyPanelResult> {
+  return ctx.ui.custom<ReplyPanelResult>((tui, theme, _kb, done) => new ReplyPanel(tui, theme, reply, questions, done));
+}
+
+const HINT_WIDGET = "unipi-answer-hint";
+
+export function registerAnswerCommand(pi: ExtensionAPI): void {
+  // "N questions detected" hint above the editor after a reply that asks some;
+  // cleared as soon as the user sends anything.
+  let hinted = false;
+  pi.on("agent_end", (_event, ctx) => {
+    try {
+      if (!ctx.hasUI || !readUtilSettings(ctx.cwd).answer.hint) return;
+      const n = extractQuestions(lastAssistantText(ctx)).length;
+      if (n === 0) return;
+      ctx.ui.setWidget(HINT_WIDGET, [dim(`  ${n} question${n === 1 ? "" : "s"} in the reply — /unipi:answer questions to answer them one by one`)], { placement: "aboveEditor" });
+      hinted = true;
+    } catch {
+      // hint is cosmetic
+    }
+  });
+  const clearHint = (ctx: ExtensionContext) => {
+    if (!hinted) return;
+    hinted = false;
+    try {
+      ctx.ui.setWidget(HINT_WIDGET, undefined);
+    } catch {
+      // ignore
+    }
+  };
+  // Any new turn (typed, /unipi:answer, or an extension message) clears it.
+  pi.on("input", (_event, ctx) => clearHint(ctx));
+  pi.on("before_agent_start", (_event, ctx) => clearHint(ctx));
+
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.ANSWER}`, {
+    description: "Answer the last reply — a fixed input box under the scrollable reply (reply), per question (questions), or a browser form (web)",
+    getArgumentCompletions: (prefix: string) => {
+      const needle = (prefix ?? "").trim().toLowerCase();
+      const matches = METHODS.filter((m) => m.value.startsWith(needle));
+      return matches.length > 0 ? matches : null;
+    },
+    handler: async (args: string, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui?.notify?.("/unipi:answer needs the interactive TUI", "warning");
+        return;
+      }
+      const reply = lastAssistantText(ctx);
+      if (!reply) {
+        ctx.ui.notify("No agent reply to answer yet.", "info");
+        return;
+      }
+      const questions = extractQuestions(reply);
+      const settings = readUtilSettings(ctx.cwd).answer;
+      const arg = args.trim().toLowerCase();
+      let method: "reply" | "questions" | "web" =
+        arg === "web" ? "web" : arg === "questions" || arg === "editor" ? "questions" : arg === "reply" ? "reply" : settings.method;
+      if (method !== "reply" && questions.length === 0 && method === "web") method = "reply";
+
+      let message: string | undefined;
+      if (method === "reply") {
+        const result = await replyPanel(ctx, reply, questions.length);
+        if (result.type === "cancel") return;
+        if (result.type === "send") message = result.text;
+        else method = "questions";
+      }
+      if (method === "questions") {
+        const title = questions.length
+          ? `Answer ${questions.length} question${questions.length === 1 ? "" : "s"} — Tab next answer · Ctrl+G your editor`
+          : "Reply to the last message (no questions found) — Ctrl+G your editor";
+        const text = await answerEditor(ctx, title, buildTemplate(questions));
+        if (text === undefined) return;
+        message = composeAnswers(questions, parseTemplate(text, questions.length));
+      } else if (method === "web") {
+        const ssh = isSsh();
+        const port = settings.port > 0 ? settings.port : ssh ? SSH_DEFAULT_PORT : 0;
+        const form = await startWebForm(reply, questions, port).catch(() => startWebForm(reply, questions, 0));
+        const lines = ssh
+          ? [
+              bold("Open on your own machine:"),
+              form.url,
+              dim("First forward the port from that machine:"),
+              `ssh -L ${form.port}:127.0.0.1:${form.port} ${hostname()}`,
+            ]
+          : [bold("Opened in your browser:"), form.url];
+        if (!ssh) openBrowser(form.url);
+        const answer = await waitForWeb(ctx, lines, form.result, form.close);
+        form.close();
+        if (!answer) return;
+        message = composeAnswers(questions, answer.answers, answer.note);
+      }
+      if (!message) {
+        ctx.ui.notify("Nothing answered — nothing sent.", "info");
+        return;
+      }
+      pi.sendUserMessage(message, ctx.isIdle() ? undefined : { deliverAs: "followUp" });
+    },
+  });
+}

package/packages/utility/src/answer/reply.ts

@@ -0,0 +1,133 @@
+/**
+ * @pi-unipi/utility — /unipi:answer "reply" panel (the default method)
+ *
+ * Like /unipi:btw: the panel replaces the input area (ctx.ui.custom without
+ * `overlay`; pi restores the editor and your draft when it closes). The agent's
+ * last reply is shown in a scrollable viewport above a FIXED input box, so you
+ * can read any part of a long reply while typing — nothing scrolls away.
+ *
+ *   ── /unipi:answer · reply ───────────── 3 questions · tab answers them one by one ──
+ *   …the reply, markdown…
+ *   ──────────────────────────────────────────────  (the input box's own top border)
+ *   your answer (multi-line: shift+enter)
+ *   ──────────────────────────────────────────────
+ *   ↵ send · ↑↓ scroll · alt+↑↓ / pgup pgdn scroll while typing · … · lines 12–40 of 88
+ *
+ * ↑/↓ scroll the reply while the input is EMPTY; once you type they belong to
+ * the input (cursor movement in a multi-line answer). Alt+↑/↓ and PgUp/PgDn
+ * always scroll.
+ */
+
+import { Editor, Key, Markdown, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, getSelectListTheme, type Theme } from "@earendil-works/pi-coding-agent";
+
+export type ReplyPanelResult = { type: "send"; text: string } | { type: "questions"; draft: string } | { type: "cancel" };
+
+export class ReplyPanel implements Component, Focusable {
+  private readonly editor: Editor;
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.editor.focused = value;
+  }
+  private scroll = 0;
+  /** Start at the end — questions usually close a reply. */
+  private atEnd = true;
+  private body: string[] = [];
+  private bodyWidth = 0;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly reply: string,
+    private readonly questionCount: number,
+    private readonly done: (result: ReplyPanelResult) => void,
+    draft = "",
+  ) {
+    this.editor = new Editor(tui, { borderColor: (text: string) => theme.fg("borderMuted", text), selectList: getSelectListTheme() });
+    if (draft) this.editor.setText(draft);
+    this.editor.onSubmit = (text: string) => {
+      const value = text.trim();
+      if (value) this.done({ type: "send", text: value });
+    };
+  }
+
+  invalidate(): void {
+    this.bodyWidth = 0;
+    this.editor.invalidate?.();
+  }
+
+  private viewport(): number {
+    return Math.max(4, (process.stdout.rows ?? 30) - 12);
+  }
+
+  private lines(width: number): string[] {
+    if (this.bodyWidth !== width) {
+      const md = new Markdown(this.reply, 0, 0, getMarkdownTheme());
+      this.body = md.render(width).flatMap((l) => wrapTextWithAnsi(l, Math.max(1, width)));
+      this.bodyWidth = width;
+    }
+    return this.body;
+  }
+
+  render(width: number): string[] {
+    const w = Math.max(20, width);
+    const t = this.theme;
+    const body = this.lines(w - 1);
+    const view = this.viewport();
+    const max = Math.max(0, body.length - view);
+    if (this.atEnd) this.scroll = max;
+    this.scroll = Math.max(0, Math.min(this.scroll, max));
+    const shown = body.slice(this.scroll, this.scroll + view);
+
+    const title = " /unipi:answer · reply ";
+    const qs = this.questionCount > 0 ? ` ${this.questionCount} question${this.questionCount === 1 ? "" : "s"} · tab answers them one by one ` : "";
+    const top = `${t.fg("borderMuted", "──")}${t.fg("accent", title)}${t.fg("borderMuted", "─".repeat(Math.max(0, w - 2 - visibleWidth(title) - visibleWidth(qs))))}${t.fg("dim", qs)}`;
+    const pos = body.length > view ? ` · lines ${this.scroll + 1}–${this.scroll + shown.length} of ${body.length}` : "";
+    const scrollKeys = this.editor.getText() === "" ? "↑↓ scroll" : "alt+↑↓ scroll";
+    const hint = t.fg("dim", `↵ send · shift+↵ newline · ${scrollKeys} · pgup/pgdn page${this.questionCount > 0 ? " · tab questions" : ""} · esc back${pos}`);
+
+    // The input box draws its own top/bottom border — no extra rule above it.
+    return [
+      truncateToWidth(top, w, ""),
+      ...shown.map((l) => truncateToWidth(l, w, "")),
+      ...Array.from({ length: Math.max(0, view - shown.length) }, () => ""),
+      ...this.editor.render(w),
+      truncateToWidth(hint, w, ""),
+    ];
+  }
+
+  private scrollBy(delta: number): void {
+    const max = Math.max(0, this.body.length - this.viewport());
+    this.scroll = Math.max(0, Math.min(max, this.scroll + delta));
+    this.atEnd = this.scroll >= max;
+    this.tui.requestRender();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape) || data === "\x1b") {
+      this.done({ type: "cancel" });
+      return;
+    }
+    if (matchesKey(data, Key.tab) && this.questionCount > 0) {
+      this.done({ type: "questions", draft: this.editor.getText() });
+      return;
+    }
+    const page = Math.max(1, this.viewport() - 2);
+    if (matchesKey(data, Key.pageUp)) return this.scrollBy(-page);
+    if (matchesKey(data, Key.pageDown)) return this.scrollBy(page);
+    if (matchesKey(data, "alt+up")) return this.scrollBy(-1);
+    if (matchesKey(data, "alt+down")) return this.scrollBy(1);
+    // Plain ↑/↓ scroll only while nothing is typed; after that they are the input's.
+    const empty = this.editor.getText() === "";
+    if (empty && matchesKey(data, Key.up)) return this.scrollBy(-1);
+    if (empty && matchesKey(data, Key.down)) return this.scrollBy(1);
+    this.editor.handleInput(data);
+    this.tui.requestRender();
+  }
+
+  dispose(): void {}
+}

package/packages/utility/src/answer/web.ts

@@ -0,0 +1,167 @@
+/**
+ * @pi-unipi/utility — /unipi:answer web form
+ *
+ * A one-shot local page: the agent's full reply on the left, one answer box
+ * per question on the right (plus a free-text note), submit → resolves. Bound
+ * to 127.0.0.1 with a random token in the URL; over SSH the caller shows a
+ * port-forward command instead of opening a browser.
+ */
+
+import { randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+
+export interface WebAnswer {
+  answers: string[];
+  note: string;
+}
+
+export interface WebForm {
+  url: string;
+  port: number;
+  result: Promise<WebAnswer | null>;
+  close: () => void;
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** Tiny markdown → HTML for the reply pane: fences, headings, lists, bold, code. */
+export function renderReply(md: string): string {
+  const out: string[] = [];
+  let code: string[] | null = null;
+  let list = false;
+  let table: string[][] | null = null;
+  const inline = (s: string) => esc(s).replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\*\*([^*]+)\*\*/g, "<b>$1</b>");
+  const flushTable = () => {
+    if (!table) return;
+    const [head, ...body] = table;
+    out.push(`<table><thead><tr>${head!.map((c) => `<th>${inline(c)}</th>`).join("")}</tr></thead><tbody>${body.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join("")}</tr>`).join("")}</tbody></table>`);
+    table = null;
+  };
+  for (const line of md.split("\n")) {
+    if (!code && /^\s*\|.*\|\s*$/.test(line)) {
+      if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue; // separator row
+      (table ??= []).push(line.trim().slice(1, -1).split("|").map((c) => c.trim()));
+      continue;
+    }
+    flushTable();
+    if (/^\s*```/.test(line)) {
+      if (code) {
+        out.push(`<pre><code>${esc(code.join("\n"))}</code></pre>`);
+        code = null;
+      } else code = [];
+      continue;
+    }
+    if (code) {
+      code.push(line);
+      continue;
+    }
+    const li = line.match(/^\s*(?:[-*+]|\d+[.)])\s+(.*)$/);
+    if (li) {
+      if (!list) out.push("<ul>");
+      list = true;
+      out.push(`<li>${inline(li[1]!)}</li>`);
+      continue;
+    }
+    if (list) {
+      out.push("</ul>");
+      list = false;
+    }
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) out.push(`<h${Math.min(4, h[1]!.length + 1)}>${inline(h[2]!)}</h${Math.min(4, h[1]!.length + 1)}>`);
+    else if (line.trim()) out.push(`<p>${inline(line)}</p>`);
+  }
+  flushTable();
+  if (code) out.push(`<pre><code>${esc(code.join("\n"))}</code></pre>`);
+  if (list) out.push("</ul>");
+  return out.join("\n");
+}
+
+export function formPage(reply: string, questions: readonly string[], token: string): string {
+  const qs = questions.length ? questions : ["Your reply"];
+  const fields = qs.map((q, i) => `
+      <label><span class="n">${i + 1}</span><span class="q">${esc(q)}</span></label>
+      <textarea name="a${i}" rows="3" placeholder="Answer (empty = skip)"></textarea>`).join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Answer — pi</title>
+<style>
+  :root{color-scheme:dark;--bg:#16181d;--panel:#1e2128;--line:#2c313a;--fg:#d7dae0;--dim:#8a919e;--accent:#53a0d7}
+  *{box-sizing:border-box} body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.55 system-ui,sans-serif}
+  main{display:grid;grid-template-columns:minmax(0,1.1fr) minmax(0,1fr);height:100vh}
+  section{overflow:auto;padding:24px 28px} .reply{border-right:1px solid var(--line)}
+  h1{font-size:13px;letter-spacing:.08em;text-transform:uppercase;color:var(--dim);margin:0 0 16px}
+  table{border-collapse:collapse;margin:10px 0} th,td{border:1px solid var(--line);padding:5px 10px;text-align:left} th{color:var(--dim);font-weight:600}
+  pre{background:var(--panel);padding:10px 12px;border-radius:6px;overflow:auto} code{font:12.5px ui-monospace,monospace}
+  label{display:flex;gap:10px;margin:18px 0 6px} .n{color:var(--accent);font-weight:600} .q{flex:1}
+  textarea{width:100%;background:var(--panel);color:var(--fg);border:1px solid var(--line);border-radius:6px;padding:8px 10px;font:inherit;resize:vertical}
+  textarea:focus{outline:none;border-color:var(--accent)}
+  .bar{position:sticky;bottom:0;background:var(--bg);padding:14px 0;display:flex;gap:12px;align-items:center}
+  button{background:var(--accent);color:#0b0d10;border:0;border-radius:6px;padding:9px 18px;font-weight:600;cursor:pointer}
+  .hint{color:var(--dim);font-size:12px} .done{padding:40px;font-size:16px}
+  @media (max-width:900px){main{grid-template-columns:1fr;height:auto}.reply{border-right:0;border-bottom:1px solid var(--line)}}
+</style></head><body><main>
+  <section class="reply"><h1>Agent's reply</h1>${renderReply(reply)}</section>
+  <section><h1>Your answers</h1>
+    <form id="f">${fields}
+      <label><span class="q">Anything else</span></label>
+      <textarea name="note" rows="3" placeholder="Optional note"></textarea>
+      <div class="bar"><button type="submit">Send to pi</button><span class="hint">Ctrl+Enter sends</span></div>
+    </form>
+  </section>
+</main>
+<script>
+const f=document.getElementById("f");
+const send=async()=>{const d=new FormData(f);const answers=${JSON.stringify(qs.map((_, i) => `a${i}`))}.map(k=>d.get(k)||"");
+  const r=await fetch("/a/${token}",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({answers,note:d.get("note")||""})});
+  document.body.innerHTML='<div class="done">'+(r.ok?"Sent to pi. You can close this tab.":"Could not send — is pi still waiting?")+'</div>';};
+f.addEventListener("submit",e=>{e.preventDefault();send();});
+f.addEventListener("keydown",e=>{if(e.key==="Enter"&&(e.ctrlKey||e.metaKey)){e.preventDefault();send();}});
+document.querySelector("textarea")?.focus();
+</script></body></html>`;
+}
+
+/** Start the form server. `port` 0 = any free port. */
+export function startWebForm(reply: string, questions: readonly string[], port = 0): Promise<WebForm> {
+  const token = randomBytes(12).toString("hex");
+  let settle: (v: WebAnswer | null) => void = () => {};
+  const result = new Promise<WebAnswer | null>((resolve) => { settle = resolve; });
+  const page = formPage(reply, questions, token);
+  const server: Server = createServer((req, res) => {
+    if (req.url !== `/a/${token}`) {
+      res.writeHead(404).end();
+      return;
+    }
+    if (req.method === "GET") {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(page);
+      return;
+    }
+    if (req.method === "POST") {
+      let body = "";
+      req.on("data", (c) => { body += c; if (body.length > 1_000_000) req.destroy(); });
+      req.on("end", () => {
+        try {
+          const data = JSON.parse(body) as { answers?: unknown; note?: unknown };
+          const answers = Array.isArray(data.answers) ? data.answers.map((a) => String(a ?? "")) : [];
+          res.writeHead(200).end("ok");
+          settle({ answers, note: typeof data.note === "string" ? data.note : "" });
+        } catch {
+          res.writeHead(400).end();
+        }
+      });
+      return;
+    }
+    res.writeHead(405).end();
+  });
+  const close = () => {
+    settle(null);
+    server.close();
+    server.closeAllConnections?.();
+  };
+  void result.then(() => setTimeout(() => { server.close(); server.closeAllConnections?.(); }, 500).unref());
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      const actual = (server.address() as { port: number }).port;
+      resolve({ url: `http://127.0.0.1:${actual}/a/${token}`, port: actual, result, close });
+    });
+  });
+}