@geoqiao/pi-ask 1.2.2 → 1.3.0

package/src/result-format.ts

@@ -13,13 +13,14 @@ export function formatResultLines(
 	for (const question of result.questions) {
 		const answer = result.answers[question.id];
 		if (!answer) {
+			lines.push(formatUnansweredLine(question.label, options.mode));
 			continue;
 		}
 
 		const answerLine = formatAnswerLine(question.label, answer, options.mode);
-		if (answerLine) {
-			lines.push(answerLine);
-		}
+		lines.push(
+			answerLine ?? formatUnansweredLine(question.label, options.mode)
+		);
 
 		if (hasPresentedTypeOverride(question.type, question.presentedType)) {
 			hasPresentationOverride = true;
@@ -44,6 +45,15 @@ export function formatResultLines(
 	return lines;
 }
 
+function formatUnansweredLine(
+	questionLabel: string,
+	mode: "summary" | "render"
+): string {
+	return mode === "summary"
+		? `${questionLabel}: (no answer)`
+		: `? ${questionLabel}: (no answer)`;
+}
+
 function formatAnswerLine(
 	questionLabel: string,
 	answer: AskResult["answers"][string],

package/src/result.ts

@@ -8,7 +8,7 @@ import type { AskResult } from "./types.ts";
 
 export function renderResultText(result: AskResult): string {
 	if (result.error) {
-		return "Invalid input";
+		return "Invalid tool payload";
 	}
 	if (result.cancelled) {
 		return CANCELLED_RESULT_TEXT;

package/src/resume-pending-ask.ts

@@ -0,0 +1,95 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
+import { successfulResponse } from "./ask-tool-helpers.ts";
+import {
+	appendPendingAskDismissal,
+	findPendingAskToolCall,
+	type PendingAskToolCall,
+} from "./pending-ask.ts";
+import type { RemoteAskRuntime } from "./remote-ask.ts";
+import { runAskFlow } from "./ui/controller.ts";
+
+const REOPEN_REASONS: ReadonlySet<SessionStartEvent["reason"]> = new Set([
+	"startup",
+	"resume",
+	"fork",
+]);
+const DISMISS_NOTICE =
+	"Unanswered ask_user form dismissed; use /ask:replay to reopen it.";
+
+export function registerPendingAskResume(
+	pi: ExtensionAPI,
+	remoteAsk: RemoteAskRuntime
+): void {
+	let reopening = false;
+
+	pi.on("session_start", (event, ctx) => {
+		if (reopening || ctx.mode !== "tui" || !REOPEN_REASONS.has(event.reason)) {
+			return;
+		}
+
+		const pendingAsk = findPendingAskToolCall(ctx);
+		if (!pendingAsk) {
+			return;
+		}
+
+		reopening = true;
+		queueMicrotask(() => {
+			reopenPendingAsk(pi, ctx, pendingAsk, remoteAsk)
+				.catch((error) => {
+					ctx.ui.notify(
+						`Could not reopen unanswered ask_user form: ${formatError(error)}`,
+						"error"
+					);
+				})
+				.finally(() => {
+					reopening = false;
+				});
+		});
+	});
+}
+
+async function reopenPendingAsk(
+	pi: Pick<ExtensionAPI, "appendEntry" | "sendUserMessage">,
+	ctx: ExtensionContext,
+	pendingAsk: PendingAskToolCall,
+	remoteAsk: RemoteAskRuntime
+): Promise<void> {
+	ctx.ui.notify(
+		`Reopening unanswered ask_user form: ${pendingAsk.params.questions.length} question(s).`,
+		"info"
+	);
+	ctx.ui.setWorkingVisible(false);
+
+	let result: Awaited<ReturnType<typeof runAskFlow>>;
+	try {
+		result = await runAskFlow(ctx, pendingAsk.params, {
+			remote: {
+				runtime: remoteAsk,
+				source: "ask:resume",
+				toolCallId: pendingAsk.toolCallId,
+			},
+		});
+	} finally {
+		ctx.ui.setWorkingVisible(true);
+	}
+
+	appendPendingAskDismissal(pi, pendingAsk.toolCallId);
+	if (result.cancelled) {
+		ctx.ui.notify(DISMISS_NOTICE, "info");
+		return;
+	}
+
+	const text = successfulResponse(result).content[0].text;
+	pi.sendUserMessage(
+		text,
+		ctx.isIdle() ? undefined : { deliverAs: "followUp" }
+	);
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/rpc/controller.ts

@@ -247,13 +247,14 @@ function formatTitle(
 }
 
 function formatOption(option: AskDisplayOption, optionIndex: number): string {
+	const recommendation = option.recommended ? " (recommended)" : "";
 	const description = option.description
 		? ` — ${compactText(option.description)}`
 		: "";
 	const preview = option.preview
 		? ` — Preview: ${compactText(option.preview)}`
 		: "";
-	return `${optionIndex + 1}. ${compactText(option.label)}${description}${preview}`;
+	return `${optionIndex + 1}. ${compactText(option.label)}${recommendation}${description}${preview}`;
 }
 
 function compactText(value: string): string {

package/src/schema.ts

@@ -1,17 +1,14 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
 export const AskOptionSchema = Type.Object({
-	value: Type.Optional(
-		Type.String({
-			description:
-				"Required machine-readable value returned for this option in the result",
-		})
-	),
-	label: Type.Optional(
-		Type.String({
-			description: "Required short visible option label shown in the list",
-		})
-	),
+	value: Type.String({
+		description:
+			"Required machine-readable value returned for this option in the result",
+	}),
+	label: Type.String({
+		description: "Required short visible option label shown in the list",
+	}),
 	description: Type.Optional(
 		Type.String({
 			description: "Optional one-line explanation to help the user choose",
@@ -23,28 +20,30 @@ export const AskOptionSchema = Type.Object({
 				"Optional preview content shown in the dedicated preview pane for preview questions",
 		})
 	),
-});
-
-export const AskQuestionSchema = Type.Object({
-	id: Type.Optional(
-		Type.String({
+	recommended: Type.Optional(
+		Type.Boolean({
 			description:
-				"Required stable question identifier used as the key in returned answers",
+				"Optional presentation marker for a grounded preference; use the description to explain the reason",
 		})
 	),
+});
+
+export const AskQuestionSchema = Type.Object({
+	id: Type.String({
+		description:
+			"Required stable question identifier used as the key in returned answers",
+	}),
 	label: Type.Optional(
 		Type.String({
 			description: "Short tab label, e.g. Goal, Audience, Tone, Scope",
 		})
 	),
-	prompt: Type.Optional(
-		Type.String({
-			description:
-				"Required direct question shown to the user; ask about one decision at a time",
-		})
-	),
+	prompt: Type.String({
+		description:
+			"Required direct question shown to the user; ask about one decision at a time",
+	}),
 	type: Type.Optional(
-		Type.String({
+		StringEnum(["single", "multi", "preview"] as const, {
 			description:
 				"Question type: `single` means one answer is expected, `multi` means multiple answers could reasonably be selected, and `preview` means options need preview-pane detail. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.",
 		})
@@ -72,3 +71,39 @@ export const AskParamsSchema = Type.Object({
 		description: "Questions to ask in the interactive clarification flow",
 	}),
 });
+
+const AnswerExtractionOptionSchema = Type.Object(
+	{
+		value: Type.String({ description: "Machine-readable option value" }),
+		label: Type.String({ description: "Short visible option label" }),
+		description: AskOptionSchema.properties.description,
+		preview: AskOptionSchema.properties.preview,
+		freeform: Type.Optional(
+			Type.Boolean({
+				description:
+					"Use only when the assistant offered no concrete choices and the user should type an answer",
+			})
+		),
+	},
+	{ additionalProperties: false }
+);
+
+const AnswerExtractionQuestionSchema = Type.Object({
+	id: Type.String({ description: "Stable snake_case question identifier" }),
+	label: AskQuestionSchema.properties.label,
+	prompt: Type.String({ description: "Direct question shown to the user" }),
+	type: AskQuestionSchema.properties.type,
+	required: AskQuestionSchema.properties.required,
+	options: Type.Array(AnswerExtractionOptionSchema, {
+		description:
+			"Choices explicitly offered by the assistant, or one freeform option when the user should type an answer",
+		minItems: 1,
+	}),
+});
+
+export const AnswerExtractionParamsSchema = Type.Object({
+	...AskParamsSchema.properties,
+	questions: Type.Array(AnswerExtractionQuestionSchema, {
+		description: "Questions extracted from the assistant message",
+	}),
+});

package/src/state/create.ts

@@ -12,7 +12,7 @@ export function createInitialState(
 	options: CreateInitialStateOptions = {}
 ) {
 	return createBaseState({
-		title: params.title,
+		title: params.title?.trim() || undefined,
 		questions: normalizeQuestions(params, options),
 	});
 }

package/src/state/normalize.ts

@@ -38,6 +38,51 @@ export function collectValidationIssues(
 	return collector.issues;
 }
 
+export function prepareAskParams(input: unknown): unknown {
+	if (!(isRecord(input) && Array.isArray(input.questions))) {
+		return input;
+	}
+	return {
+		...input,
+		questions: input.questions.map((question) => {
+			if (!(isRecord(question) && Array.isArray(question.options))) {
+				return question;
+			}
+			return {
+				...question,
+				options: question.options.map(prepareOption),
+			};
+		}),
+	};
+}
+
+function prepareOption(input: unknown): unknown {
+	if (!isRecord(input)) {
+		return input;
+	}
+	if (
+		input.label !== undefined &&
+		!(typeof input.label === "string" && !input.label.trim())
+	) {
+		return input;
+	}
+	if (typeof input.value !== "string") {
+		return input;
+	}
+	const words = input.value.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+	if (!words) {
+		return input;
+	}
+	return {
+		...input,
+		label: words.charAt(0).toUpperCase() + words.slice(1),
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 function normalizeQuestion(
 	question: AskQuestionInput,
 	index: number,
@@ -65,8 +110,11 @@ function normalizeOption(option: AskOption): AskOption {
 	return {
 		value: option.value.trim(),
 		label: option.label.trim(),
-		description: option.description?.trim(),
-		preview: option.preview?.trim(),
+		description: option.description?.trim() || undefined,
+		preview: option.preview?.trim() || undefined,
+		...(option.recommended === undefined
+			? {}
+			: { recommended: option.recommended }),
 		...(option.freeform ? { freeform: true } : {}),
 	};
 }
@@ -118,12 +166,6 @@ function validateQuestion(
 		`${questionPath}.id`,
 		`Question ${questionNumber}: duplicate question id "${questionId}"`
 	);
-	assertOptionalText(
-		question.label,
-		collector,
-		`${questionPath}.label`,
-		`Question ${questionNumber}: label must not be empty`
-	);
 	assertRequired(
 		question.prompt?.trim(),
 		collector,
@@ -218,18 +260,6 @@ function validateOption(
 		`${optionPath}.label`,
 		`${prefix}: label is required`
 	);
-	assertOptionalText(
-		option.description,
-		collector,
-		`${optionPath}.description`,
-		`${prefix}: description must not be empty`
-	);
-	assertOptionalText(
-		option.preview,
-		collector,
-		`${optionPath}.preview`,
-		`${prefix}: preview must not be empty`
-	);
 	if (questionType === "preview") {
 		assertRequired(
 			optionPreview,
@@ -287,17 +317,6 @@ function assertRequired(
 	}
 }
 
-function assertOptionalText(
-	value: string | undefined,
-	collector: IssueCollector,
-	path: string,
-	message: string
-) {
-	if (value !== undefined && !value.trim()) {
-		collector.add(path, message);
-	}
-}
-
 function assertUnique(
 	seen: Set<string>,
 	value: string | undefined,

package/src/state/result.ts

@@ -205,6 +205,9 @@ function cloneOption(option: AskState["questions"][number]["options"][number]) {
 		label: option.label,
 		...(option.description ? { description: option.description } : {}),
 		...(option.preview ? { preview: option.preview } : {}),
+		...(option.recommended === undefined
+			? {}
+			: { recommended: option.recommended }),
 	};
 }
 

package/src/types.ts

@@ -5,6 +5,7 @@ export interface AskOption {
 	freeform?: boolean;
 	label: string;
 	preview?: string;
+	recommended?: boolean;
 	value: string;
 }
 

package/src/ui/render-helpers.ts

@@ -311,16 +311,23 @@ export function mergeColumns(
 }
 
 export function measurePreviewLeftWidth(
-	options: Array<{ label: string; description?: string }>,
+	options: Array<{
+		description?: string;
+		label: string;
+		recommended?: boolean;
+	}>,
 	width: number
 ): number {
 	let widest = 0;
 	for (let index = 0; index < options.length; index++) {
 		const option = options[index];
+		const description = option.recommended
+			? `${UI_TEXT.recommendedMarker}${option.description ? ` | ${option.description}` : ""}`
+			: option.description;
 		widest = Math.max(
 			widest,
 			visibleWidth(`${index + 1}. ${option.label}`),
-			option.description ? visibleWidth(option.description) : 0
+			description ? visibleWidth(description) : 0
 		);
 	}
 

package/src/ui/render-question.ts

@@ -1,5 +1,9 @@
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { UI_DIMENSIONS } from "../constants/ui.ts";
+import {
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { UI_DIMENSIONS, UI_TEXT } from "../constants/ui.ts";
 import {
 	measurePreviewLeftWidth,
 	mergeColumns,
@@ -83,7 +87,13 @@ function renderStandardOption(
 		row.pointer,
 		" ".repeat(visibleWidth(row.pointer))
 	);
-	renderOptionDescription(lines, row.description, context.width, context.theme);
+	renderOptionSubtitle(
+		lines,
+		row.description,
+		row.recommended,
+		context.width,
+		context.theme
+	);
 	renderOptionDetail(lines, row.detail, context, {
 		suppressLeadingGap: !!row.description,
 	});
@@ -170,7 +180,7 @@ function renderPreviewOptionList(
 			row.pointer,
 			"  "
 		);
-		renderOptionDescription(lines, row.description, width, theme);
+		renderOptionSubtitle(lines, row.description, row.recommended, width, theme);
 	}
 	return lines;
 }
@@ -275,14 +285,36 @@ function renderInteractiveCustomOption(
 	});
 }
 
-function renderOptionDescription(
+function renderOptionSubtitle(
 	lines: string[],
 	description: string | undefined,
+	recommended: boolean,
 	width: number,
 	theme: Theme
 ) {
-	if (!description) {
+	if (!recommended) {
+		if (description) {
+			pushWrappedText(
+				lines,
+				description,
+				width,
+				theme,
+				"muted",
+				"     ",
+				"     "
+			);
+		}
 		return;
 	}
-	pushWrappedText(lines, description, width, theme, "muted", "     ", "     ");
+
+	const indent = "     ";
+	const text =
+		theme.fg("warning", UI_TEXT.recommendedMarker) +
+		(description ? theme.fg("muted", ` | ${description}`) : "");
+	for (const line of wrapTextWithAnsi(
+		text,
+		Math.max(1, width - visibleWidth(indent))
+	)) {
+		lines.push(truncateToWidth(`${indent}${line}`, width));
+	}
 }

package/src/ui/view-models/question.ts

@@ -30,6 +30,7 @@ export interface OptionRowModel {
 	label: string;
 	pointer: string;
 	prefix: string;
+	recommended: boolean;
 	selected: boolean;
 }
 
@@ -104,6 +105,7 @@ function buildOptionRowModel(
 		label: option.label,
 		pointer,
 		prefix: getOptionPrefix(question.type, option, answered),
+		recommended: option.recommended === true,
 		selected,
 	};
 }