@black942026/pi-ask-user 0.1.0 → 0.1.2

package/src/core.ts

@@ -1,4 +1,5 @@
 import { combineSignals, createDeadline, safeTimeoutMs } from "./deadline.ts";
+import { validateAnswer } from "./answers.ts";
 import { AskUserValidationError, normalizeAskUserRequest } from "./schema.ts";
 import type {
 	AskUIInput,
@@ -92,9 +93,17 @@ export async function askUserNormalized(
 	const effectiveRequest = applyPreferences(request, host.preferences);
 	const deadline = createDeadline(effectiveRequest.totalTimeoutMs, now);
 	const deadlineController = new AbortController();
+	const timeoutCancelled = new AbortController();
 	const linked = combineSignals(signal, deadlineController.signal);
 
 	const input: AskUIInput = { request: effectiveRequest, deadline, signal: linked.signal };
+	if (route === "custom") {
+		input.cancelTimeout = () => {
+			if (!deadline.cancel()) return false;
+			timeoutCancelled.abort();
+			return true;
+		};
+	}
 	if (onUpdate) input.onUpdate = onUpdate;
 
 	// Wait events are emitted exactly around a real UI attempt: `waitStarted`
@@ -138,12 +147,14 @@ export async function askUserNormalized(
 	}
 
 	// The core owns the guarantee: even a renderer that ignores its AbortSignal
-	// cannot hang the call. The deadline and the caller's cancellation are raced
-	// independently against the renderer; a late renderer result is ignored.
+	// cannot hang the call unless the user explicitly disables the timeout.
+	// The deadline and caller's cancellation are raced independently against
+	// the renderer; a late renderer result is ignored.
 	let race: DeadlineRace;
 	try {
-		race = await raceWithDeadline(renderPromise, deadline.remainingMs(), signal, () =>
-			deadlineController.abort(),
+		race = await raceWithDeadline(
+			renderPromise, deadline.remainingMs(), signal,
+			() => deadlineController.abort(), timeoutCancelled.signal,
 		);
 	} finally {
 		// Always release the listeners installed on the caller's signal.
@@ -178,7 +189,8 @@ type DeadlineRace =
  *
  * This is what makes the timeout guarantee independent of renderer behaviour: a
  * renderer that never resolves (or that ignores its signal) still yields
- * `timeout`. Late results are discarded, and the rejection path is always
+ * `timeout`, unless the user explicitly cancels the timeout. Late results are
+ * discarded, and the rejection path is always
  * handled so a late failure cannot become an unhandled rejection.
  */
 function raceWithDeadline(
@@ -186,15 +198,23 @@ function raceWithDeadline(
 	remainingMs: number,
 	callerSignal: AbortSignal | undefined,
 	onDeadline: () => void,
+	timeoutCancelled: AbortSignal,
 ): Promise<DeadlineRace> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	let abortHandler: (() => void) | undefined;
+	const clearDeadlineTimer = (): void => {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	};
 	const racers: Array<Promise<DeadlineRace>> = [
 		render.then(
 			(outcome): DeadlineRace => ({ kind: "outcome", outcome }),
 			(error): DeadlineRace => ({ kind: "outcome", outcome: { kind: "error", message: messageOf(error) } }),
 		),
 		new Promise<DeadlineRace>((resolve) => {
+			// Cancellation may happen synchronously during renderer construction.
+			if (timeoutCancelled.aborted) return;
+			timeoutCancelled.addEventListener("abort", clearDeadlineTimer, { once: true });
 			// `safeTimeoutMs` prevents a >32-bit delay from firing immediately.
 			timer = setTimeout(() => {
 				onDeadline();
@@ -215,7 +235,8 @@ function raceWithDeadline(
 		);
 	}
 	return Promise.race(racers).finally(() => {
-		if (timer) clearTimeout(timer);
+		clearDeadlineTimer();
+		timeoutCancelled.removeEventListener("abort", clearDeadlineTimer);
 		// Remove the listener when the render settled first, so repeated calls do
 		// not accumulate listeners on a long-lived caller signal.
 		if (abortHandler && callerSignal) callerSignal.removeEventListener("abort", abortHandler);
@@ -252,7 +273,15 @@ function mapOutcome(
 ): AskUserResult {
 	switch (outcome.kind) {
 		case "submitted": {
-			const answers = outcome.answers ?? [];
+			if (!Array.isArray(outcome.answers)) {
+				return {
+					status: "error",
+					route,
+					answers: [],
+					error: { code: "internal", message: `${route} UI returned a malformed answers payload.` },
+				};
+			}
+			const answers = outcome.answers;
 			if (answers.length !== request.questions.length) {
 				return {
 					status: "error",
@@ -264,15 +293,23 @@ function mapOutcome(
 					},
 				};
 			}
-			const empty = answers.find(
-				(answer) => answer.selections.length === 0 && (answer.freeText ?? "").trim() === "",
-			);
-			if (empty) {
+			for (let index = 0; index < answers.length; index += 1) {
+				const answer = answers[index]!;
+				let invalid: string | undefined;
+				try {
+					invalid = validateAnswer(request.questions[index]!, answer);
+				} catch (error) {
+					invalid = `answer validation failed: ${messageOf(error)}`;
+				}
+				if (!invalid) continue;
 				return {
 					status: "error",
 					route,
 					answers,
-					error: { code: "empty_answer", message: `The answer to question "${empty.title}" is empty.` },
+					error: {
+						code: invalid.includes("empty") || invalid.includes("missing") ? "empty_answer" : "internal",
+						message: `The ${route} UI returned an invalid answer for question "${request.questions[index]!.title}": ${invalid}.`,
+					},
 				};
 			}
 			return { status: "answered", route, answers };

package/src/deadline.ts

@@ -13,27 +13,43 @@ export function safeTimeoutMs(ms: number): number {
 	return Math.min(Math.floor(ms), MAX_SAFE_TIMEOUT_MS);
 }
 
+/** A shared deadline that the user can disable for the current questionnaire. */
+export interface CancellableDeadline extends Deadline {
+	/** Disable expiry. Returns false if the deadline has already expired. */
+	cancel(): boolean;
+}
+
 /**
  * Create a single overall deadline for a questionnaire.
  *
- * The deadline is always `timeoutMs` (which callers compute as
+ * The initial deadline is `totalMs` (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.
+ * the remaining time. `cancel()` disables expiry but does not clear any timers;
+ * the core and custom UI clear their timers separately. A deadline never
+ * degrades to another route.
  */
-export function createDeadline(totalMs: number, now: () => number = Date.now): Deadline {
+export function createDeadline(totalMs: number, now: () => number = Date.now): CancellableDeadline {
 	const startedAt = now();
 	const safeTotal = safeTimeoutMs(totalMs);
 	const expiresAt = safeTotal === 0 ? startedAt : startedAt + safeTotal;
+	let cancelled = false;
 	return {
 		startedAt,
-		expiresAt,
+		get expiresAt(): number {
+			return cancelled ? Infinity : expiresAt;
+		},
 		remainingMs(): number {
-			return Math.max(0, expiresAt - now());
+			return cancelled ? Infinity : Math.max(0, expiresAt - now());
 		},
 		expired(): boolean {
-			return now() >= expiresAt;
+			return !cancelled && now() >= expiresAt;
+		},
+		cancel(): boolean {
+			if (!cancelled && now() >= expiresAt) return false;
+			cancelled = true;
+			return true;
 		},
 	};
 }

package/src/index.ts

@@ -38,6 +38,7 @@ export {
 	DEFAULT_TIMEOUT_PER_QUESTION_MS,
 	LIMITS,
 	MAX_OPTIONS,
+	MAX_FORM_FIELDS,
 	MAX_QUESTIONS,
 	normalizeAskUserRequest,
 } from "./schema.ts";
@@ -77,6 +78,7 @@ export {
 	emptyDraft,
 	finalizeAnswers,
 	toAnswer,
+	validateAnswer,
 	type DraftAnswer,
 	type FinalizeResult,
 } from "./answers.ts";
@@ -98,7 +100,7 @@ export interface AskUserToolDetails {
 	progress?: string;
 }
 
-const DESCRIPTION = "Ask the user one or more structured questions through the host's interactive UI.";
+const DESCRIPTION = "Ask the user structured single-choice, multi-choice, text, boolean, or flat form questions through the host's interactive UI.";
 
 const PROMPT_SNIPPET = "Ask the user structured questions when you would otherwise guess.";
 
@@ -106,6 +108,7 @@ 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.",
+	"Use kind=bool for a real boolean. Use kind=simple-form with flat uniquely named fields when several typed values belong in one logical question; forms cannot nest.",
 ];
 
 /**
@@ -136,6 +139,12 @@ function describeRequestAsText(request: NormalizedRequest): string {
 			const description = option.description?.trim();
 			lines.push(`   ${optionIndex + 1}) ${option.label}${description ? ` — ${description}` : ""}`);
 		});
+		if (question.kind === "bool") lines.push("   answer: true or false");
+		for (const field of question.fields ?? []) {
+			lines.push(`   - ${field.label} [${field.name}: ${field.kind}]${field.required ? " required" : " optional"}`);
+			field.options.forEach((option, optionIndex) => lines.push(`      ${optionIndex + 1}) ${option.label}`));
+			if (field.hasDefault) lines.push(`      default: ${JSON.stringify(field.default)}`);
+		}
 		if (question.hasDefault && question.default !== undefined) lines.push(`   default: ${question.default}`);
 	});
 	return lines.join("\n");
@@ -151,6 +160,10 @@ function buildModelContent(result: AskUserResult, request: NormalizedRequest): s
 	switch (result.status) {
 		case "answered": {
 			const lines = result.answers.map((answer) => {
+				if (answer.value !== undefined) {
+					const suffix = answer.usedDefault ? " (default used)" : "";
+					return `- ${answer.title}: ${JSON.stringify(answer.value)}${suffix}`;
+				}
 				const parts: string[] = [];
 				if (answer.selections.length > 0) parts.push(answer.selections.join(", "));
 				if (answer.freeText) parts.push(answer.freeText);
@@ -211,7 +224,9 @@ export interface RegisterAskUserOptions {
 	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.
+	 * `<Pi agent directory>/ask-user.json` (normally `~/.pi/agent/ask-user.json`).
+	 * The directory follows Pi's `PI_CODING_AGENT_DIR`; there are no AskUser-specific
+	 * environment-variable preferences.
 	 */
 	configFile?: string | false;
 }

package/src/parse.ts

@@ -54,6 +54,9 @@ export function parseNativeAnswer(question: NormalizedQuestion, raw: string): Pa
 	if (question.kind === "input") {
 		return { ok: true, value: { selections: [], freeText: trimmed, empty: false } };
 	}
+	if (question.kind === "bool" || question.kind === "simple-form") {
+		return { ok: false, error: `${question.kind} uses typed native input and cannot be parsed as a legacy answer.` };
+	}
 
 	const pipeIndex = raw.indexOf("|");
 	const left = pipeIndex >= 0 ? raw.slice(0, pipeIndex) : raw;
@@ -115,5 +118,9 @@ export function nativeInputHint(question: NormalizedQuestion): string {
 				: "Free input. Reply with text to answer.";
 		case "input":
 			return "Free input. Reply with text to answer.";
+		case "bool":
+			return "Boolean. Reply with true or false.";
+		case "simple-form":
+			return "Form fields are asked one at a time.";
 	}
 }