pi-ask-popup 0.1.0

package/src/config.ts

@@ -0,0 +1,250 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+
+/** Key spec for the overlay collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+export type CollapseKeySpec = string;
+
+export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+]";
+export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
+
+/** Filename both layers use, under the agent dir and under the project's config dir. */
+export const CONFIG_FILE_NAME = "pi-ask-popup.json";
+
+/** Operator-supplied copy folded into the tool's registered description and prompt. */
+export interface GuidanceFields {
+  description?: string;
+  promptSnippet?: string;
+  promptGuidelines?: string[];
+}
+
+export interface AskPopupConfig {
+  /**
+   * Key spec for the collapse/expand shortcut, in pi-coding-agent keybinding id
+   * format (`modifier+key`: `ctrl+]`, `alt+o`, `ctrl+shift+h`). Defaults to
+   * `"ctrl+]"`. Pick something reachable on your layout — Latin American
+   * keyboards put `]` on the shifted layer and usually want `"ctrl+}"`. Pass
+   * `"off"` to disable the shortcut entirely.
+   */
+  collapseKey?: CollapseKeySpec;
+  guidance?: GuidanceFields;
+}
+
+export interface ConfigLoadResult {
+  config: AskPopupConfig;
+  /**
+   * Problems worth telling the user about, as data. Never printed here: on RPC
+   * and JSON hosts this process is speaking a protocol on stdout, and a stray
+   * `console.warn` corrupts the stream. The caller decides where these go.
+   */
+  warnings: readonly string[];
+}
+
+export interface ConfigSources {
+  /** Pi's global agent directory, normally `getAgentDir()` (`~/.pi/agent`). */
+  agentDir: string;
+  /**
+   * Workspace root whose `<CONFIG_DIR_NAME>/pi-ask-popup.json` overrides the
+   * global layer. Omit it to skip the project layer entirely — callers pass
+   * `ctx.cwd` only when `ctx.isProjectTrusted()`, so an untrusted checkout
+   * cannot rebind a global keyboard shortcut or rewrite the tool description
+   * the model is given.
+   */
+  projectDir?: string;
+}
+
+/** The layer files, global first. Existence is not checked; reading never creates them. */
+export function configPaths(sources: ConfigSources): string[] {
+  const paths = [join(sources.agentDir, CONFIG_FILE_NAME)];
+  if (sources.projectDir !== undefined) {
+    paths.push(join(sources.projectDir, CONFIG_DIR_NAME, CONFIG_FILE_NAME));
+  }
+  return paths;
+}
+
+/**
+ * Read one layer. An absent file means "no overrides" and is not a warning —
+ * having no config is the normal case, not a degraded one. Anything else that
+ * goes wrong (malformed JSON, a directory in the file's place, no read
+ * permission) degrades to no overrides and reports why.
+ *
+ * Deliberately `readFileSync` + catch rather than `existsSync` then read: the
+ * check-then-read pair races, and this keeps the no-write guarantee obvious —
+ * nothing here can create a file or a parent directory.
+ */
+function readLayer(path: string, warnings: string[]): Record<string, unknown> {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      warnings.push(`pi-ask-popup: cannot read ${path} — ${(err as Error).message}`);
+    }
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(text);
+    // `typeof null === "object"` and so is an array; a config file is neither.
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      warnings.push(`pi-ask-popup: ${path} is not a JSON object, ignoring it`);
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    warnings.push(`pi-ask-popup: invalid JSON in ${path}, ignoring it — ${(err as Error).message}`);
+    return {};
+  }
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Keep only the guidance entries that are usable, silently. A single bad field
+ * is not worth a warning — the field falls back to the built-in default and
+ * the tool still registers.
+ */
+export function validateGuidanceFields(fields: unknown): GuidanceFields {
+  if (fields === null || typeof fields !== "object") return {};
+  const g = fields as Record<string, unknown>;
+  const out: GuidanceFields = {};
+  const description = nonEmptyString(g.description);
+  if (description !== undefined) out.description = description;
+  const promptSnippet = nonEmptyString(g.promptSnippet);
+  if (promptSnippet !== undefined) out.promptSnippet = promptSnippet;
+  const guidelines = g.promptGuidelines;
+  if (
+    Array.isArray(guidelines) &&
+    guidelines.length > 0 &&
+    guidelines.every((s) => nonEmptyString(s) !== undefined)
+  ) {
+    out.promptGuidelines = guidelines as string[];
+  }
+  return out;
+}
+
+/**
+ * Read the global layer, then let the project layer override it. Guidance
+ * merges per field rather than wholesale, so a workspace can pin one line of
+ * copy without restating the rest.
+ */
+export function loadConfig(sources: ConfigSources): ConfigLoadResult {
+  const warnings: string[] = [];
+  const config: AskPopupConfig = {};
+  for (const path of configPaths(sources)) {
+    const raw = readLayer(path, warnings);
+    const collapseKey = nonEmptyString(raw.collapseKey);
+    if (collapseKey !== undefined) config.collapseKey = collapseKey;
+    const guidance = validateGuidanceFields(raw.guidance);
+    if (Object.keys(guidance).length > 0) {
+      config.guidance = { ...config.guidance, ...guidance };
+    }
+  }
+  return { config, warnings };
+}
+
+/**
+ * Base keys pi-tui's `matchesKey` actually recognizes, transcribed from its
+ * `SYMBOL_KEYS` set and the named cases of its match switch. Two deliberate
+ * differences from the set upstream accepted:
+ *
+ * - `"` is gone. pi-tui does not carry it, so `ctrl+"` parsed fine and then
+ *   matched nothing: a dead shortcut with no fallback and no diagnostic.
+ * - `+` is gone. It is the separator, so no spec can name it as a base key
+ *   anyway, and `matchesKey("+", "+")` is false.
+ *
+ * Named keys are lowercase because `parseKeyId` lowercases the whole id before
+ * matching — `pageUp` reaches the switch as `pageup`.
+ */
+const SYMBOL_KEYS = new Set("`-=[]\\;',./!@#$%^&*()_|~{}:<>?");
+const SPECIAL_KEYS = new Set([
+  "escape",
+  "esc",
+  "enter",
+  "return",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "clear",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+  ...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+function isBaseKey(key: string): boolean {
+  if (key.length !== 1) return SPECIAL_KEYS.has(key);
+  return (key >= "a" && key <= "z") || (key >= "0" && key <= "9") || SYMBOL_KEYS.has(key);
+}
+
+/**
+ * Mirror pi-tui's KeyId grammar strictly: zero or more distinct modifiers, then
+ * one base key.
+ *
+ * Loose acceptance is not merely untidy here. pi-tui's `parseKeyId` takes the
+ * LAST `+`-part as the key and asks only whether the remaining parts *include*
+ * "ctrl"/"shift"/"alt"/"super" — unknown parts are discarded, not rejected. So
+ * a typo like `ctr+]` parses as a bare `]` with no modifiers, and the raw
+ * terminal listener that owns this shortcut would then swallow every `]` the
+ * user types, anywhere.
+ */
+function isValidCollapseKeySpec(spec: string): boolean {
+  if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+  const parts = spec.split("+");
+  const base = parts[parts.length - 1] ?? "";
+  const modifiers = parts.slice(0, -1);
+  if (modifiers.length !== new Set(modifiers).size) return false;
+  if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+  return isBaseKey(base);
+}
+
+/**
+ * Normalize and validate the configured shortcut, falling back to the default.
+ *
+ * The parameter widens `collapseKey` to include an explicit `undefined` rather
+ * than leaving it merely optional: callers spread a partially-populated config
+ * in, and under `exactOptionalPropertyTypes` a present-but-undefined key is a
+ * different type from an absent one. Both mean "not configured" here.
+ */
+export function resolveCollapseKey(config: {
+  collapseKey?: CollapseKeySpec | undefined;
+}): CollapseKeySpec {
+  const raw = config.collapseKey?.trim().toLowerCase();
+  if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
+  if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+  return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+
+// The only compound-word names in SPECIAL_KEYS — capitalizing the first letter
+// alone would render them "Pageup" and "Pagedown".
+const COMPOUND_KEY_DISPLAY: Record<string, string> = {
+  pageup: "PageUp",
+  pagedown: "PageDown",
+};
+
+/**
+ * Pretty-print a resolved spec for UI copy: `"ctrl+]"` → `"Ctrl+]"`, `"alt+o"` →
+ * `"Alt+O"`, `"ctrl+pagedown"` → `"Ctrl+PageDown"`. Display only — matching
+ * always uses the raw lowercase spec, so never feed the result back into
+ * `matchesKey`.
+ */
+export function formatKeySpecForDisplay(spec: CollapseKeySpec): string {
+  return spec
+    .split("+")
+    .map(
+      (part) =>
+        COMPOUND_KEY_DISPLAY[part] ??
+        (part.length <= 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1)),
+    )
+    .join("+");
+}

package/src/events.ts

@@ -0,0 +1,107 @@
+/**
+ * The public event contract.
+ *
+ * This module deliberately imports nothing. A footer, statusline or notifier
+ * subscribes to these channels to know what is being asked and whether the
+ * agent is waiting on a person; it should not have to load a render graph, or
+ * a schema compiler, to read two strings and four interfaces. Adding an import
+ * here defeats the reason the `./events` subpath exists, so there is a test
+ * that fails if one appears.
+ *
+ * Stability rules for both channels:
+ *
+ *   1. Channel names never change once published. Subscribers hardcode them.
+ *   2. Payload changes are append-only, and new fields ship optional.
+ *      Listeners must tolerate fields they do not know.
+ *   3. Anything breaking -- a rename, a retype, a removal, a change in when
+ *      the event fires -- takes a new channel name and a period of emitting
+ *      both.
+ *   4. No version field inside a payload. The channel name carries the
+ *      version, because that is what a subscriber matches on.
+ *   5. Payloads stay JSON-safe: primitives, arrays and plain objects. No Set,
+ *      Map, Date or class instance. Listeners forward these across process and
+ *      network boundaries, and a Map arrives at the far end as `{}`.
+ */
+
+/** Fired once, as the questionnaire is put to the user. */
+export const ASK_POPUP_PROMPT_EVENT = "pi-ask-popup:prompt" as const;
+
+/** Fired true before the wait and false when it ends, however it ends. */
+export const ASK_POPUP_BLOCKED_EVENT = "pi-ask-popup:blocked" as const;
+
+export interface AskPopupPromptOption {
+  label: string;
+  description: string;
+  /**
+   * Whether the option carries markdown preview content. The content itself is
+   * deliberately not shipped: it can run to hundreds of lines, and a listener
+   * that wants to say "this one has details" only needs the boolean.
+   */
+  hasPreview: boolean;
+}
+
+export interface AskPopupPromptQuestion {
+  /** The question text, as the agent wrote it. */
+  question: string;
+  /** The short chip shown beside the question. */
+  header: string;
+  /** Normalized from the optional parameter, so listeners never see undefined. */
+  multiSelect: boolean;
+  options: readonly AskPopupPromptOption[];
+}
+
+export interface AskPopupPromptEventPayload {
+  questions: readonly AskPopupPromptQuestion[];
+}
+
+export interface AskPopupBlockedEventPayload {
+  /** True while input is awaited; false once it is answered, cancelled or failed. */
+  active: boolean;
+}
+
+/**
+ * What `buildPromptPayload` reads. Declared structurally rather than imported
+ * from the tool's typebox schemas: the shapes match, so the real parameters
+ * satisfy this at the call site, and this file stays import-free.
+ */
+export interface PromptSourceOption {
+  label: string;
+  description: string;
+  preview?: string | undefined;
+}
+
+export interface PromptSourceQuestion {
+  question: string;
+  header: string;
+  multiSelect?: boolean | undefined;
+  options: readonly PromptSourceOption[];
+}
+
+export interface PromptSource {
+  questions: readonly PromptSourceQuestion[];
+}
+
+/**
+ * Project the validated tool parameters onto the prompt payload. Copies field
+ * by field rather than spreading: a spread would forward whatever else the
+ * parameters happen to carry, and preview content is the thing this payload
+ * exists to leave behind.
+ */
+export function buildPromptPayload(source: PromptSource): AskPopupPromptEventPayload {
+  return {
+    questions: source.questions.map((q) => ({
+      question: q.question,
+      header: q.header,
+      multiSelect: q.multiSelect ?? false,
+      options: q.options.map((o) => ({
+        label: o.label,
+        description: o.description,
+        hasPreview: typeof o.preview === "string" && o.preview.length > 0,
+      })),
+    })),
+  };
+}
+
+export function buildBlockedPayload(active: boolean): AskPopupBlockedEventPayload {
+  return { active };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * pi-ask-popup — a tabbed questionnaire the model can put to you when it would
+ * otherwise guess.
+ *
+ * Registers `ask_user_question`, plus a reconciler that keeps the tool out of
+ * the model's tool list on hosts with no way to show it.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskPopupTool } from "./ask-user-question.js";
+import { registerAskPopupReconciler } from "./reconcile.js";
+
+export {
+  ASK_POPUP_BLOCKED_EVENT,
+  ASK_POPUP_PROMPT_EVENT,
+  type AskPopupBlockedEventPayload,
+  type AskPopupPromptEventPayload,
+  type AskPopupPromptOption,
+  type AskPopupPromptQuestion,
+} from "./events.js";
+
+export default function piAskPopup(pi: ExtensionAPI): void {
+  registerAskPopupTool(pi);
+  registerAskPopupReconciler(pi);
+}

package/src/reconcile.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ASK_POPUP_TOOL_NAME } from "./ask-user-question.js";
+
+/**
+ * Keep the tool out of the model's hands when there is no way to show it.
+ *
+ * A model offered a tool it cannot use will call it, get an error, and have to
+ * recover; not offering it is simply better. `ctx.hasUI` is the honest signal:
+ * RPC hosts report true and the dialog walker works there, so they stay.
+ *
+ * Idempotent by construction. When the tool is already in the right state,
+ * nothing is written, so sibling tools another extension added are untouched.
+ */
+export function reconcileAskPopupTool(pi: ExtensionAPI, ctx: ExtensionContext): void {
+  const active = pi.getActiveTools();
+  const hasTool = active.includes(ASK_POPUP_TOOL_NAME);
+  if (!ctx.hasUI && hasTool) {
+    pi.setActiveTools(active.filter((n) => n !== ASK_POPUP_TOOL_NAME));
+  } else if (ctx.hasUI && !hasTool) {
+    pi.setActiveTools([...active, ASK_POPUP_TOOL_NAME]);
+  }
+}
+
+/**
+ * Run the reconciler before each turn, which is when the tool list the model
+ * sees is snapshotted. The in-handler guards stay as a one-turn backstop in
+ * case that ordering ever changes, or a host claims a UI it cannot render with.
+ */
+export function registerAskPopupReconciler(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (_event, ctx) => reconcileAskPopupTool(pi, ctx));
+}

package/src/rpc-fallback.ts

@@ -0,0 +1,198 @@
+/**
+ * The dialog-primitive path for hosts that cannot render the overlay.
+ *
+ * The TUI path draws a tabbed overlay through `ctx.ui.custom()`, which needs a
+ * real terminal. RPC hosts -- the VS Code pendant, ACP clients like Zed and
+ * Paseo -- report `hasUI: true`, because Pi's dialog sub-protocol genuinely
+ * works there, and yet `ui.custom()` resolves undefined without drawing
+ * anything. What those hosts do have is `ui.select()` and `ui.input()`, which
+ * they render natively. So this walks the questions one dialog at a time and
+ * returns the same `QuestionnaireResult` the overlay would, feeding the same
+ * envelope.
+ *
+ * What is lost, and why it cannot be helped: the select and input primitives
+ * take a title and a list, so there is no side-by-side preview pane (previews
+ * fold into the title), no tabbed review (one dialog per question), and
+ * multi-select becomes a free-text list of numbers instead of checkbox rows.
+ * Notes do not exist on this path at all -- neither primitive carries a field
+ * for them, and inventing a second dialog to collect one would double the
+ * number of prompts for something most answers never use.
+ *
+ * The "Type something." escape does survive, on both variants.
+ */
+
+import { ROW_INTENT_META } from "./state/row-intent.js";
+import type {
+  QuestionAnswer,
+  QuestionData,
+  QuestionnaireResult,
+  QuestionParams,
+} from "./tool/types.js";
+
+const MULTI_SELECT_INSTRUCTIONS =
+  'Enter the numbers of all that apply, comma-separated (e.g. "1,3"), or type a custom answer as plain text.';
+const CUSTOM_ANSWER_TITLE = "Type your answer:";
+const MULTI_SELECT_PLACEHOLDER = "1,3";
+
+/** How much of an option's preview is folded into a select title before truncation. */
+const MAX_PREVIEW_CHARS = 600;
+
+/**
+ * The slice of Pi's UI context this walker needs, declared structurally.
+ * `hasDialogUI` is the runtime gate that makes the shape trustworthy: jiti
+ * transpiles without type-checking, so a host that does not implement these
+ * would otherwise fail at the call rather than at the check.
+ */
+export type DialogUI = {
+  select: (
+    title: string,
+    options: string[],
+    opts?: { timeout?: number; signal?: AbortSignal },
+  ) => Promise<string | undefined>;
+  input: (
+    title: string,
+    placeholder?: string,
+    opts?: { timeout?: number; signal?: AbortSignal },
+  ) => Promise<string | undefined>;
+};
+
+/** Whether the host implements the select and input primitives. */
+export function hasDialogUI(ui: unknown): ui is DialogUI {
+  const u = ui as Partial<Record<"select" | "input", unknown>> | null | undefined;
+  return typeof u?.select === "function" && typeof u?.input === "function";
+}
+
+type Option = QuestionData["options"][number];
+
+function formatOptionLine(option: Option, index: number): string {
+  return `${index + 1}. ${option.label} — ${option.description}`;
+}
+
+/**
+ * Read a leading option number as a zero-based index, or null when it is not
+ * one. `Number.parseInt` reads "2. B — b" as 2, which is what makes it work on
+ * the string a select dialog hands back. NaN and out-of-range both fail the
+ * bounds check.
+ */
+function parseIndex(token: string, count: number): number | null {
+  const i = Number.parseInt(token, 10) - 1;
+  return i >= 0 && i < count ? i : null;
+}
+
+/** Previews folded into the title, since there is no pane to put them in. */
+function buildPreviewBlock(question: QuestionData): string {
+  const blocks = question.options.flatMap((o, i) =>
+    o.preview !== undefined && o.preview.length > 0
+      ? [`--- ${i + 1}. ${o.label} preview ---\n${o.preview.slice(0, MAX_PREVIEW_CHARS)}`]
+      : [],
+  );
+  return blocks.length > 0 ? `\n\n${blocks.join("\n\n")}` : "";
+}
+
+/**
+ * Walk the questionnaire, one native dialog at a time.
+ *
+ * Dismissing any dialog cancels the whole questionnaire, which is what Esc
+ * does in the overlay, and the shared envelope turns that into a decline. Any
+ * other outcome produces one `QuestionAnswer` per question, so what the model
+ * receives is indistinguishable from the overlay path.
+ */
+export async function runRpcQuestionnaire(
+  ui: DialogUI,
+  params: QuestionParams,
+): Promise<QuestionnaireResult> {
+  const answers: QuestionAnswer[] = [];
+  const dialogOpts = params.timeout === undefined ? undefined : { timeout: params.timeout };
+  for (let qi = 0; qi < params.questions.length; qi++) {
+    const q = params.questions[qi];
+    if (!q) continue;
+    const header = q.header ? `[${q.header}] ` : "";
+    const answer = q.multiSelect
+      ? await askMultiSelect(ui, q, qi, header, dialogOpts)
+      : await askSingleSelect(ui, q, qi, header, dialogOpts);
+    if (answer === undefined) return { answers, cancelled: true };
+    answers.push(answer);
+  }
+  return { answers, cancelled: false };
+}
+
+/** Undefined means the user dismissed the dialog, which cancels everything. */
+async function askSingleSelect(
+  ui: DialogUI,
+  q: QuestionData,
+  questionIndex: number,
+  header: string,
+  opts?: { timeout?: number; signal?: AbortSignal },
+): Promise<QuestionAnswer | undefined> {
+  const options = q.options.map(formatOptionLine);
+  options.push(`${q.options.length + 1}. ${ROW_INTENT_META.other.label}`);
+  const chosen = await ui.select(`${header}${q.question}${buildPreviewBlock(q)}`, options, opts);
+  if (chosen === undefined || chosen === null) return undefined;
+  const idx = parseIndex(chosen, options.length);
+  // A host that returns something outside the list it was given is
+  // indistinguishable from a dismissal. Treating it as one beats fabricating
+  // an answer the user never gave.
+  if (idx === null) return undefined;
+  const option = q.options[idx];
+  if (option) {
+    return {
+      questionIndex,
+      question: q.question,
+      kind: "option",
+      answer: option.label,
+      // Spread rather than assigned: the envelope's contract is that the key is
+      // absent when there was no preview, not present and undefined.
+      ...(option.preview !== undefined && option.preview.length > 0
+        ? { preview: option.preview }
+        : {}),
+    };
+  }
+  // The "Type something." row, which is the one index past the authored options.
+  const typed = await ui.input(`${header}${q.question}\n\n${CUSTOM_ANSWER_TITLE}`, "", opts);
+  if (typed === undefined || typed === null) return undefined;
+  return { questionIndex, question: q.question, kind: "custom", answer: typed };
+}
+
+/** Undefined means the user dismissed the dialog, which cancels everything. */
+async function askMultiSelect(
+  ui: DialogUI,
+  q: QuestionData,
+  questionIndex: number,
+  header: string,
+  opts?: { timeout?: number; signal?: AbortSignal },
+): Promise<QuestionAnswer | undefined> {
+  const list = q.options.map(formatOptionLine).join("\n");
+  const value = await ui.input(
+    `${header}${q.question}\n\n${list}\n\n${MULTI_SELECT_INSTRUCTIONS}`,
+    MULTI_SELECT_PLACEHOLDER,
+    opts,
+  );
+  if (value === undefined || value === null) return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    // A deliberate empty commit, the same as pressing Next with nothing ticked.
+    //
+    // Kept explicit even though falling through reaches the same answer: with
+    // no tokens the `every` below is vacuously true and produces an empty
+    // selection anyway. Removing this would leave an important behaviour
+    // resting on that, and no test could tell the two apart.
+    return { questionIndex, question: q.question, kind: "multi", answer: null, selected: [] };
+  }
+  const tokens = trimmed.split(/[,\s]+/).filter((tok) => tok.length > 0);
+  const indices = tokens.map((tok) =>
+    /^\d+\.?$/.test(tok) ? parseIndex(tok, q.options.length) : null,
+  );
+  if (indices.every((i): i is number => i !== null)) {
+    const selected: string[] = [];
+    for (const i of indices) {
+      const label = q.options[i]?.label;
+      if (label !== undefined && !selected.includes(label)) selected.push(label);
+    }
+    return { questionIndex, question: q.question, kind: "multi", answer: null, selected };
+  }
+  // Any token that is not an index -- a word, or a number like "13" when there
+  // are three options -- means the user typed an answer rather than picking
+  // from the list. Keeping it verbatim is both the honest reading and the
+  // multi-select half of the "Type something." escape.
+  return { questionIndex, question: q.question, kind: "custom", answer: trimmed };
+}