@geoqiao/pi-ask 1.2.3 → 1.3.0

package/src/ask-tool-helpers.ts

@@ -13,13 +13,15 @@ import type {
 } from "./types.ts";
 
 export const ASK_TOOL_DESCRIPTION =
-	"Interactive clarification tool for cases where the next step depends on user preferences, missing requirements, or choosing between multiple valid directions. Ask a short structured interview, collect normalized answers, and continue using those answers explicitly instead of guessing. TUI mode supports single-select, multi-select, and preview-pane questions; RPC mode presents questions sequentially, offers one portable choice per question plus a typed-answer fallback, and flattens preview details into option text. Always include a machine-readable `value` for every option. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.";
+	"Interactive clarification tool for cases where the next step depends on user preferences, missing requirements, or choosing between multiple valid directions. Ask a short structured interview, collect normalized answers, and continue using those answers explicitly instead of guessing. TUI mode supports single-select, multi-select, and preview-pane questions; RPC mode presents questions sequentially, offers one portable choice per question plus a typed-answer fallback, and flattens preview details into option text. Always include a stable `id` and non-empty `prompt` for every question, plus a machine-readable `value` and visible `label` for every option. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.";
 
 export const ASK_TOOL_PROMPT_GUIDELINES = [
 	"Use `ask_user` before making preference-sensitive decisions about scope, tone, UX, naming, architecture, docs, or implementation direction.",
 	"When multiple valid directions exist, call `ask_user` with 1-3 concise questions instead of committing to one path on your own.",
 	"When calling `ask_user`, prefer one focused decision per question. Use short labels. Provide clear, distinct options. Do not add filler options.",
-	"When calling `ask_user`, always include a non-empty machine-readable `value` for every option.",
+	"When calling `ask_user`, always include a stable `id` and non-empty `prompt` for every question.",
+	"When calling `ask_user`, always include a non-empty machine-readable `value` and visible `label` for every option.",
+	"When calling `ask_user`, mark grounded preferences with `recommended: true` and use the option `description` to state the reason.",
 	"When calling `ask_user`, choose question `type` from the question semantics: `single` means one answer is expected, `multi` means multiple answers could reasonably be selected, and `preview` means options need preview-pane detail.",
 	'When calling `ask_user`, use `type: "preview"` only when every option includes non-empty `preview` text. Option descriptions do not satisfy this requirement.',
 	"After an `ask_user` elaboration or follow-up note, prefer another structured `ask_user` follow-up if a choice is still needed instead of switching to plain-text multiple choice in chat.",
@@ -89,7 +91,7 @@ export function renderAskToolCall(args: unknown, theme: ToolTheme) {
 		? params.questions
 				.map(
 					(question: AskQuestionInput, index) =>
-						question.label || `Q${index + 1}`
+						question.label?.trim() || `Q${index + 1}`
 				)
 				.join(", ")
 		: "";
@@ -113,17 +115,16 @@ export function renderAskToolResult(
 	theme: ToolTheme
 ) {
 	const details = result.details;
-	if (!details) {
+	if (!(details && Array.isArray(details.questions))) {
 		const text = result.content[0];
 		return new Text(text?.type === "text" ? (text.text ?? "") : "", 0, 0);
 	}
-	if (details.error) {
-		return new Text(theme.fg("warning", "Invalid input"), 0, 0);
-	}
-	if (details.cancelled) {
-		return new Text(theme.fg("warning", "Cancelled"), 0, 0);
-	}
-	return new Text(renderResultText(details), 0, 0);
+	const text = renderResultText(details);
+	return new Text(
+		details.error || details.cancelled ? theme.fg("warning", text) : text,
+		0,
+		0
+	);
 }
 
 function errorResultDetails(

package/src/ask-tool.ts

@@ -17,6 +17,7 @@ import { getAskConfigStore } from "./config/store.ts";
 import type { RemoteAskRuntime } from "./remote-ask.ts";
 import { runRpcAskFlow } from "./rpc/controller.ts";
 import { AskParamsSchema } from "./schema.ts";
+import { prepareAskParams } from "./state/normalize.ts";
 import type { AskParams } from "./types.ts";
 import { runAskFlow } from "./ui/controller.ts";
 
@@ -32,6 +33,7 @@ export function registerAskTool(
 			"Clarify ambiguous or preference-sensitive decisions with a short interactive interview before proceeding",
 		promptGuidelines: [...ASK_TOOL_PROMPT_GUIDELINES],
 		parameters: AskParamsSchema,
+		prepareArguments: (args) => prepareAskParams(args) as AskParams,
 		execute: (toolCallId, params, signal, onUpdate, ctx) =>
 			executeAskTool(
 				pi,

package/src/constants/ui.ts

@@ -14,6 +14,7 @@ export const UI_DIMENSIONS = {
 } as const;
 
 export const UI_TEXT = {
+	recommendedMarker: "(recommended)",
 	questionNoteTitle: "Note:",
 	reviewTitle: "Review answers",
 	unanswered: "→ unanswered",

package/src/index.ts

@@ -6,6 +6,7 @@ import { registerAskSettingsCommand } from "./ask-settings-command.ts";
 import { registerAskTool } from "./ask-tool.ts";
 import { resetAskConfigStore } from "./config/store.ts";
 import { createRemoteAskRuntime } from "./remote-ask.ts";
+import { registerPendingAskResume } from "./resume-pending-ask.ts";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const CONFIGURATION_DOC_PATH = resolve(
@@ -27,4 +28,5 @@ export default function askExtension(pi: ExtensionAPI) {
 	registerAskTool(pi, remoteAsk);
 	registerAskSettingsCommand(pi);
 	registerAnswerCommands(pi, remoteAsk);
+	registerPendingAskResume(pi, remoteAsk);
 }

package/src/pending-ask.ts

@@ -0,0 +1,128 @@
+import type { ToolCall } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+import { findPayloadForSourceEntry } from "./ask-payload-store.ts";
+import { validateParams } from "./ask-tool-helpers.ts";
+import { AskParamsSchema } from "./schema.ts";
+import type { AskParams } from "./types.ts";
+
+export const ASK_PENDING_DISMISSED_ENTRY_TYPE = "ask:pending-dismissed";
+const ASK_TOOL_NAME = "ask_user";
+
+export interface PendingAskToolCall {
+	params: AskParams;
+	toolCallId: string;
+}
+
+export function appendPendingAskDismissal(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	toolCallId: string
+): void {
+	pi.appendEntry(ASK_PENDING_DISMISSED_ENTRY_TYPE, { toolCallId });
+}
+
+export function findPendingAskToolCall(
+	ctx: Pick<ExtensionContext, "sessionManager">
+): PendingAskToolCall | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	const resolvedToolCallIds = collectResolvedToolCallIds(branch);
+
+	for (let entryIndex = branch.length - 1; entryIndex >= 0; entryIndex--) {
+		const toolCall = findUnresolvedAskToolCall(
+			branch[entryIndex],
+			resolvedToolCallIds
+		);
+		if (!toolCall) {
+			continue;
+		}
+
+		const params = resolvePendingAskParams(ctx, toolCall);
+		if (params) {
+			return { params, toolCallId: toolCall.id };
+		}
+	}
+	return;
+}
+
+function collectResolvedToolCallIds(
+	branch: readonly SessionEntry[]
+): Set<string> {
+	const resolved = new Set<string>();
+	for (const entry of branch) {
+		const dismissedToolCallId = getDismissedToolCallId(entry);
+		if (dismissedToolCallId) {
+			resolved.add(dismissedToolCallId);
+			continue;
+		}
+		if (entry.type === "message" && entry.message.role === "toolResult") {
+			resolved.add(entry.message.toolCallId);
+		}
+	}
+	return resolved;
+}
+
+function findUnresolvedAskToolCall(
+	entry: SessionEntry,
+	resolvedToolCallIds: ReadonlySet<string>
+): ToolCall | undefined {
+	if (
+		entry.type !== "message" ||
+		entry.message.role !== "assistant" ||
+		entry.message.stopReason !== "toolUse"
+	) {
+		return;
+	}
+
+	for (
+		let partIndex = entry.message.content.length - 1;
+		partIndex >= 0;
+		partIndex--
+	) {
+		const part = entry.message.content[partIndex];
+		if (
+			part.type === "toolCall" &&
+			part.name === ASK_TOOL_NAME &&
+			!resolvedToolCallIds.has(part.id)
+		) {
+			return part;
+		}
+	}
+	return;
+}
+
+function resolvePendingAskParams(
+	ctx: Pick<ExtensionContext, "sessionManager">,
+	toolCall: ToolCall
+): AskParams | undefined {
+	const persistedPayload = findPayloadForSourceEntry(ctx, toolCall.id, "tool");
+	if (persistedPayload) {
+		return persistedPayload.params;
+	}
+
+	const argumentsFallback = toolCall.arguments;
+	if (
+		Value.Check(AskParamsSchema, argumentsFallback) &&
+		validateParams(argumentsFallback).ok
+	) {
+		return argumentsFallback;
+	}
+	return;
+}
+
+function getDismissedToolCallId(entry: SessionEntry): string | undefined {
+	if (
+		entry.type !== "custom" ||
+		entry.customType !== ASK_PENDING_DISMISSED_ENTRY_TYPE ||
+		!entry.data ||
+		typeof entry.data !== "object"
+	) {
+		return;
+	}
+
+	const toolCallId = (entry.data as { toolCallId?: unknown }).toolCallId;
+	return typeof toolCallId === "string" ? toolCallId : undefined;
+}

package/src/remote-ask.ts

@@ -7,12 +7,17 @@ import type {
 	AskStateAnswer,
 } from "./types.ts";
 
-export const PI_ASK_STARTED_EVENT = "@eko24ive/pi-ask:started";
-export const PI_ASK_COMPLETED_EVENT = "@eko24ive/pi-ask:completed";
-export const PI_ASK_SUBMIT_EVENT = "@eko24ive/pi-ask:submit";
-export const PI_ASK_SUBMIT_RESULT_EVENT = "@eko24ive/pi-ask:submit-result";
-
-export type RemoteAskSource = "tool" | "answer" | "answer:again" | "ask:replay";
+export const PI_ASK_STARTED_EVENT = "@geoqiao/pi-ask:started";
+export const PI_ASK_COMPLETED_EVENT = "@geoqiao/pi-ask:completed";
+export const PI_ASK_SUBMIT_EVENT = "@geoqiao/pi-ask:submit";
+export const PI_ASK_SUBMIT_RESULT_EVENT = "@geoqiao/pi-ask:submit-result";
+
+export type RemoteAskSource =
+	| "tool"
+	| "answer"
+	| "answer:again"
+	| "ask:replay"
+	| "ask:resume";
 
 export interface RemoteAskAnswer {
 	customText?: string;

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
 		);
 	}