@a-t-h-i/bot-lobby 0.6.3 → 0.6.5

package/src/ask/relay.ts

@@ -0,0 +1,89 @@
+/**
+ * Asking the user from a subagent. A subagent runs as `pi --mode rpc` with no
+ * terminal of its own, so its `ask_user_question` goes out as an RPC editor
+ * dialog carrying the questions (marked with `RELAY_TITLE`); the runner in the
+ * master process answers it by putting the questionnaire to the user and
+ * sends the answers back the same way. Only runs the master lets ask (the
+ * designer's) get the tool: it sets `ASK_ENV` for them.
+ */
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Asker } from "./dialog.ts";
+import { MAX_OPTIONS, MAX_QUESTIONS, type AskQuestion, type AskResult } from "./types.ts";
+
+/** Env flag the master sets for a subagent that may ask the user. */
+export const ASK_ENV = "BOT_LOBBY_ASK";
+/** Title of the RPC dialog that carries a relayed questionnaire. */
+export const RELAY_TITLE = "bot-lobby:ask_user_question";
+
+export function relayEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[ASK_ENV] === "1";
+}
+
+/** Where an agent saves the images it shows the user for a task: outside the repository, so they are never part of its change. */
+export function previewDir(taskId: string): string {
+  return join(tmpdir(), "bot-lobby-previews", taskId.replace(/[^\w.-]/g, "_"));
+}
+
+/** Image paths made absolute, so the master finds them whatever its cwd. */
+function withAbsoluteImages(questions: readonly AskQuestion[], cwd: string): AskQuestion[] {
+  return questions.map((question) => ({
+    ...question,
+    options: question.options.map((option) => (option.image && !isAbsolute(option.image) ? { ...option, image: resolve(cwd, option.image) } : option)),
+  }));
+}
+
+/** The answers the master sent back, or undefined when they do not read as answers. */
+export function readRelayAnswer(value: string | undefined): AskResult | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(value) as Partial<AskResult>;
+    if (!Array.isArray(parsed.answers) || typeof parsed.cancelled !== "boolean") return undefined;
+    return { answers: parsed.answers, cancelled: parsed.cancelled, ...(typeof parsed.globalNote === "string" ? { globalNote: parsed.globalNote } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+const text = (value: unknown): value is string => typeof value === "string";
+
+/** One relayed question as the questionnaire can show it, or undefined when it is not one. */
+function asQuestion(value: unknown): AskQuestion | undefined {
+  const raw = value as Partial<AskQuestion> | null;
+  if (!raw || !text(raw.question) || !text(raw.header) || !Array.isArray(raw.options)) return undefined;
+  const options = raw.options
+    .filter((option) => option && text(option.label))
+    .slice(0, MAX_OPTIONS)
+    .map((option) => ({
+      label: option.label,
+      ...(text(option.description) ? { description: option.description } : {}),
+      ...(text(option.preview) ? { preview: option.preview } : {}),
+      ...(text(option.image) ? { image: option.image } : {}),
+    }));
+  if (options.length === 0) return undefined;
+  return { question: raw.question, header: raw.header, options, ...(raw.multiSelect === true ? { multiSelect: true } : {}) };
+}
+
+/**
+ * The questions a relayed dialog carries, or undefined when it is not one.
+ * The master takes only what the questionnaire can show from them: the
+ * subagent checked them, but its process is not trusted to have.
+ */
+export function readRelayRequest(title: string | undefined, prefill: string | undefined): AskQuestion[] | undefined {
+  if (title !== RELAY_TITLE || !prefill) return undefined;
+  try {
+    const parsed = JSON.parse(prefill) as { questions?: unknown };
+    if (!Array.isArray(parsed.questions)) return undefined;
+    const questions = parsed.questions.slice(0, MAX_QUESTIONS).map(asQuestion);
+    return questions.length > 0 && questions.every(Boolean) ? (questions as AskQuestion[]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Inside a subagent: the questions go to the master as an RPC dialog, and its answers come back. */
+export const relayAsker: Asker = async (questions, ctx: ExtensionContext) => {
+  const value = await ctx.ui.editor(RELAY_TITLE, JSON.stringify({ questions: withAbsoluteImages(questions, ctx.cwd) }));
+  return readRelayAnswer(value) ?? { answers: [], cancelled: true };
+};

package/src/ask/state.ts

@@ -0,0 +1,160 @@
+/**
+ * The questionnaire as state and keys, with no terminal in sight: each key
+ * press is one pure step, so every path (pick, toggle, type your own answer,
+ * move between questions, submit, cancel) is tested directly.
+ *
+ * Every question lists its options, then a row for the user's own answer.
+ * Enter on an option answers a single-choice question and moves on; space
+ * toggles options of a multi-choice one and enter moves on. Answering the
+ * last question submits; ←/→ move between questions first. Esc stops typing,
+ * or puts the questions away.
+ */
+import type { AskAnswer, AskQuestion, AskResult } from "./types.ts";
+
+export type AskKey =
+  | { type: "up" }
+  | { type: "down" }
+  | { type: "left" }
+  | { type: "right" }
+  | { type: "enter" }
+  | { type: "space" }
+  | { type: "escape" }
+  | { type: "backspace" }
+  /** 1-9: pick (or toggle) that option. */
+  | { type: "digit"; value: number }
+  /** Typed or pasted text, only used while writing an answer. */
+  | { type: "text"; value: string };
+
+export interface AskState {
+  questions: readonly AskQuestion[];
+  /** The question in view. */
+  tab: number;
+  /** The focused row of each question: an option index, or `options.length` for the own-answer row. */
+  cursor: number[];
+  /** Options picked in each question (one for a single-choice question). */
+  picked: number[][];
+  /** The user's own answer to each question, when they wrote one. */
+  typed: Array<string | undefined>;
+  /** Writing the own answer of the question in view. */
+  editing: boolean;
+  draft: string;
+  /** Set once the user submits or puts the questions away. */
+  result?: AskResult;
+}
+
+export function initialState(questions: readonly AskQuestion[]): AskState {
+  return {
+    questions,
+    tab: 0,
+    cursor: questions.map(() => 0),
+    picked: questions.map(() => []),
+    typed: questions.map(() => undefined),
+    editing: false,
+    draft: "",
+  };
+}
+
+/** Whether a question has an answer yet. */
+export function isAnswered(state: AskState, index: number): boolean {
+  return (state.picked[index]?.length ?? 0) > 0 || Boolean(state.typed[index]?.trim());
+}
+
+/** The answers given, in the order asked; unanswered questions are left out. */
+export function answersOf(state: AskState): AskAnswer[] {
+  const answers: AskAnswer[] = [];
+  state.questions.forEach((question, index) => {
+    const picked = (state.picked[index] ?? []).map((option) => question.options[option]!.label);
+    const own = state.typed[index]?.trim();
+    if (question.multiSelect) {
+      const selected = own ? [...picked, own] : picked;
+      if (selected.length > 0) answers.push({ questionIndex: index, question: question.question, kind: "multi", answer: selected.join(", "), selected });
+    } else if (own) answers.push({ questionIndex: index, question: question.question, kind: "custom", answer: own });
+    else if (picked[0]) answers.push({ questionIndex: index, question: question.question, kind: "option", answer: picked[0] });
+  });
+  return answers;
+}
+
+function set<T>(list: readonly T[], index: number, value: T): T[] {
+  const next = [...list];
+  next[index] = value;
+  return next;
+}
+
+/** The next question, or the submitted result after the last one. */
+function advance(state: AskState): AskState {
+  if (state.tab < state.questions.length - 1) return { ...state, tab: state.tab + 1, editing: false, draft: "" };
+  return { ...state, editing: false, draft: "", result: { answers: answersOf(state), cancelled: false } };
+}
+
+function choose(state: AskState, option: number): AskState {
+  const question = state.questions[state.tab]!;
+  if (option < 0 || option >= question.options.length) return state;
+  if (question.multiSelect) {
+    const picked = state.picked[state.tab] ?? [];
+    const next = picked.includes(option) ? picked.filter((entry) => entry !== option) : [...picked, option].sort((a, b) => a - b);
+    return { ...state, cursor: set(state.cursor, state.tab, option), picked: set(state.picked, state.tab, next) };
+  }
+  // One answer to a single-choice question: picking an option replaces any words of the user's own.
+  return advance({ ...state, cursor: set(state.cursor, state.tab, option), picked: set(state.picked, state.tab, [option]), typed: set(state.typed, state.tab, undefined) });
+}
+
+function typing(state: AskState, key: AskKey): AskState {
+  switch (key.type) {
+    case "text":
+      return { ...state, draft: state.draft + key.value.replace(/[\r\n\t]+/g, " ") };
+    case "space":
+      return { ...state, draft: `${state.draft} ` };
+    case "digit":
+      return { ...state, draft: state.draft + String(key.value) };
+    case "backspace":
+      return { ...state, draft: [...state.draft].slice(0, -1).join("") };
+    case "escape":
+      return { ...state, editing: false, draft: "" };
+    case "enter": {
+      const own = state.draft.trim();
+      const question = state.questions[state.tab]!;
+      const typed = set(state.typed, state.tab, own || undefined);
+      // Your own words answer a single-choice question instead of a picked option.
+      const picked = own && !question.multiSelect ? set(state.picked, state.tab, []) : state.picked;
+      const next = { ...state, typed, picked, editing: false, draft: "" };
+      return own ? advance(next) : next;
+    }
+    default:
+      return state;
+  }
+}
+
+/** One key press. */
+export function step(state: AskState, key: AskKey): AskState {
+  if (state.result) return state;
+  if (state.editing) return typing(state, key);
+  const question = state.questions[state.tab];
+  if (!question) return { ...state, result: { answers: [], cancelled: false } };
+  const rows = question.options.length + 1;
+  const cursor = state.cursor[state.tab] ?? 0;
+  switch (key.type) {
+    case "up":
+      return { ...state, cursor: set(state.cursor, state.tab, (cursor - 1 + rows) % rows) };
+    case "down":
+      return { ...state, cursor: set(state.cursor, state.tab, (cursor + 1) % rows) };
+    case "left":
+      return state.tab > 0 ? { ...state, tab: state.tab - 1 } : state;
+    case "right":
+      return state.tab < state.questions.length - 1 ? { ...state, tab: state.tab + 1 } : state;
+    case "digit":
+      return choose(state, key.value - 1);
+    case "space":
+      return cursor < question.options.length && question.multiSelect ? choose(state, cursor) : state;
+    case "enter": {
+      if (cursor === question.options.length) return { ...state, editing: true, draft: state.typed[state.tab] ?? "" };
+      if (!question.multiSelect) return choose(state, cursor);
+      // A multi-choice question moves on with what is picked; with nothing picked, enter picks the focused option.
+      if (!isAnswered(state, state.tab)) return advance(choose(state, cursor));
+      return advance(state);
+    }
+    case "escape":
+      return { ...state, result: { answers: answersOf(state), cancelled: true } };
+    default:
+      return state;
+  }
+}

package/src/ask/tool.ts

@@ -0,0 +1,126 @@
+/**
+ * `ask_user_question`: the model asks instead of guessing, with typed options
+ * the user picks from (or answers in their own words). Registered by
+ * bot-lobby in every pi session it loads in, the lobby's or not, so pi needs
+ * no separate questionnaire extension. A subagent has no terminal: it gets
+ * the tool only when the master lets it ask (the designer), and its questions
+ * are relayed through the master (see relay.ts).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { isSubagentProcess } from "../pi/quiet.ts";
+import { askUser, type Asker } from "./dialog.ts";
+import { isImagePath } from "./image.ts";
+import { relayAsker, relayEnabled } from "./relay.ts";
+import { ASK_TOOL, MAX_HEADER, MAX_LABEL, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, RESERVED, type AskQuestion, type AskResult } from "./types.ts";
+
+export { ASK_TOOL };
+
+const OptionSchema = Type.Object({
+  label: Type.String({ maxLength: MAX_LABEL, description: `The option as the user sees and picks it: 1-5 words, at most ${MAX_LABEL} characters.` }),
+  description: Type.Optional(Type.String({ description: "What choosing it means: its trade-offs or consequences. Markdown." })),
+  preview: Type.Optional(Type.String({ description: "Markdown shown beside the options while this one is focused: a mockup, a code snippet, a diagram, a config. Only when seeing it helps the user compare." })),
+  image: Type.Optional(Type.String({ description: "Path to a PNG (or JPEG, GIF, WebP) shown with the preview: a screenshot or a rendered mockup of this option. Drawn as the image in terminals that can, as coloured blocks (PNG) elsewhere." })),
+});
+
+const QuestionSchema = Type.Object({
+  question: Type.String({ description: "The whole question, clear and specific, ending with a question mark. Markdown." }),
+  header: Type.String({ maxLength: MAX_HEADER, description: `A short chip naming the question (at most ${MAX_HEADER} characters), e.g. "Auth" or "Layout".` }),
+  options: Type.Array(OptionSchema, { minItems: MIN_OPTIONS, maxItems: MAX_OPTIONS, description: `${MIN_OPTIONS}-${MAX_OPTIONS} distinct options. Put the one you recommend first and end its label with "(Recommended)". The user can always answer in their own words instead.` }),
+  multiSelect: Type.Optional(Type.Boolean({ description: "True when several answers can apply together." })),
+});
+
+export const AskParams = Type.Object({
+  questions: Type.Array(QuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS, description: `1-${MAX_QUESTIONS} questions asked together.` }),
+});
+
+const DESCRIPTION = [
+  "Ask the user one to four questions with options to pick from, when the answer would change what you do and you would otherwise guess.",
+  "Each question has 2-4 options (the one you recommend first, its label ending in \"(Recommended)\"); the user can pick one (or several with multiSelect), or answer in their own words.",
+  "Questions, descriptions and previews are Markdown. Give options a `preview` when the user needs to see them to choose: a UI mockup, a layout sketch, a code snippet, a config; the focused option's preview shows beside the list. An option can also carry an `image` file (a screenshot, a rendered mockup).",
+  "Do not use it for yes/no confirmations of what you were already told to do, or for questions the conversation already answers.",
+].join(" ");
+
+const RELAYED = "Your questions reach the user through the oracle, and your clock stops while they answer. Ask only what is theirs to decide (a visual direction, a layout, a trade-off they care about), all at once; decide the rest yourself.";
+
+/** Why a set of questions cannot be asked as given, or undefined when it can. */
+export function invalidQuestions(questions: readonly AskQuestion[]): string | undefined {
+  const asked = new Set<string>();
+  for (const [index, question] of questions.entries()) {
+    const at = `question ${index + 1}`;
+    if (!question.question.trim()) return `${at} is empty`;
+    if (asked.has(question.question.trim().toLowerCase())) return `${at} repeats an earlier question`;
+    asked.add(question.question.trim().toLowerCase());
+    const labels = new Set<string>();
+    for (const option of question.options) {
+      const label = option.label.trim().toLowerCase();
+      if (!label) return `${at} has an option without a label`;
+      if (RESERVED.has(label)) return `${at}: "${option.label}" is kept for the user's own answer; leave it out`;
+      if (labels.has(label)) return `${at} has two options labelled "${option.label}"`;
+      if (option.image?.trim() && !isImagePath(option.image)) return `${at}: the image for "${option.label}" must be a .png, .jpg, .gif or .webp file`;
+      labels.add(label);
+    }
+  }
+  return undefined;
+}
+
+/** What the model reads back: each question with its answer, or that it was skipped. */
+export function answerSummary(questions: readonly AskQuestion[], result: AskResult): string {
+  if (result.cancelled && result.answers.length === 0) {
+    // A relay that could not ask anyone (auto mode) says why.
+    if (result.globalNote) return result.globalNote;
+    return "The user put the questions away without answering. Do not ask the same again right away: go on with your best judgement and say what you assumed, or ask something narrower.";
+  }
+  const lines = questions.map((question, index) => {
+    const answer = result.answers.find((entry) => entry.questionIndex === index);
+    const head = `${index + 1}. [${question.header}] ${question.question.replace(/\s+/g, " ").trim()}`;
+    if (!answer) return `${head}\n   → (not answered)`;
+    const text = answer.kind === "multi" ? (answer.selected ?? []).join(", ") : answer.answer ?? "";
+    return `${head}\n   → ${text}${answer.kind === "custom" ? " (in the user's own words)" : ""}${answer.notes ? `\n   note: ${answer.notes}` : ""}`;
+  });
+  return [
+    result.cancelled ? "The user answered some questions, then put the rest away:" : "The user answered:",
+    ...lines,
+    ...(result.globalNote ? ["", `Note: ${result.globalNote}`] : []),
+  ].join("\n");
+}
+
+/**
+ * Register `ask_user_question` in this pi session; in a subagent only when
+ * the master relays its questions. `ask` is swappable for tests.
+ */
+export function registerAskTool(pi: ExtensionAPI, ask?: Asker): void {
+  const subagent = isSubagentProcess();
+  if (subagent && !relayEnabled()) return;
+  const asker = ask ?? (subagent ? relayAsker : askUser);
+  pi.registerTool({
+    name: ASK_TOOL,
+    label: "Ask",
+    description: subagent ? `${DESCRIPTION} ${RELAYED}` : DESCRIPTION,
+    promptSnippet: "Ask the user structured questions with options (and previews) instead of guessing",
+    promptGuidelines: [
+      "Use ask_user_question when a real decision is the user's and the answer changes your work; batch related questions (at most four) into one call.",
+    ],
+    parameters: AskParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const questions = (params as { questions: AskQuestion[] }).questions;
+      const invalid = invalidQuestions(questions);
+      if (invalid) throw new Error(`${invalid}.`);
+      const result = await asker(questions, ctx, signal);
+      return { content: [{ type: "text", text: answerSummary(questions, result) }], details: result };
+    },
+    renderCall(args, theme) {
+      const questions = (args as { questions?: AskQuestion[] }).questions ?? [];
+      const heads = questions.map((question) => question.header).filter(Boolean).join(", ");
+      return new Text(`${theme.fg("toolTitle", theme.bold("ask"))} ${theme.fg("accent", `${questions.length} question${questions.length === 1 ? "" : "s"}`)}${heads ? ` ${theme.fg("muted", heads)}` : ""}`, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as AskResult | undefined;
+      if (!details) return new Container();
+      if (details.cancelled && details.answers.length === 0) return new Text(theme.fg("warning", "put away without answering"), 0, 0);
+      const lines = details.answers.map((answer) => `${theme.fg("success", "✓")} ${theme.fg("muted", answer.question.replace(/\s+/g, " ").slice(0, 60))} ${theme.fg("dim", "→")} ${theme.fg("accent", answer.kind === "multi" ? (answer.selected ?? []).join(", ") : answer.answer ?? "")}`);
+      return new Text(lines.join("\n"), 0, 0);
+    },
+  });
+}

package/src/ask/types.ts

@@ -0,0 +1,55 @@
+/**
+ * The questionnaire's shape: what a model (or the planning panel) asks, and
+ * what comes back. The same shape `ask_user_question` has had in pi, so a
+ * model's habits carry over: 1-4 questions, 2-4 options each, a short header,
+ * multi-select, and a per-option preview (Markdown: a mockup, a snippet, a
+ * diagram) shown beside the options.
+ */
+
+/** The questionnaire tool's name, in this session and in the agents that may ask. */
+export const ASK_TOOL = "ask_user_question";
+
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER = 16;
+export const MAX_LABEL = 60;
+
+/** The row under every question's options where the user writes their own answer. */
+export const OWN_ANSWER = "Type something.";
+
+/** Labels the questionnaire keeps for its own rows. */
+export const RESERVED = new Set(["other", OWN_ANSWER.toLowerCase(), "next"]);
+
+export interface AskOption {
+  label: string;
+  description?: string;
+  /** Markdown shown beside the options while this one is focused. */
+  preview?: string;
+  /** An image file (PNG, JPEG, GIF or WebP) shown with the preview: a screenshot, a rendered mockup. */
+  image?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  /** A short chip naming the question (a topic, or who asks it). */
+  header: string;
+  options: AskOption[];
+  multiSelect?: boolean;
+}
+
+export interface AskAnswer {
+  questionIndex: number;
+  question: string;
+  /** A picked option, the user's own words, or several picked options. */
+  kind: "option" | "custom" | "multi";
+  answer: string | null;
+  selected?: string[];
+  notes?: string;
+}
+
+export interface AskResult {
+  answers: AskAnswer[];
+  cancelled: boolean;
+  globalNote?: string;
+}

package/src/ask/view.ts

@@ -0,0 +1,159 @@
+/**
+ * The questionnaire drawn: a chip per question, the question in Markdown, its
+ * options (each with its description in Markdown), the row for your own
+ * answer, and — when options carry one — the focused option's preview in a
+ * box beside them (or under them in a narrow terminal). Pure: state in, lines
+ * out, exactly `width` columns and at most `height` rows.
+ */
+import { basename } from "node:path";
+import { textWidth } from "../width.ts";
+import { beside, bold, box, fill, fit, markdownLines, paint, wrap, type LobbyTheme } from "../lobby/layout.ts";
+import { imageLines, type ImagePreview } from "./image.ts";
+import { isAnswered, type AskState } from "./state.ts";
+import { OWN_ANSWER, type AskQuestion } from "./types.ts";
+
+/** Terminals at least this wide show the preview beside the options. */
+export const SIDE_BY_SIDE_MIN = 96;
+/** Rows the preview box keeps at least, and at most. */
+const PREVIEW_MIN = 6;
+const PREVIEW_MAX = 40;
+/** A preview box needs this many inner rows to draw an image in; smaller ones name the file. */
+const IMAGE_MIN_ROWS = 6;
+/** Option descriptions sit under their label, past the marker and number. */
+const DESCRIPTION_INDENT = 7;
+
+const RECOMMENDED = /\s*\(recommended\)\s*$/i;
+
+function chips(state: AskState, theme?: LobbyTheme): string {
+  if (state.questions.length === 1) return paint(theme, "muted", state.questions[0]!.header);
+  return state.questions
+    .map((question, index) => {
+      const label = ` ${index + 1} ${question.header}${isAnswered(state, index) ? " ✓" : ""} `;
+      if (index === state.tab) return bold(theme, paint(theme, "accent", `[${label.trim()}]`));
+      return paint(theme, isAnswered(state, index) ? "success" : "muted", label.trim());
+    })
+    .join(paint(theme, "dim", "  ·  "));
+}
+
+function optionLabel(label: string, focused: boolean, theme?: LobbyTheme): string {
+  const recommended = RECOMMENDED.test(label);
+  const plain = label.replace(RECOMMENDED, "");
+  const text = focused ? bold(theme, plain) : plain;
+  return recommended ? `${text} ${paint(theme, "success", "(Recommended)")}` : text;
+}
+
+/** The options and the own-answer row, each option with its description beneath. */
+function optionLines(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  const cursor = state.cursor[state.tab] ?? 0;
+  const picked = state.picked[state.tab] ?? [];
+  const lines: string[] = [];
+  question.options.forEach((option, index) => {
+    const focused = cursor === index && !state.editing;
+    const pointer = focused ? paint(theme, "accent", "›") : " ";
+    const mark = question.multiSelect ? (picked.includes(index) ? "☑" : "☐") : picked.includes(index) ? "●" : "○";
+    const lead = `${pointer} ${paint(theme, picked.includes(index) ? "accent" : "dim", mark)} ${paint(theme, "dim", `${index + 1}.`)} `;
+    const labelLines = wrap(optionLabel(option.label, focused, theme), Math.max(1, width - textWidth(lead)));
+    lines.push(`${lead}${labelLines[0] ?? ""}`, ...labelLines.slice(1).map((line) => `${" ".repeat(textWidth(lead))}${line}`));
+    if (option.description?.trim()) {
+      const indent = " ".repeat(DESCRIPTION_INDENT);
+      for (const line of markdownLines(option.description.trim(), Math.max(1, width - DESCRIPTION_INDENT), theme)) lines.push(line ? `${indent}${paint(theme, "muted", line)}` : "");
+    }
+  });
+  const ownFocused = cursor === question.options.length;
+  const pointer = ownFocused || state.editing ? paint(theme, "accent", "›") : " ";
+  const own = state.typed[state.tab];
+  const lead = `${pointer} ${paint(theme, own ? "accent" : "dim", "✎")}    `;
+  const room = Math.max(1, width - textWidth(lead));
+  if (state.editing) {
+    const draft = wrap(`${state.draft}▏`, room);
+    lines.push(`${lead}${paint(theme, "accent", draft[0] ?? "")}`, ...draft.slice(1).map((line) => `${" ".repeat(textWidth(lead))}${paint(theme, "accent", line)}`));
+  } else {
+    lines.push(`${lead}${own ? paint(theme, "accent", `“${own}”`) : paint(theme, ownFocused ? "text" : "dim", OWN_ANSWER)}`);
+  }
+  return lines;
+}
+
+interface Preview {
+  label: string;
+  text: string;
+  image?: string;
+}
+
+/** The preview to show: the focused option's, when any option in the question has one (Markdown or an image). */
+function previewOf(state: AskState, question: AskQuestion): Preview | undefined {
+  if (!question.options.some((option) => option.preview?.trim() || option.image?.trim())) return undefined;
+  const cursor = state.cursor[state.tab] ?? 0;
+  const option = question.options[cursor];
+  if (!option) return { label: OWN_ANSWER, text: "" };
+  return { label: option.label.replace(RECOMMENDED, ""), text: option.preview?.trim() ?? "", ...(option.image?.trim() ? { image: option.image.trim() } : {}) };
+}
+
+/** The image part of a preview: drawn when the box has room, else named. It never takes the box's last rows from the text entirely. */
+function imageBlock(preview: Preview, inner: number, innerRows: number, textRows: number, frame: AskFrame, theme?: LobbyTheme): string[] {
+  if (!preview.image) return [];
+  const loaded = frame.images?.get(preview.image);
+  const textRoom = textRows > 0 ? Math.min(textRows + 1, Math.max(2, Math.floor(innerRows / 3))) : 0;
+  const rows = innerRows - textRoom;
+  if (!loaded) return [paint(theme, "muted", `Image: ${preview.image}`)];
+  if (rows < IMAGE_MIN_ROWS) return [paint(theme, "muted", `Image: ${basename(preview.image)} (the terminal is too small to draw it)`)];
+  return imageLines(loaded, inner, rows, theme);
+}
+
+/** The preview in a box at most `rows` tall; an image keeps within `fits` rows, which the terminal surely shows. */
+function previewBox(preview: Preview, width: number, rows: number, theme: LobbyTheme | undefined, frame: AskFrame, fits = rows): string[] {
+  const inner = Math.max(1, width - 4);
+  const text = preview.text ? markdownLines(preview.text, inner, theme) : [];
+  const image = imageBlock(preview, inner, Math.min(rows, fits) - 2, text.length, frame, theme);
+  const joined = [...image, ...(image.length > 0 && text.length > 0 ? [""] : []), ...text];
+  const body = joined.length > 0 ? joined : [paint(theme, "dim", "No preview for this one.")];
+  const height = Math.max(3, Math.min(rows, body.length + 2));
+  const more = body.length > height - 2 ? `${body.length - (height - 2)} more lines` : "";
+  return box(width, height, body, { title: `Preview · ${preview.label}`, ...(more ? { right: more } : {}), theme });
+}
+
+function hints(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  const parts = state.editing
+    ? ["enter keep it", "esc back to the options"]
+    : [
+        "↑↓ move",
+        question.multiSelect ? "space pick · enter next" : "enter choose",
+        `1-${question.options.length} pick`,
+        ...(state.questions.length > 1 ? ["←→ questions"] : []),
+        "esc put away",
+      ];
+  return wrap(paint(theme, "dim", parts.join(" · ")), width);
+}
+
+/** Around the questions: who is asking (an agent the oracle relays for), and the option images, read beforehand. */
+export interface AskFrame {
+  from?: string;
+  images?: ReadonlyMap<string, ImagePreview>;
+}
+
+/** The whole questionnaire in a box, `width` wide and at most `height` rows. */
+export function renderAsk(state: AskState, width: number, height: number, theme?: LobbyTheme, frame: AskFrame = {}): string[] {
+  const question = state.questions[state.tab];
+  if (!question || width < 20 || height < 6) return [];
+  const inner = width - 4;
+  const head = [chips(state, theme), "", ...markdownLines(question.question, inner, theme), ""];
+  const foot = ["", ...hints(state, question, inner, theme)];
+  const preview = previewOf(state, question);
+  let body: string[];
+  if (preview && inner >= SIDE_BY_SIDE_MIN) {
+    const left = Math.floor(inner * 0.42);
+    const options = optionLines(state, question, left, theme);
+    const rows = Math.max(PREVIEW_MIN, Math.min(PREVIEW_MAX, height - 2 - head.length - foot.length));
+    const side = previewBox(preview, inner - left - 2, Math.max(rows, Math.min(options.length, PREVIEW_MAX)), theme, frame, rows);
+    body = beside([fill(options, Math.max(options.length, side.length), left), side], "  ");
+  } else {
+    const options = optionLines(state, question, inner, theme);
+    const room = height - 2 - head.length - foot.length - options.length - 1;
+    body = preview && room >= 3 ? [...options, "", ...previewBox(preview, inner, Math.min(PREVIEW_MAX, room), theme, frame)] : options;
+  }
+  const content = [...head, ...body, ...foot];
+  // Too tall for the terminal: the question and hints stay, the middle is cut.
+  const fitted = content.length > height - 2 ? [...content.slice(0, height - 2 - foot.length), ...foot] : content;
+  const count = state.questions.length > 1 ? `Question ${state.tab + 1} of ${state.questions.length}` : "Question";
+  const title = frame.from ? `${frame.from} asks · ${count}` : count;
+  return box(width, fitted.length + 2, fitted.map((line) => fit(line, inner)), { title, focused: true, theme });
+}