@hheei/pi-ask-user 0.0.0-stage → 0.1.0

package/dist/batch-prompt.js

@@ -0,0 +1,192 @@
+import { decodeKittyPrintable, Key, matchesKey, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
+import { AskComponent } from "./ask-prompt";
+import { INLINE_DOCK_RESERVED_ROWS } from "./constants";
+import { formatKeyList } from "./prompt-help";
+import { getOverlayMaxRenderLinesForRows, railRow } from "./prompt-layout";
+import { formatResponseSummary, } from "./response";
+/**
+ * One prompt for a whole `questions` batch: a page per question plus a review
+ * page. Each page is an AskComponent that stays alive, so drafts and checkboxes
+ * survive moving between pages. Answers are recorded per page and only the
+ * review page submits; esc that would cancel a page cancels the batch.
+ */
+export class BatchAskComponent {
+    questions;
+    settings;
+    tui;
+    theme;
+    keybindings;
+    onDone;
+    heading;
+    pages;
+    answers;
+    current = 0;
+    title = "";
+    confirmingSkips = false;
+    _focused = false;
+    constructor(questions, settings, tui, theme, keybindings, onDone, heading) {
+        this.questions = questions;
+        this.settings = settings;
+        this.tui = tui;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.onDone = onDone;
+        this.heading = heading;
+        this.answers = questions.map(() => undefined);
+        this.pages = questions.map((entry, index) => new AskComponent(entry, settings, tui, theme, keybindings, (result) => this.handlePageDone(index, result)));
+        this.updateChrome();
+    }
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        this._focused = value;
+        const page = this.pages[this.current];
+        if (page)
+            page.focused = value;
+    }
+    invalidate() {
+        for (const page of this.pages)
+            page.invalidate();
+    }
+    render(width) {
+        const page = this.pages[this.current];
+        return page ? page.render(width) : this.renderReview(width);
+    }
+    handleInput(data) {
+        const pageCount = this.questions.length + 1;
+        // Tab and shift+tab move between pages here; inside a page, arrows still
+        // move the option selection.
+        if (matchesKey(data, Key.tab)) {
+            this.goTo((this.current + 1) % pageCount);
+            return;
+        }
+        if (matchesKey(data, Key.shift("tab"))) {
+            this.goTo((this.current + pageCount - 1) % pageCount);
+            return;
+        }
+        const page = this.pages[this.current];
+        if (page) {
+            page.handleInput(data);
+            return;
+        }
+        this.handleReviewInput(data);
+    }
+    handlePageDone(index, result) {
+        if (result === null) {
+            this.onDone(null);
+            return;
+        }
+        this.answers[index] = result;
+        const count = this.questions.length;
+        for (let step = 1; step <= count; step++) {
+            const next = (index + step) % count;
+            if (!this.answers[next]) {
+                this.goTo(next);
+                return;
+            }
+        }
+        this.goTo(count);
+    }
+    goTo(target) {
+        const previous = this.pages[this.current];
+        if (previous)
+            previous.focused = false;
+        this.current = target;
+        this.confirmingSkips = false;
+        const next = this.pages[target];
+        if (next)
+            next.focused = this._focused;
+        this.updateChrome();
+        this.tui.requestRender();
+    }
+    updateChrome() {
+        const labels = this.questions.map((_, index) => {
+            const label = `${index + 1}${this.answers[index] ? "\u2713" : ""}`;
+            return index === this.current ? `[${label}]` : label;
+        });
+        const review = this.current === this.questions.length ? "[review]" : "review";
+        // The strip is one terminal row, so the heading's line breaks collapse here only.
+        const heading = this.heading ? ` \u00b7 ${this.heading.replace(/\s+/g, " ").slice(0, 40)}` : "";
+        this.title = `ask_user${heading} ${labels.join(" ")} \u00b7 ${review}`;
+        const hint = "\u21e5 questions";
+        for (const page of this.pages)
+            page.setBatchChrome(this.title, hint);
+    }
+    /** Submit from the review page; with unanswered questions, the first submit asks to confirm. */
+    submitReview() {
+        if (this.unansweredCount() > 0 && !this.confirmingSkips) {
+            this.confirmingSkips = true;
+            this.tui.requestRender();
+            return;
+        }
+        this.onDone(this.answers.map((response) => response ? { status: "answered", response } : { status: "skipped" }));
+    }
+    unansweredCount() {
+        return this.answers.filter((answer) => !answer).length;
+    }
+    handleReviewInput(data) {
+        if (this.keybindings.matches(data, "tui.select.cancel")) {
+            this.onDone(null);
+            return;
+        }
+        if (this.keybindings.matches(data, "tui.select.confirm")) {
+            this.submitReview();
+            return;
+        }
+        // Kitty's keyboard protocol can deliver digits as CSI-u sequences.
+        const key = decodeKittyPrintable(data) ?? data;
+        const jump = key.length === 1 ? Number.parseInt(key, 10) : Number.NaN;
+        if (jump >= 1 && jump <= this.questions.length)
+            this.goTo(jump - 1);
+    }
+    renderReview(width) {
+        const theme = this.theme;
+        const wrap = (text) => wrapTextWithAnsi(text, Math.max(1, width - 1));
+        const answerLines = this.questions.flatMap((entry, index) => {
+            const response = this.answers[index];
+            const marker = response ? theme.fg("success", "\u2713") : theme.fg("warning", "\u25cb");
+            return [
+                ...wrap(`${marker} ${theme.fg("text", `${index + 1}. ${entry.question}`)}`),
+                ...wrap(response
+                    ? `   ${theme.fg("dim", "\u2192")} ${theme.fg("accent", formatResponseSummary(response))}`
+                    : `   ${theme.fg("warning", "unanswered")}`),
+            ];
+        });
+        const unanswered = this.unansweredCount();
+        const confirmKey = formatKeyList(this.keybindings.getKeys("tui.select.confirm"));
+        const cancelKey = formatKeyList(this.keybindings.getKeys("tui.select.cancel"));
+        const hints = [
+            `${confirmKey} ${unanswered > 0 ? "submit with skips" : "submit"}`,
+            `1-${this.questions.length} edit`,
+            "\u21e5 questions",
+            `${cancelKey} cancel`,
+        ].join(" \u00b7 ");
+        const warning = this.confirmingSkips
+            ? theme.fg("warning", `${unanswered} unanswered \u2014 press ${confirmKey} again to submit`)
+            : undefined;
+        const footerLines = [...(warning ? wrap(warning) : []), ...wrap(theme.fg("dim", hints))];
+        // The title and the footer are fixed; the answers take what is left and are
+        // cut from the end, so a short prompt still shows the first ones.
+        const budget = Math.max(1, this.reviewLineCap() - 3 - footerLines.length);
+        return [
+            railRow(theme, width),
+            theme.fg("dim", this.title),
+            ...answerLines.slice(0, budget),
+            ...footerLines,
+            railRow(theme, width),
+        ];
+    }
+    /** Rows the review page may use, rails included. */
+    reviewLineCap() {
+        const rows = Number.isFinite(this.tui.terminal.rows) ? Math.floor(this.tui.terminal.rows) : 24;
+        const overlayCap = getOverlayMaxRenderLinesForRows(rows);
+        if (this.settings.displayMode === "overlay")
+            return overlayCap;
+        // Inline prompts sit in Pi's fullscreen input dock, which clips anything
+        // taller than what remains after the transcript's minimum row, the
+        // working status, and the 2-3 row footer. Components only learn their
+        // width, so stay within that space instead of growing with the content.
+        return Math.max(4, Math.min(overlayCap, rows - INLINE_DOCK_RESERVED_ROWS));
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+export declare const BATCH_MIN_QUESTIONS = 2;
+export declare const BATCH_MAX_QUESTIONS = 4;
+export type AskMode = "select" | "freeform";
+export declare const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+export declare const ASK_OVERLAY_MIN_RENDER_LINES = 8;
+export declare const ASK_OVERLAY_WIDTH = "92%";
+export declare const ASK_OVERLAY_MIN_WIDTH = 40;
+export declare const FREEFORM_SENTINEL = "\u270F\uFE0F Type custom response...";
+export declare const FREEFORM_LABEL = "Type something.";
+export declare const FREEFORM_HINT = "Enter a custom response";
+export declare const CONTEXT_TOGGLE_KEYS: readonly ["ctrl+e", "ctrl+x", "ctrl+y"];
+export declare const INLINE_CONTEXT_MAX_ROWS = 3;
+export declare const INLINE_DOCK_RESERVED_ROWS = 5;
+/** Section of `<agent-dir>/ext_settings.json` (and its project override) holding these preferences. */
+export declare const SETTINGS_SECTION = "askUser";

package/dist/constants.js

@@ -0,0 +1,17 @@
+import { Key } from "@earendil-works/pi-tui";
+export const BATCH_MIN_QUESTIONS = 2;
+export const BATCH_MAX_QUESTIONS = 4;
+export const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+export const ASK_OVERLAY_MIN_RENDER_LINES = 8;
+export const ASK_OVERLAY_WIDTH = "92%";
+export const ASK_OVERLAY_MIN_WIDTH = 40;
+export const FREEFORM_SENTINEL = "\u270f\ufe0f Type custom response...";
+export const FREEFORM_LABEL = "Type something.";
+export const FREEFORM_HINT = "Enter a custom response";
+export const CONTEXT_TOGGLE_KEYS = [Key.ctrl("e"), Key.ctrl("x"), Key.ctrl("y")];
+export const INLINE_CONTEXT_MAX_ROWS = 3;
+// Rows Pi's fullscreen layout keeps outside the input dock: the transcript's
+// minimum row, the working status, and up to three footer rows.
+export const INLINE_DOCK_RESERVED_ROWS = 5;
+/** Section of `<agent-dir>/ext_settings.json` (and its project override) holding these preferences. */
+export const SETTINGS_SECTION = "askUser";

package/dist/custom-prompt.d.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI, ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { AskDisplayMode } from "./schema";
+/** Report the session as blocked on the user (`herdr:blocked`) for the duration of `run`. */
+export declare function whileBlocked<T>(pi: ExtensionAPI, run: () => Promise<T>): Promise<T>;
+export interface CustomPromptRequest<T> {
+    signal?: AbortSignal | undefined;
+    timeout?: number | undefined;
+    displayMode: AskDisplayMode;
+    /** Absent when the host's own dialog answers the prompt, e.g. a question without options. */
+    createComponent?: (tui: TUI, theme: Theme, keybindings: KeybindingsManager, complete: (value: T | null) => void) => Component;
+    /** Non-TUI hosts (RPC, print) answer through dialogs instead of a custom surface. */
+    fallback: (signal: AbortSignal, deadline: number | undefined) => Promise<T | null>;
+}
+/**
+ * Runs one prompt and owns everything around it: the surface slot, the abort
+ * forwarding, and the timeout. `null` means the user cancelled, the deadline
+ * passed, or the host has no custom UI.
+ */
+export declare function runCustomPrompt<T>(pi: ExtensionAPI, ctx: ExtensionContext, request: CustomPromptRequest<T>): Promise<T | null>;

package/dist/custom-prompt.js

@@ -0,0 +1,56 @@
+import { openTuiSurface } from "@hheei/pi-ext-core";
+import { ASK_OVERLAY_MIN_WIDTH, ASK_OVERLAY_WIDTH } from "./constants";
+/** Report the session as blocked on the user (`herdr:blocked`) for the duration of `run`. */
+export async function whileBlocked(pi, run) {
+    pi.events.emit("herdr:blocked", { active: true, label: "Waiting for user response" });
+    try {
+        return await run();
+    }
+    finally {
+        pi.events.emit("herdr:blocked", { active: false });
+    }
+}
+function overlayOptions(displayMode) {
+    if (displayMode !== "overlay")
+        return undefined;
+    return {
+        anchor: "center",
+        width: ASK_OVERLAY_WIDTH,
+        minWidth: ASK_OVERLAY_MIN_WIDTH,
+        maxHeight: "85%",
+        margin: 1,
+    };
+}
+/**
+ * Runs one prompt and owns everything around it: the surface slot, the abort
+ * forwarding, and the timeout. `null` means the user cancelled, the deadline
+ * passed, or the host has no custom UI.
+ */
+export async function runCustomPrompt(pi, ctx, request) {
+    const { signal, timeout, displayMode, createComponent } = request;
+    const deadline = timeout && timeout > 0 ? Date.now() + timeout : undefined;
+    const local = new AbortController();
+    const abortLocally = () => local.abort(signal?.reason);
+    if (signal?.aborted)
+        return null;
+    signal?.addEventListener("abort", abortLocally, { once: true });
+    const timer = deadline === undefined ? undefined : setTimeout(abortLocally, timeout);
+    try {
+        if (ctx.mode !== "tui" || createComponent === undefined) {
+            return await request.fallback(local.signal, deadline);
+        }
+        const options = overlayOptions(displayMode);
+        const result = await openTuiSurface(pi, ctx, {
+            hostId: "ask-user",
+            signal: local.signal,
+            ...(options === undefined ? {} : { overlay: true, overlayOptions: options }),
+            create: ({ tui, theme, keybindings, close }) => createComponent(tui, theme, keybindings, close),
+        });
+        return result.status === "closed" ? result.value : null;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        signal?.removeEventListener("abort", abortLocally);
+    }
+}

package/dist/dialogs.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { type AskUIResult, type BatchAnswer } from "./response";
+import type { BatchQuestion } from "./schema";
+import type { QuestionOption } from "./single-select-layout";
+type DialogOptions = {
+    signal?: AbortSignal;
+    timeout?: number;
+};
+/** The host's text dialog, typed so the caller only deals with the answer. */
+export declare function askText(ui: DialogUI, prompt: string, placeholder: string, options: DialogOptions | undefined): Promise<string | undefined>;
+/** The two host dialog methods the RPC/headless fallback degrades to. */
+type DialogUI = Pick<ExtensionUIContext, "select" | "input">;
+/**
+ * RPC/headless fallback: use dialog methods (select/input) instead of the rich TUI overlay.
+ * ctx.ui.custom() returns undefined in RPC mode, so we degrade gracefully.
+ */
+export declare function askViaDialogs(ui: DialogUI, question: string, context: string | undefined, options: QuestionOption[], allowMultiple: boolean, allowFreeform: boolean, dialogOpts?: DialogOptions, deadline?: number): Promise<AskUIResult | null>;
+/**
+ * RPC/headless fallback for a `questions` batch: ask each question in turn
+ * with the select()/input() dialogs. There is no review step here, so
+ * cancelling any question cancels the whole batch, and every dialog stage
+ * shares one deadline.
+ */
+export declare function askBatchViaDialogs(ui: DialogUI, questions: BatchQuestion[], signal: AbortSignal | undefined, deadline: number | undefined, heading?: string): Promise<BatchAnswer[] | null>;
+export {};

package/dist/dialogs.js

@@ -0,0 +1,93 @@
+import { FREEFORM_SENTINEL } from "./constants";
+import { createFreeformResponse, createSelectionResponse, formatOptionsForMessage, isCancelledInput, } from "./response";
+function parseDialogSelections(input) {
+    return input
+        .split(",")
+        .map((selection) => selection.trim())
+        .filter(Boolean);
+}
+/** The host's text dialog, typed so the caller only deals with the answer. */
+export function askText(ui, prompt, placeholder, options) {
+    return ui.input(prompt, placeholder, options);
+}
+/** The host's single-choice dialog; `undefined` means the user dismissed it. */
+function askSelect(ui, prompt, options, dialogOptions) {
+    return ui.select(prompt, options, dialogOptions);
+}
+/**
+ * Runs one dialog stage with the time the deadline has left. `null` means the
+ * prompt was already cancelled or the deadline passed, so a host that answers
+ * late cannot continue the flow.
+ */
+async function runDialogStage(dialogOpts, deadline, run) {
+    if (dialogOpts?.signal?.aborted)
+        return null;
+    let options = dialogOpts;
+    if (deadline !== undefined) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        options = { ...dialogOpts, timeout: remaining };
+    }
+    const value = await run(options);
+    return dialogOpts?.signal?.aborted ? null : { value };
+}
+/**
+ * RPC/headless fallback: use dialog methods (select/input) instead of the rich TUI overlay.
+ * ctx.ui.custom() returns undefined in RPC mode, so we degrade gracefully.
+ */
+export async function askViaDialogs(ui, question, context, options, allowMultiple, allowFreeform, dialogOpts, deadline) {
+    const prompt = context ? `${question}\n\nContext:\n${context}` : question;
+    if (allowMultiple) {
+        const optionList = formatOptionsForMessage(options);
+        const selection = await runDialogStage(dialogOpts, deadline, (opts) => askText(ui, `${prompt}\n\nOptions (select one or more):\n${optionList}`, "Type your selection(s)...", opts));
+        const typed = selection?.value;
+        if (typed === undefined || isCancelledInput(typed))
+            return null;
+        const selections = parseDialogSelections(typed);
+        return selections.length === 0 ? null : createSelectionResponse(selections);
+    }
+    const selectOptions = options.map((option) => option.title);
+    if (allowFreeform)
+        selectOptions.push(FREEFORM_SENTINEL);
+    const selection = await runDialogStage(dialogOpts, deadline, (opts) => askSelect(ui, prompt, selectOptions, opts));
+    const value = selection?.value;
+    if (value === undefined || isCancelledInput(value))
+        return null;
+    if (value === FREEFORM_SENTINEL) {
+        const answer = await runDialogStage(dialogOpts, deadline, (opts) => askText(ui, prompt, "Type your answer...", opts));
+        const text = answer?.value;
+        if (text === undefined || isCancelledInput(text))
+            return null;
+        return createFreeformResponse(text);
+    }
+    return createSelectionResponse([value]);
+}
+/**
+ * RPC/headless fallback for a `questions` batch: ask each question in turn
+ * with the select()/input() dialogs. There is no review step here, so
+ * cancelling any question cancels the whole batch, and every dialog stage
+ * shares one deadline.
+ */
+export async function askBatchViaDialogs(ui, questions, signal, deadline, heading) {
+    const dialogOpts = signal ? { signal } : undefined;
+    const answers = [];
+    for (const [index, entry] of questions.entries()) {
+        const title = `${heading ? `${heading}\n` : ""}(${index + 1}/${questions.length}) ${entry.question}`;
+        let response;
+        if (entry.options.length === 0) {
+            const prompt = entry.context ? `${title}\n\nContext:\n${entry.context}` : title;
+            const answer = await runDialogStage(dialogOpts, deadline, (opts) => askText(ui, prompt, "Type your answer...", opts));
+            if (answer === null)
+                return null;
+            response = createFreeformResponse(answer.value);
+        }
+        else {
+            response = await askViaDialogs(ui, title, entry.context, entry.options, entry.allowMultiple, entry.allowFreeform, dialogOpts, deadline);
+        }
+        if (!response)
+            return null;
+        answers.push({ status: "answered", response });
+    }
+    return answers;
+}

package/dist/events.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AskResponse } from "./response";
+import type { QuestionOption } from "./single-select-layout";
+export interface AskEventSubject {
+    question: string;
+    context?: string | undefined;
+    options: QuestionOption[];
+}
+/** Position of a question inside a `questions` batch, attached to its ask:* events. */
+interface BatchPosition {
+    index: number;
+    total: number;
+}
+/**
+ * Every installed extension receives these events, so they carry only the
+ * question and the response kind; the context and the user's actual answer
+ * stay inside the tool result (#51).
+ */
+export declare function createAskEventEmitter(pi: ExtensionAPI): {
+    answered(subject: AskEventSubject, response: AskResponse, batch?: BatchPosition): void;
+    cancelled(subject: AskEventSubject, batch?: BatchPosition): void;
+};
+export {};

package/dist/events.js

@@ -0,0 +1,22 @@
+/**
+ * Every installed extension receives these events, so they carry only the
+ * question and the response kind; the context and the user's actual answer
+ * stay inside the tool result (#51).
+ */
+export function createAskEventEmitter(pi) {
+    return {
+        answered(subject, response, batch) {
+            pi.events.emit("ask:answered", {
+                question: subject.question,
+                response: { kind: response.kind },
+                ...(batch ? { batch } : {}),
+            });
+        },
+        cancelled(subject, batch) {
+            pi.events.emit("ask:cancelled", {
+                question: subject.question,
+                ...(batch ? { batch } : {}),
+            });
+        },
+    };
+}

package/dist/execute.d.ts

@@ -0,0 +1,5 @@
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AskBatchDetails, type AskToolDetails } from "./response";
+import { type AskParams } from "./schema";
+export declare function executeSingle(pi: ExtensionAPI, params: AskParams, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<AskToolDetails> | undefined, ctx: ExtensionContext): Promise<AgentToolResult<AskToolDetails>>;
+export declare function executeBatch(pi: ExtensionAPI, params: AskParams, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<AskBatchDetails> | undefined, ctx: ExtensionContext): Promise<AgentToolResult<AskBatchDetails>>;

package/dist/execute.js

@@ -0,0 +1,157 @@
+import { AskComponent } from "./ask-prompt";
+import { BatchAskComponent } from "./batch-prompt";
+import { runCustomPrompt, whileBlocked } from "./custom-prompt";
+import { askBatchViaDialogs, askText, askViaDialogs } from "./dialogs";
+import { createAskEventEmitter } from "./events";
+import { formatBatchAnswers, formatBatchForMessage, formatSingleForMessage } from "./format";
+import { resolvePromptSettings } from "./preferences";
+import { createFreeformResponse, formatResponseSummary, } from "./response";
+import { batchHeading, coerceOptions, malformedOptionsError, normalizeBatchQuestions, } from "./schema";
+/** Host text dialog for a prompt without options; shares the caller's deadline and abort. */
+async function askForText(ctx, question, context, signal, deadline) {
+    const prompt = context ? `${question}\n\nContext:\n${context}` : question;
+    const timeout = deadline === undefined ? undefined : Math.max(1, deadline - Date.now());
+    const answer = await askText(ctx.ui, prompt, "Type your answer...", {
+        signal,
+        ...(timeout === undefined ? {} : { timeout }),
+    });
+    // A host dialog that ignores the signal can still resolve after cancellation.
+    return signal.aborted ? null : createFreeformResponse(answer);
+}
+/** One prompt run: the surface, its deadline, the abort forwarding, and the dialog fallback. */
+async function runInteractive(pi, ctx, request) {
+    const { settings, createComponent } = request;
+    return await whileBlocked(pi, () => runCustomPrompt(pi, ctx, {
+        signal: request.signal,
+        timeout: request.timeout,
+        displayMode: settings.displayMode,
+        ...(createComponent === undefined ? {} : { createComponent }),
+        fallback: request.fallback,
+    }));
+}
+export async function executeSingle(pi, params, signal, onUpdate, ctx) {
+    const question = params.question;
+    if (typeof question !== "string") {
+        throw new Error("ask_user needs question (one focused question) or questions (2-4 independent questions).");
+    }
+    if (signal?.aborted) {
+        return {
+            content: [{ type: "text", text: "Cancelled" }],
+            details: { question, context: params.context, options: [], response: null, cancelled: true },
+        };
+    }
+    const settings = await resolvePromptSettings(params, signal);
+    const context = params.context?.trim() || undefined;
+    const rawOptions = params.options ?? [];
+    const options = coerceOptions(rawOptions);
+    if (rawOptions.length > 0 && options.length === 0) {
+        throw malformedOptionsError(rawOptions.length);
+    }
+    const prompt = {
+        question,
+        context,
+        options,
+        allowMultiple: params.allowMultiple ?? false,
+        allowFreeform: params.allowFreeform ?? true,
+    };
+    const base = { question, context, options, response: null, cancelled: false };
+    if (!ctx.hasUI || !ctx.ui) {
+        throw new Error(formatSingleForMessage({
+            question,
+            context,
+            options,
+            allowFreeform: prompt.allowFreeform,
+        }));
+    }
+    const events = createAskEventEmitter(pi);
+    const subject = { question, context, options };
+    if (options.length > 0) {
+        onUpdate?.({
+            content: [{ type: "text", text: "Waiting for user input..." }],
+            details: base,
+        });
+    }
+    const response = await runInteractive(pi, ctx, {
+        settings,
+        signal,
+        timeout: params.timeout_ms,
+        createComponent: options.length === 0
+            ? undefined
+            : (tui, theme, keybindings, complete) => new AskComponent(prompt, settings, tui, theme, keybindings, complete),
+        fallback: (fallbackSignal, deadline) => options.length === 0
+            ? askForText(ctx, question, context, fallbackSignal, deadline)
+            : askViaDialogs(ctx.ui, question, context, options, prompt.allowMultiple, prompt.allowFreeform, { signal: fallbackSignal }, deadline),
+    });
+    // A caller abort that lands while the prompt resolves still cancels the answer.
+    if (response === null || signal?.aborted) {
+        events.cancelled(subject);
+        return {
+            content: [{ type: "text", text: "User cancelled the question" }],
+            details: { ...base, cancelled: true },
+        };
+    }
+    events.answered(subject, response);
+    return {
+        content: [{ type: "text", text: `User answered: ${formatResponseSummary(response)}` }],
+        details: { ...base, response },
+    };
+}
+export async function executeBatch(pi, params, signal, onUpdate, ctx) {
+    const questions = normalizeBatchQuestions(params);
+    const heading = batchHeading(params);
+    const subjects = questions.map(({ question, context, options }) => ({
+        question,
+        context,
+        options,
+    }));
+    const details = (answers, cancelled) => ({
+        kind: "batch",
+        ...(heading ? { heading } : {}),
+        questions: subjects,
+        answers,
+        cancelled,
+    });
+    if (signal?.aborted) {
+        return {
+            content: [{ type: "text", text: "Cancelled" }],
+            details: details([], true),
+        };
+    }
+    const settings = await resolvePromptSettings(params, signal);
+    const events = createAskEventEmitter(pi);
+    if (!ctx.hasUI || !ctx.ui) {
+        throw new Error(formatBatchForMessage(questions, heading));
+    }
+    onUpdate?.({
+        content: [{ type: "text", text: "Waiting for user input..." }],
+        details: details([], false),
+    });
+    const answers = await runInteractive(pi, ctx, {
+        settings,
+        signal,
+        timeout: params.timeout_ms,
+        createComponent: (tui, theme, keybindings, complete) => new BatchAskComponent(questions, settings, tui, theme, keybindings, complete, heading),
+        fallback: (fallbackSignal, deadline) => askBatchViaDialogs(ctx.ui, questions, fallbackSignal, deadline, heading),
+    });
+    if (answers === null || signal?.aborted) {
+        subjects.forEach((subject, index) => {
+            events.cancelled(subject, { index, total: subjects.length });
+        });
+        return {
+            content: [{ type: "text", text: "User cancelled the questions" }],
+            details: details([], true),
+        };
+    }
+    // Skipped questions emit nothing; each answered one emits its usual event.
+    answers.forEach((answer, index) => {
+        const subject = subjects[index];
+        if (answer.status === "answered" && subject) {
+            events.answered(subject, answer.response, { index, total: subjects.length });
+        }
+    });
+    const result = details(answers, false);
+    return {
+        content: [{ type: "text", text: formatBatchAnswers(result) }],
+        details: result,
+    };
+}

package/dist/format.d.ts

@@ -0,0 +1,18 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type AskBatchDetails, type AskResponse } from "./response";
+import type { BatchQuestion } from "./schema";
+import type { QuestionOption } from "./single-select-layout";
+export declare function formatBatchAnswers(details: AskBatchDetails): string;
+/** Non-interactive hosts get the whole prompt as text, so the model can still ask. */
+export declare function formatSingleForMessage(input: {
+    question: string;
+    context: string | undefined;
+    options: QuestionOption[];
+    allowFreeform: boolean;
+}): string;
+export declare function formatBatchForMessage(questions: BatchQuestion[], heading?: string): string;
+/** Expanded-result block: every option with the selected ones marked. */
+export declare function formatOptionMarkers(theme: Theme, options: QuestionOption[], response: Extract<AskResponse, {
+    kind: "selection";
+}>, indent?: string): string;
+export declare function formatBatchResult(theme: Theme, details: AskBatchDetails, expanded: boolean): string;