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

package/src/deadline.ts

@@ -0,0 +1,78 @@
+import type { Deadline } from "./types.ts";
+
+/**
+ * Largest delay Node's `setTimeout` accepts (a 32-bit signed integer). Larger
+ * values are clamped by Node to ~1 ms, which would fire a timer immediately and
+ * turn a huge timeout into an instant one. We clamp instead.
+ */
+export const MAX_SAFE_TIMEOUT_MS = 2_147_483_647;
+
+/** Clamp a requested timeout to a value `setTimeout` can honour. */
+export function safeTimeoutMs(ms: number): number {
+	if (!Number.isFinite(ms) || ms <= 0) return 0;
+	return Math.min(Math.floor(ms), MAX_SAFE_TIMEOUT_MS);
+}
+
+/**
+ * Create a single overall deadline for a questionnaire.
+ *
+ * The deadline is always `timeoutMs` (which callers compute as
+ * `timeoutPerQuestionMs × questionCount`). It is clamped to
+ * {@link MAX_SAFE_TIMEOUT_MS} so `setTimeout` never overflows. Every interaction
+ * for the questionnaire shares this one deadline; native dialogs receive only
+ * the remaining time. A deadline never degrades to another route.
+ */
+export function createDeadline(totalMs: number, now: () => number = Date.now): Deadline {
+	const startedAt = now();
+	const safeTotal = safeTimeoutMs(totalMs);
+	const expiresAt = safeTotal === 0 ? startedAt : startedAt + safeTotal;
+	return {
+		startedAt,
+		expiresAt,
+		remainingMs(): number {
+			return Math.max(0, expiresAt - now());
+		},
+		expired(): boolean {
+			return now() >= expiresAt;
+		},
+	};
+}
+
+/** A signal plus the cleanup for the listeners it installed on its sources. */
+export interface LinkedSignal {
+	signal: AbortSignal;
+	/** Remove listeners from the source signals. Idempotent. */
+	dispose(): void;
+}
+
+/**
+ * Combine the caller's abort signal with a deadline-driven abort signal.
+ *
+ * Unlike `AbortSignal.any`, this returns an explicit `dispose()` so listeners
+ * installed on the caller's signal are removed once the interaction settles and
+ * do not accumulate across repeated calls.
+ */
+export function combineSignals(caller: AbortSignal | undefined, deadlineSignal: AbortSignal): LinkedSignal {
+	const controller = new AbortController();
+	const onDeadline = () => controller.abort(deadlineSignal.reason);
+	const onCaller = () => controller.abort(caller?.reason);
+	let disposed = false;
+
+	if (deadlineSignal.aborted) controller.abort(deadlineSignal.reason);
+	else deadlineSignal.addEventListener("abort", onDeadline, { once: true });
+
+	if (caller) {
+		if (caller.aborted) controller.abort(caller.reason);
+		else caller.addEventListener("abort", onCaller, { once: true });
+	}
+
+	return {
+		signal: controller.signal,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			deadlineSignal.removeEventListener("abort", onDeadline);
+			if (caller) caller.removeEventListener("abort", onCaller);
+		},
+	};
+}

package/src/events.ts

@@ -0,0 +1,96 @@
+/**
+ * Runtime event emission for the registered `ask_user` tool.
+ *
+ * These events carry *result semantics* that Pi's generic `ui_prompt_start` /
+ * `ui_prompt_end` do not: whether the wait ended with an answer, a dismissal, a
+ * timeout, or an error — and through which route.
+ *
+ * Two families are emitted:
+ *
+ *  1. `herdr:blocked` — `{ active: true, label, callId? }` only when the tool is
+ *     actually entering the interactive wait, and exactly one matching
+ *     `{ active: false, callId? }` afterwards, for every outcome (answered,
+ *     aborted, timeout, error). Invalid or unavailable requests never emit it,
+ *     because no UI is attempted.
+ *  2. `ask:answered` / `ask:aborted` / `ask:timeout` / `ask:error` — exactly once
+ *     per UI attempt, carrying the correlation id and the route/status. By
+ *     default the full question, answers, and free text are **never** broadcast;
+ *     only non-sensitive metadata leaves the extension.
+ *
+ * A direct {@link createAskUser} caller has no Pi event bus; it may inject an
+ * {@link AskUserEventSink} instead (or accept the deliberate absence). This
+ * module never fabricates access to a bus.
+ */
+import type { AskUserEventSink, AskUserResult, AskUserRoute } from "./types.ts";
+
+/** The minimal event-bus surface used here (structurally matches Pi's EventBus). */
+export interface AskEventBus {
+	emit(channel: string, data: unknown): void;
+}
+
+export const HERDR_BLOCKED = "herdr:blocked";
+export const ASK_ANSWERED = "ask:answered";
+export const ASK_ABORTED = "ask:aborted";
+export const ASK_TIMEOUT = "ask:timeout";
+export const ASK_ERROR = "ask:error";
+
+/** Fixed label for the blocked/idle indicator. */
+export const WAITING_LABEL = "Waiting for user response";
+
+function optionalCallId(callId: string | undefined): { callId?: string } {
+	return callId === undefined || callId === "" ? {} : { callId };
+}
+
+/**
+ * Build the Pi event-bus sink for one tool call. Returns `undefined` when no
+ * usable bus is present, so the caller emits nothing rather than faking it.
+ * Emission failures are swallowed: events must never break the interaction.
+ */
+export function createAskEventSink(bus: AskEventBus | undefined, callId?: string): AskUserEventSink | undefined {
+	if (!bus || typeof bus.emit !== "function") return undefined;
+	const emit = (channel: string, data: unknown): void => {
+		try {
+			bus.emit(channel, data);
+		} catch {
+			// An observer must never break the interaction.
+		}
+	};
+	return {
+		waitStarted(): void {
+			emit(HERDR_BLOCKED, { active: true, label: WAITING_LABEL, ...optionalCallId(callId) });
+		},
+		waitEnded(result: AskUserResult): void {
+			emit(HERDR_BLOCKED, { active: false, ...optionalCallId(callId) });
+			const correlation: { callId?: string; route?: AskUserRoute } = { ...optionalCallId(callId) };
+			if (result.route !== undefined) correlation.route = result.route;
+			switch (result.status) {
+				case "answered":
+					emit(ASK_ANSWERED, { ...correlation, status: "answered" });
+					break;
+				case "aborted":
+					emit(ASK_ABORTED, { ...correlation, status: "aborted", cancelledReason: result.cancelledReason ?? "user" });
+					break;
+				case "timeout":
+					emit(ASK_TIMEOUT, { ...correlation, status: "timeout" });
+					break;
+				case "error":
+					emit(ASK_ERROR, { ...correlation, status: "error", errorCode: result.error?.code });
+					break;
+			}
+		},
+	};
+}
+
+/** The outcome-event channel for a status, exposed for documentation/tests. */
+export function outcomeChannel(status: AskUserResult["status"]): string {
+	switch (status) {
+		case "answered":
+			return ASK_ANSWERED;
+		case "aborted":
+			return ASK_ABORTED;
+		case "timeout":
+			return ASK_TIMEOUT;
+		case "error":
+			return ASK_ERROR;
+	}
+}

package/src/index.ts

@@ -0,0 +1,358 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { createPiHost } from "./adapters/pi.ts";
+import { createAskEventSink } from "./events.ts";
+import { askUserNormalized } from "./core.ts";
+import { AskUserParams, normalizeAskUserRequest } from "./schema.ts";
+import type {
+	AskUserDisplayMode,
+	AskUserErrorCode,
+	AskUserHost,
+	AskUserMode,
+	AskUserResult,
+	AskUserRoute,
+	AskUserStatus,
+	NormalizedRequest,
+} from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Re-exports: reusable TypeScript surface for other extensions
+// ---------------------------------------------------------------------------
+
+export * from "./types.ts";
+export { askUser, askUserNormalized } from "./core.ts";
+export { createPiHost, createPiCustomRenderer, type PiHostOptions } from "./adapters/pi.ts";
+export { createAskUser, type AskUser, type CreateAskUserOptions } from "./ask.ts";
+export { createNativeRunner, type NativeDialogUI } from "./ui/native.ts";
+export {
+	AskUserComponent,
+	MIN_USABLE_ROWS,
+	SPLIT_MIN_WIDTH,
+	type AskUserTheme,
+	type CustomUIResult,
+} from "./ui/custom.ts";
+export { nativeInputHint, parseNativeAnswer, type ParsedAnswer, type ParseOutcome } from "./parse.ts";
+export {
+	AskUserValidationError,
+	AskUserParams,
+	DEFAULT_TIMEOUT_PER_QUESTION_MS,
+	LIMITS,
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	normalizeAskUserRequest,
+} from "./schema.ts";
+export { hostCapabilities, probeRoutes, createAskUserHost, askUserSupport, type CreateAskUserHostOptions } from "./route.ts";
+export { UI_MODES, isUIMode } from "./mode.ts";
+export {
+	AskUserConfigError,
+	DEFAULT_DISPLAY_MODE,
+	DEFAULT_OVERLAY_TOGGLE_KEY,
+	USER_CONFIG_DIR,
+	USER_CONFIG_PATH,
+	isAllowedOverlayToggleSpec,
+	normalizeOverlayToggleKey,
+	parseAskUserConfig,
+	parseAskUserOptions,
+	readAskUserConfigFile,
+	resolveAskUserConfig,
+	toUiPreferences,
+	type AskUserConfigOverrides,
+	type ResolvedAskUserConfig,
+} from "./config.ts";
+export {
+	ASK_ABORTED,
+	ASK_ANSWERED,
+	ASK_ERROR,
+	ASK_TIMEOUT,
+	HERDR_BLOCKED,
+	WAITING_LABEL,
+	createAskEventSink,
+	outcomeChannel,
+	type AskEventBus,
+} from "./events.ts";
+export { createDeadline, combineSignals, safeTimeoutMs, MAX_SAFE_TIMEOUT_MS, type LinkedSignal } from "./deadline.ts";
+export {
+	draftFromDefault,
+	draftIsEmpty,
+	emptyDraft,
+	finalizeAnswers,
+	toAnswer,
+	type DraftAnswer,
+	type FinalizeResult,
+} from "./answers.ts";
+
+// ---------------------------------------------------------------------------
+// Tool
+// ---------------------------------------------------------------------------
+
+export const TOOL_NAME = "ask_user";
+
+export interface AskUserToolDetails {
+	/** Absent when no route ran (invalid_request / invalid_config). */
+	route?: AskUserRoute;
+	status: AskUserStatus;
+	answers: AskUserResult["answers"];
+	warnings?: string[];
+	error?: AskUserResult["error"];
+	/** Present while streaming progress updates. */
+	progress?: string;
+}
+
+const DESCRIPTION = "Ask the user one or more structured questions through the host's interactive UI.";
+
+const PROMPT_SNIPPET = "Ask the user structured questions when you would otherwise guess.";
+
+const PROMPT_GUIDELINES = [
+	"Use ask_user when a choice is high-impact or ambiguous and you cannot infer the answer.",
+	"If the tool reports the UI could not run, ask the user the question yourself in ordinary text instead.",
+	"Never invent an answer; on aborted or timeout, report it plainly and do not re-ask.",
+];
+
+/**
+ * Error codes that mean the interactive UI could not be shown or run. For these
+ * the tool text advises the model to ask the user in ordinary text instead. An
+ * invalid questionnaire or an empty answer is *not* a UI failure.
+ */
+const UI_FAILURE_CODES: readonly AskUserErrorCode[] = [
+	"unsupported_mode",
+	"invalid_config",
+	"not_initialized",
+	"custom_ui_failed",
+	"native_ui_failed",
+];
+
+function isUIFailure(code: AskUserErrorCode | undefined): boolean {
+	return code !== undefined && UI_FAILURE_CODES.includes(code);
+}
+
+/** Render the questionnaire as plain text, used only in the fallback advice. */
+function describeRequestAsText(request: NormalizedRequest): string {
+	const lines: string[] = [];
+	if (request.header && request.header.trim() !== "") lines.push(request.header.trim());
+	request.questions.forEach((question, index) => {
+		const prompt = question.prompt?.trim();
+		lines.push(`${index + 1}. ${question.title}${prompt ? ` — ${prompt}` : ""}`);
+		question.options.forEach((option, optionIndex) => {
+			const description = option.description?.trim();
+			lines.push(`   ${optionIndex + 1}) ${option.label}${description ? ` — ${description}` : ""}`);
+		});
+		if (question.hasDefault && question.default !== undefined) lines.push(`   default: ${question.default}`);
+	});
+	return lines.join("\n");
+}
+
+/**
+ * Model-facing text for a tool result. UI-unavailable/display failures carry an
+ * explicit ordinary-text fallback (with the question content); timeouts and
+ * aborts do not, because the UI may already have been shown and re-asking would
+ * prompt the user twice. In every case the model is told not to invent an answer.
+ */
+function buildModelContent(result: AskUserResult, request: NormalizedRequest): string {
+	switch (result.status) {
+		case "answered": {
+			const lines = result.answers.map((answer) => {
+				const parts: string[] = [];
+				if (answer.selections.length > 0) parts.push(answer.selections.join(", "));
+				if (answer.freeText) parts.push(answer.freeText);
+				const value = parts.length > 0 ? parts.join(" | ") : "(empty)";
+				const suffix = answer.usedDefault ? " (default)" : "";
+				return `- ${answer.title}: ${value}${suffix}`;
+			});
+			return `The user answered:\n${lines.join("\n")}`;
+		}
+		case "aborted":
+			return result.cancelledReason === "abort"
+				? "The request was aborted before an answer. Do not invent one."
+				: "The user dismissed the interaction; no answer. Do not invent one or re-ask the same question.";
+		case "timeout":
+			return "No answer before the deadline. Do not invent one, and do not repeat the same prompt.";
+		case "error": {
+			const code = result.error?.code;
+			const base = `AskUser failed (${code ?? "internal"}): ${result.error?.message ?? "unknown error"}.`;
+			if (isUIFailure(code)) {
+				return [
+					base,
+					"The interactive UI could not complete the request. Ask the user the question yourself in ordinary text — this is a fallback message, not an answer:",
+					describeRequestAsText(request),
+					"Then wait for the user's reply; do not invent an answer.",
+				].join("\n");
+			}
+			if (code === "invalid_request") {
+				return `${base} Fix the request and retry the tool call. Do not invent an answer.`;
+			}
+			// Non-UI failures (empty_answer, internal): report plainly, no retry advice.
+			return `${base} Do not invent an answer; report the failure to the user.`;
+		}
+	}
+}
+
+function detailsOf(result: AskUserResult): AskUserToolDetails {
+	const details: AskUserToolDetails = { status: result.status, answers: result.answers };
+	if (result.route !== undefined) details.route = result.route;
+	if (result.warnings !== undefined) details.warnings = result.warnings;
+	if (result.error !== undefined) details.error = result.error;
+	return details;
+}
+
+export interface RegisterAskUserOptions {
+	/**
+	 * Explicit UI route for this registration: `custom` | `native`. It has the
+	 * highest precedence. When omitted, the route is read from the user config
+	 * file, else probed from the implementations the context supports (preferring
+	 * `custom`), at host creation — never per request. An invalid value, or a
+	 * route the environment cannot run, is an actionable error — never a fallback.
+	 */
+	mode?: AskUserMode;
+	/** Explicit display mode; overrides the config file and the model's request. */
+	displayMode?: AskUserDisplayMode;
+	/** Explicit overlay toggle key; `null` disables it. Overrides the config file. */
+	overlayToggleKey?: string | null;
+	/** Explicit timeout (ms) per question; overrides the config file and the request. */
+	timeoutPerQuestionMs?: number;
+	/**
+	 * Path to the user config file, or `false` to skip reading it. Defaults to
+	 * `~/.pi/ask-user/config.json`. There are no environment variables.
+	 */
+	configFile?: string | false;
+}
+
+/**
+ * Register the `ask_user` tool for the current extension runtime.
+ *
+ * The explicit options are captured here, at registration. The host is created
+ * once per session from the context delivered to `pi.on("session_start", ...)`,
+ * so the capability probe and the user config read run exactly once and every
+ * tool call reuses that host. The host is released on `session_shutdown`, which
+ * Pi also fires before a reload or session replacement, so the following
+ * `session_start` builds a fresh host (and re-reads the config) from the new
+ * context.
+ *
+ * Runtime events: when the tool really enters the interactive wait it emits
+ * `herdr:blocked` `{ active: true, ... }`, then exactly one matching
+ * `{ active: false, ... }`, plus one outcome event (`ask:answered`,
+ * `ask:aborted`, `ask:timeout`, or `ask:error`) carrying the call id and the
+ * route/status. Invalid or unavailable requests emit nothing. See `events.ts`.
+ *
+ * A route the environment cannot run, or a renderer that fails, is reported as
+ * an actionable error in the tool text (never a silent fallback and never an
+ * unanswered questionnaire handed back as if it were the user's answer).
+ */
+export function registerAskUser(pi: ExtensionAPI, options: RegisterAskUserOptions = {}): void {
+	let host: AskUserHost | undefined;
+
+	pi.on("session_start", (_event, ctx) => {
+		host = createPiHost(ctx, options);
+	});
+	pi.on("session_shutdown", () => {
+		host = undefined;
+	});
+
+	pi.registerTool<typeof AskUserParams, AskUserToolDetails>({
+		name: TOOL_NAME,
+		label: "Ask User",
+		description: DESCRIPTION,
+		promptSnippet: PROMPT_SNIPPET,
+		promptGuidelines: PROMPT_GUIDELINES,
+		executionMode: "sequential",
+		parameters: AskUserParams,
+		async execute(toolCallId, params, signal, onUpdate, _ctx: ExtensionContext) {
+			let request: NormalizedRequest;
+			let warnings: string[] = [];
+			try {
+				const normalized = normalizeAskUserRequest(params);
+				request = normalized.request;
+				warnings = normalized.warnings;
+			} catch (error) {
+				// An invalid questionnaire is a request error, not a UI failure: no
+				// ordinary-text fallback is offered here.
+				const message = error instanceof Error ? error.message : String(error);
+				const details: AskUserToolDetails = {
+					status: "error",
+					answers: [],
+					error: { code: "invalid_request", message },
+				};
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Invalid parameters: ${message} Fix the request and retry the tool call. Do not invent an answer.`,
+						},
+					],
+					details,
+				};
+			}
+
+			// The session-scoped host is the single source of truth for the route;
+			// no probe happens per call. A call before the session has started is an
+			// explicit error, not a fabricated "no UI" result.
+			const activeHost = host;
+			if (!activeHost) {
+				const result: AskUserResult = {
+					status: "error",
+					answers: [],
+					error: {
+						code: "not_initialized",
+						message: "AskUser has not finished session initialization (no session_start received).",
+					},
+				};
+				return { content: [{ type: "text" as const, text: buildModelContent(result, request) }], details: detailsOf(result) };
+			}
+
+			// Progress updates advertise the route actually in use; a host that
+			// cannot prompt has no route to advertise.
+			const onUpdateText = onUpdate
+				? (text: string) => {
+						const details: AskUserToolDetails = { status: "answered", answers: [], progress: text };
+						if (activeHost.support.status === "available") details.route = activeHost.support.route;
+						onUpdate({ content: [{ type: "text" as const, text }], details });
+					}
+				: undefined;
+			const askOptions: Parameters<typeof askUserNormalized>[1] = { host: activeHost };
+			if (signal) askOptions.signal = signal;
+			if (onUpdateText) askOptions.onUpdate = onUpdateText;
+			// The event sink is created per call so its correlation id is the tool
+			// call id. It is absent when the runtime exposes no usable event bus, in
+			// which case nothing is emitted rather than faking a bus.
+			const events = createAskEventSink(pi.events, toolCallId);
+			if (events) askOptions.events = events;
+
+			const result = await askUserNormalized(request, askOptions, warnings);
+
+			return {
+				content: [{ type: "text" as const, text: buildModelContent(result, request) }],
+				details: detailsOf(result),
+			};
+		},
+		renderCall(args, theme) {
+			const count = Array.isArray(args.questions) ? args.questions.length : 0;
+			const titles = Array.isArray(args.questions)
+				? args.questions
+						.map((question) => (question as { title?: unknown }).title)
+						.filter((title): title is string => typeof title === "string")
+						.join(" / ")
+				: "";
+			const label = `${TOOL_NAME} · ${count} question(s)`;
+			return new Text(theme.fg("toolTitle", label) + (titles ? theme.fg("muted", ` — ${titles}`) : ""), 0, 0);
+		},
+		renderResult(result, renderOptions, theme) {
+			const details = result.details as AskUserToolDetails | undefined;
+			const text =
+				result.content
+					.filter((block) => block.type === "text")
+					.map((block) => (block as { text?: string }).text ?? "")
+					.join("\n") || "";
+			if (renderOptions.isPartial) {
+				return new Text(theme.fg("muted", text || "Waiting for user input…"), 0, 0);
+			}
+			const status = details?.status ?? "error";
+			const tone = status === "answered" ? "success" : status === "error" ? "error" : "warning";
+			const header = theme.fg(tone, `${TOOL_NAME}: ${status} (${details?.route ?? "?"})`);
+			return new Text(`${header}\n${theme.fg("toolOutput", text)}`, 0, 0);
+		},
+	});
+}
+
+/** Pi extension entry point. */
+export default function askUserExtension(pi: ExtensionAPI): void {
+	registerAskUser(pi);
+}

package/src/mode.ts

@@ -0,0 +1,18 @@
+import type { AskUserMode } from "./types.ts";
+
+/**
+ * The UI routes AskUser supports, in probe-priority order.
+ *
+ * A route is never read from the environment: it is either passed explicitly to
+ * the host-factory (`createAskUserHost({ mode })`, `createPiHost(ctx, { mode })`,
+ * `registerAskUser(pi, { mode })`) or discovered from the implementations
+ * the host can really bind (see `createAskUserHost`). Model tool parameters can
+ * never influence it.
+ */
+
+/** The accepted routes, in documentation and probe-priority order. */
+export const UI_MODES: readonly AskUserMode[] = ["custom", "native"];
+
+export function isUIMode(value: unknown): value is AskUserMode {
+	return typeof value === "string" && (UI_MODES as readonly string[]).includes(value);
+}

package/src/parse.ts

@@ -0,0 +1,119 @@
+import type { NormalizedQuestion } from "./types.ts";
+
+/**
+ * Parsing of native-dialog answers.
+ *
+ * The native route uses exactly one Pi native input dialog per question. The
+ * number and the optional trailing free text live in the same box:
+ *
+ *   single:  `2`            `2 | note`        `<free text>`
+ *   multi:   `1,3`          `1,3 | note`      `<free text>`
+ *   input:   `<free text>`
+ *
+ * The left-hand side of the first `|` is classified as an option-number list or
+ * as free text. The rules are deliberately strict so a malformed number list is
+ * re-prompted instead of being silently treated as prose:
+ *
+ *  1. If the left side contains only digits and separators (` ` `,` `，` `、`),
+ *     it is an option-number list. Tokens are validated for range and count.
+ *  2. Otherwise, if the left side begins with a digit run immediately followed by
+ *     a list separator (`,` `，` `、` `.`) — e.g. `1,a`, `1.5`, `2, please` — it is
+ *     a malformed option-number list and is rejected, not guessed as free text.
+ *  3. Otherwise the whole input is free text. This covers prose such as
+ *     `2 options please` (a space after the digit, not a list separator).
+ *
+ * To answer with prose that starts like a number list, write it after an empty
+ * left side: `| 1, please explain`. An empty left side always means free input.
+ */
+
+export interface ParsedAnswer {
+	selections: number[];
+	freeText?: string;
+	empty: boolean;
+}
+
+export type ParseOutcome = { ok: true; value: ParsedAnswer } | { ok: false; error: string };
+
+const PURE_DIGITS = /^\d+$/;
+/** digits + separators only (spaces, ASCII/CJK commas, enumeration comma). */
+const DIGIT_SEPARATOR_ONLY = /^[\d\s,\uFF0C\u3001]+$/;
+/** a digit run immediately followed by a list separator ⇒ a number-list attempt. */
+const NUMBER_LIST_ATTEMPT = /^\d+\s*[.,\uFF0C\u3001]/;
+
+function splitOnSeparators(value: string): string[] {
+	return value.split(/[,\uFF0C\u3001\s]+/).filter((token) => token.length > 0);
+}
+
+export function parseNativeAnswer(question: NormalizedQuestion, raw: string): ParseOutcome {
+	const trimmed = raw.trim();
+	if (trimmed === "") {
+		return { ok: true, value: { selections: [], empty: true } };
+	}
+
+	// Free-text-only questions take the whole box verbatim.
+	if (question.kind === "input") {
+		return { ok: true, value: { selections: [], freeText: trimmed, empty: false } };
+	}
+
+	const pipeIndex = raw.indexOf("|");
+	const left = pipeIndex >= 0 ? raw.slice(0, pipeIndex) : raw;
+	const right = pipeIndex >= 0 ? raw.slice(pipeIndex + 1) : "";
+	const comment = right.trim();
+	const leftTrim = left.trim();
+
+	// No number in the box: the (optional) right side is the free input.
+	if (leftTrim === "") {
+		return { ok: true, value: { selections: [], freeText: comment, empty: comment === "" } };
+	}
+
+	const isStrictList = DIGIT_SEPARATOR_ONLY.test(leftTrim);
+	const isListAttempt = isStrictList || NUMBER_LIST_ATTEMPT.test(leftTrim);
+	if (!isListAttempt) {
+		// Free text, taken verbatim including any `|`.
+		return { ok: true, value: { selections: [], freeText: trimmed, empty: false } };
+	}
+
+	// Tokens are separated only by commas/spaces; a stray character such as `.`
+	// or a letter makes the whole thing an invalid number list (re-prompt).
+	const tokens = splitOnSeparators(leftTrim);
+	const bad = tokens.find((token) => !PURE_DIGITS.test(token));
+	if (bad !== undefined || tokens.length === 0) {
+		return { ok: false, error: `Invalid number: "${leftTrim}" is not a valid option-number list.` };
+	}
+
+	const indices = tokens.map((token) => Number.parseInt(token, 10) - 1);
+	const max = question.options.length;
+	const outOfRange = indices.find((idx) => idx < 0 || idx >= max);
+	if (outOfRange !== undefined) {
+		return { ok: false, error: `Number out of range: enter a number between 1 and ${max}.` };
+	}
+
+	const unique = [...new Set(indices)];
+	if (question.kind === "single" && unique.length > 1) {
+		return { ok: false, error: "This is a single-select question; enter only one number." };
+	}
+
+	const ordered = question.kind === "single" ? unique : [...unique].sort((a, b) => a - b);
+	const value: ParsedAnswer = {
+		selections: question.kind === "single" ? [ordered[0]!] : ordered,
+		empty: false,
+	};
+	if (comment !== "") value.freeText = comment;
+	return { ok: true, value };
+}
+
+/** Render the per-question input instruction used by the native route. */
+export function nativeInputHint(question: NormalizedQuestion): string {
+	switch (question.kind) {
+		case "single":
+			return question.options.length > 0
+				? 'Single select. Reply with a number (e.g. 2), or "2 | note", or just reply with free text.'
+				: "Free input. Reply with text to answer.";
+		case "multi":
+			return question.options.length > 0
+				? 'Multi select. Reply with numbers separated by commas (e.g. 1,3), or "1,3 | note", or just reply with free text.'
+				: "Free input. Reply with text to answer.";
+		case "input":
+			return "Free input. Reply with text to answer.";
+	}
+}