@geoqiao/pi-ask 1.1.0

package/src/answer-extraction.ts

@@ -0,0 +1,354 @@
+import {
+	type Api,
+	complete,
+	type Model,
+	type UserMessage,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AskConfig } from "./config/schema.ts";
+import type { AskParams } from "./types.ts";
+
+export const ANSWER_EXTRACTION_SYSTEM_PROMPT = `You extract user-input questions from an assistant message and return ONLY raw JSON.
+
+Return JSON matching this TypeScript shape:
+{
+  "title"?: string,
+  "questions": [
+    {
+      "id": string,
+      "label"?: string,
+      "prompt": string,
+      "type"?: "single" | "multi" | "preview",
+      "required"?: boolean,
+      "options": [
+        {
+          "value": string,
+          "label": string,
+          "description"?: string,
+          "preview"?: string,
+          "freeform"?: boolean
+        }
+      ]
+    }
+  ]
+}
+
+Rules:
+- Output raw JSON only. No Markdown. No prose. No code fences.
+- Extract questions that require user input.
+- Ignore generic conversational or clarification prompts such as "How can I help?", "Could you clarify?", or "Let me know what you need" unless they include concrete choices.
+- Extract a question when it has explicit choices or when the user should type their own answer.
+- Preserve question order.
+- Generate stable snake_case ids.
+- Choose question type from the question semantics.
+- Use type "single" when one answer is expected.
+- Use type "multi" when multiple answers could reasonably be selected.
+- Use type "preview" when options need preview-pane detail and every option has non-empty preview text.
+- Avoid defaulting mechanically; infer from whether the options are mutually exclusive, can coexist, or need preview-pane detail.
+- Each extracted question must have at least one option.
+- Options rule:
+  - Extract options only from choices explicitly offered by the assistant.
+  - If the assistant gives concrete choices, use those choices as normal options.
+  - If the assistant gives examples only, do not treat examples as choices unless they are presented as selectable answers.
+  - If no concrete choices are given and the user should type their own answer, create exactly one freeform option: {"value":"freeform","label":"Type answer","freeform":true}.
+  - Never invent options.
+  - Never mix a freeform option with normal options.
+- Provide clear, distinct options. Do not add filler options.
+- Do not create an option that merely restates the question.
+- Include descriptions only when helpful.
+- Return {"questions":[]} if no questions are found.`;
+
+interface SelectedExtractionModel {
+	auth: { apiKey?: string; headers?: Record<string, string> };
+	model: Model<Api>;
+	usedFallback: boolean;
+}
+
+export async function selectExtractionModel(
+	ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+	preferences: AskConfig["answer"]["extractionModels"]
+): Promise<SelectedExtractionModel | { error: string }> {
+	for (const preference of preferences) {
+		const model = ctx.modelRegistry.find(preference.provider, preference.id);
+		if (!model) {
+			continue;
+		}
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (auth.ok) {
+			return { model, auth, usedFallback: false };
+		}
+	}
+
+	if (!ctx.model) {
+		return {
+			error:
+				"No available extraction model. Configure answer.extractionModels or select a chat model.",
+		};
+	}
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+	if (!auth.ok) {
+		return {
+			error: `No auth for fallback chat model: ${ctx.model.provider}/${ctx.model.id}.`,
+		};
+	}
+
+	return { model: ctx.model, auth, usedFallback: true };
+}
+
+export async function extractAskParams(options: {
+	assistantText: string;
+	model: Model<Api>;
+	auth: { apiKey?: string; headers?: Record<string, string> };
+	retries: number;
+	signal?: AbortSignal;
+	timeoutMs: number;
+	onRetry?: (attempt: number, maxRetries: number) => void;
+}): Promise<AskParams> {
+	let lastCandidate: AskParams | undefined;
+	let lastResponse = "";
+	let lastError = "";
+	for (let attempt = 0; attempt <= options.retries; attempt++) {
+		if (attempt > 0) {
+			options.onRetry?.(attempt, options.retries);
+		}
+		const responseText = await runExtractionAttempt({
+			...options,
+			attempt,
+			lastError,
+			lastResponse,
+		});
+		lastResponse = responseText;
+		const parsed = parseExtractionCandidate(responseText);
+		if (!parsed.ok) {
+			lastError = parsed.error;
+			continue;
+		}
+		lastCandidate = parsed.params;
+		if (parsed.issues.length === 0) {
+			return parsed.params;
+		}
+		lastError = parsed.issues.join("\n");
+	}
+	if (lastCandidate) {
+		return repairExtractionParams(lastCandidate);
+	}
+	throw new Error(
+		"Question extraction did not return valid JSON after retries."
+	);
+}
+
+async function runExtractionAttempt(options: {
+	assistantText: string;
+	attempt: number;
+	auth: { apiKey?: string; headers?: Record<string, string> };
+	lastError: string;
+	lastResponse: string;
+	model: Model<Api>;
+	signal?: AbortSignal;
+	timeoutMs: number;
+}): Promise<string> {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timeout = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, options.timeoutMs);
+	const abortFromParent = () => controller.abort();
+	options.signal?.addEventListener("abort", abortFromParent, { once: true });
+	try {
+		const userMessage: UserMessage = {
+			role: "user",
+			content: [
+				{
+					type: "text",
+					text:
+						options.attempt === 0
+							? options.assistantText
+							: formatRetryPrompt(options),
+				},
+			],
+			timestamp: Date.now(),
+		};
+		const response = await complete(
+			options.model,
+			{
+				systemPrompt: ANSWER_EXTRACTION_SYSTEM_PROMPT,
+				messages: [userMessage],
+			},
+			{
+				apiKey: options.auth.apiKey,
+				headers: options.auth.headers,
+				signal: controller.signal,
+			}
+		);
+		if (response.stopReason === "aborted") {
+			throw new Error(
+				timedOut
+					? "Question extraction timed out. Try again or configure a faster extraction model."
+					: "Question extraction cancelled."
+			);
+		}
+		return response.content
+			.filter(
+				(part): part is { text: string; type: "text" } => part.type === "text"
+			)
+			.map((part) => part.text)
+			.join("\n");
+	} finally {
+		clearTimeout(timeout);
+		options.signal?.removeEventListener("abort", abortFromParent);
+	}
+}
+
+const MAX_EXTRACTED_OPTIONS_PER_QUESTION = 4;
+
+function parseExtractionCandidate(
+	responseText: string
+):
+	| { ok: true; params: AskParams; issues: string[] }
+	| { ok: false; error: string } {
+	try {
+		const parsed = JSON.parse(responseText.trim()) as unknown;
+		if (!isAskParamsLike(parsed)) {
+			return { ok: false, error: "root.questions must be an array" };
+		}
+		return {
+			ok: true,
+			params: parsed,
+			issues: collectExtractionBusinessIssues(parsed),
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+function isAskParamsLike(value: unknown): value is AskParams {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		Array.isArray((value as { questions?: unknown }).questions)
+	);
+}
+
+export function collectExtractionBusinessIssues(params: AskParams): string[] {
+	const issues: string[] = [];
+	params.questions.forEach((question, questionIndex) => {
+		if (isGenericConversationalPrompt(question.prompt)) {
+			issues.push(
+				`questions[${questionIndex}].prompt is generic conversational text; omit this question unless it includes concrete choices`
+			);
+		}
+		if (question.options.length > MAX_EXTRACTED_OPTIONS_PER_QUESTION) {
+			issues.push(
+				`questions[${questionIndex}].options has ${question.options.length} items; max is ${MAX_EXTRACTED_OPTIONS_PER_QUESTION}`
+			);
+		}
+		if (
+			question.options.length === 1 &&
+			optionRestatesQuestion(question.options[0]?.label, question.prompt)
+		) {
+			issues.push(
+				`questions[${questionIndex}].options[0] merely restates the question; omit this question or provide meaningful distinct options`
+			);
+		}
+	});
+	return issues;
+}
+
+export function repairExtractionParams(params: AskParams): AskParams {
+	return {
+		...params,
+		questions: params.questions
+			.filter((question) => !isGenericConversationalPrompt(question.prompt))
+			.filter(
+				(question) =>
+					question.options.length !== 1 ||
+					!optionRestatesQuestion(question.options[0]?.label, question.prompt)
+			)
+			.map((question) => ({
+				...question,
+				options: capOptionsPreservingOther(question.options),
+			})),
+	};
+}
+
+function capOptionsPreservingOther<T extends { label: string; value: string }>(
+	options: T[]
+): T[] {
+	if (options.length <= MAX_EXTRACTED_OPTIONS_PER_QUESTION) {
+		return options;
+	}
+	const other = options.find((option) => isOtherOption(option));
+	if (!other) {
+		return options.slice(0, MAX_EXTRACTED_OPTIONS_PER_QUESTION);
+	}
+	const head = options
+		.filter((option) => option !== other)
+		.slice(0, MAX_EXTRACTED_OPTIONS_PER_QUESTION - 1);
+	return [...head, other];
+}
+
+function isOtherOption(option: { label: string; value: string }): boolean {
+	const label = normalizeText(option.label);
+	const value = normalizeText(option.value);
+	return (
+		label === "other" || label.includes("something else") || value === "other"
+	);
+}
+
+function optionRestatesQuestion(
+	label: string | undefined,
+	prompt: string
+): boolean {
+	if (!label) {
+		return false;
+	}
+	const normalizedLabel = normalizeText(label);
+	const normalizedPrompt = normalizeText(prompt);
+	return (
+		normalizedLabel.length > 8 &&
+		(normalizedPrompt.includes(normalizedLabel) ||
+			normalizedLabel.includes(normalizedPrompt))
+	);
+}
+
+function isGenericConversationalPrompt(prompt: string): boolean {
+	const normalized = normalizeText(prompt);
+	return [
+		"how can i help",
+		"could you clarify",
+		"let me know what you need",
+		"what else is on your mind",
+		"anything on your mind i can help with",
+	].some((phrase) => normalized.includes(phrase));
+}
+
+function normalizeText(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim();
+}
+
+function formatRetryPrompt(options: {
+	assistantText: string;
+	lastError: string;
+	lastResponse: string;
+}): string {
+	return `Your previous response was not valid raw JSON.
+
+JSON.parse error:
+${options.lastError}
+
+Previous response:
+${options.lastResponse}
+
+Original assistant message:
+${options.assistantText}
+
+Return ONLY valid raw JSON matching the schema and fix the reported issues. No Markdown. No prose.`;
+}

package/src/ask-payload-store.ts

@@ -0,0 +1,86 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { validateParams } from "./ask-tool-helpers.ts";
+import type { AskParams } from "./types.ts";
+
+export const ASK_PAYLOAD_ENTRY_TYPE = "ask:payload";
+export const ASK_PAYLOAD_ENTRY_VERSION = 1;
+
+export type AskPayloadSource = "answer-extraction" | "tool";
+
+export interface AskPayloadEntryData {
+	params: AskParams;
+	source: AskPayloadSource;
+	sourceEntryId?: string;
+	timestamp: number;
+	version: typeof ASK_PAYLOAD_ENTRY_VERSION;
+}
+
+export function appendAskPayload(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	data: Omit<AskPayloadEntryData, "timestamp" | "version">
+): void {
+	pi.appendEntry(ASK_PAYLOAD_ENTRY_TYPE, {
+		version: ASK_PAYLOAD_ENTRY_VERSION,
+		timestamp: Date.now(),
+		...data,
+	});
+}
+
+export function findLatestPayloadInCurrentBranch(
+	ctx: Pick<ExtensionContext, "sessionManager">,
+	source: AskPayloadSource
+): { data?: AskPayloadEntryData; invalidMatchFound: boolean } {
+	let invalidMatchFound = false;
+	for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
+		if (!isAskPayloadEntry(entry)) {
+			continue;
+		}
+		const data = entry.data;
+		if (data?.source !== source) {
+			continue;
+		}
+		if (isValidAskPayloadData(data)) {
+			return { data, invalidMatchFound };
+		}
+		invalidMatchFound = true;
+	}
+	return { invalidMatchFound };
+}
+
+function isAskPayloadEntry(entry: unknown): entry is {
+	customType: string;
+	data?: Partial<AskPayloadEntryData>;
+	type: "custom";
+} {
+	return (
+		!!entry &&
+		typeof entry === "object" &&
+		(entry as { type?: unknown }).type === "custom" &&
+		(entry as { customType?: unknown }).customType === ASK_PAYLOAD_ENTRY_TYPE
+	);
+}
+
+function isValidAskPayloadData(data: unknown): data is AskPayloadEntryData {
+	if (!(data && typeof data === "object")) {
+		return false;
+	}
+	const payload = data as Partial<AskPayloadEntryData>;
+	if (payload.version !== ASK_PAYLOAD_ENTRY_VERSION) {
+		return false;
+	}
+	if (payload.source !== "tool" && payload.source !== "answer-extraction") {
+		return false;
+	}
+	if (
+		!payload.params ||
+		validateParams(payload.params, {
+			allowFreeform: payload.source === "answer-extraction",
+		}).ok === false
+	) {
+		return false;
+	}
+	return true;
+}

package/src/ask-settings-command.ts

@@ -0,0 +1,14 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { showAskSettings } from "./ui/show-settings.ts";
+
+export function registerAskSettingsCommand(pi: ExtensionAPI) {
+	pi.registerCommand("ask-settings", {
+		description: "Open ask settings",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			await showAskSettings(ctx);
+		},
+	});
+}

package/src/ask-tool-helpers.ts

@@ -0,0 +1,172 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { UI_DIMENSIONS } from "./constants/ui.ts";
+import { renderResultText } from "./result.ts";
+import { createInitialState } from "./state/create.ts";
+import { collectValidationIssues } from "./state/normalize.ts";
+import { summarizeResult, toAskResult } from "./state/result.ts";
+import type {
+	AskParams,
+	AskQuestionInput,
+	AskResult,
+	AskValidationIssue,
+} 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. Supports single-select, multi-select, and preview-pane questions. Always include a machine-readable `value` 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`, 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.",
+	"When prior `ask_user` answers narrow the branch, bundle the next 2-3 related unresolved decisions into one follow-up `ask_user` call when possible.",
+	"Use one-at-a-time `ask_user` follow-up calls only when the next question materially depends on the previous answer.",
+] as const;
+
+interface ValidateParamsOptions {
+	allowFreeform?: boolean;
+	presentSingleAsMulti?: boolean;
+}
+
+export function validateParams(
+	params: AskParams,
+	options: ValidateParamsOptions = {}
+):
+	| { ok: true; state: ReturnType<typeof createInitialState> }
+	| { ok: false; issues: AskValidationIssue[] } {
+	const issues = collectValidationIssues(params, options);
+	if (issues.length > 0) {
+		return { ok: false, issues };
+	}
+
+	return {
+		ok: true,
+		state: createInitialState(params, options),
+	};
+}
+
+export function invalidPayloadResponse(
+	params: AskParams,
+	issues: AskValidationIssue[]
+) {
+	return {
+		content: [{ type: "text" as const, text: formatValidationError(issues) }],
+		details: errorResultDetails(params, issues),
+	};
+}
+
+export function nonInteractiveResponse(
+	state: ReturnType<typeof createInitialState>
+) {
+	return {
+		content: [
+			{ type: "text" as const, text: formatNonInteractiveMessage(state) },
+		],
+		details: {
+			...toAskResult(state),
+			cancelled: true,
+		},
+	};
+}
+
+export function successfulResponse(result: AskResult) {
+	return {
+		content: [{ type: "text" as const, text: summarizeResult(result) }],
+		details: result,
+	};
+}
+
+type ToolTheme = ExtensionContext["ui"]["theme"];
+
+export function renderAskToolCall(args: unknown, theme: ToolTheme) {
+	const params = args as AskParams;
+	const labels = Array.isArray(params.questions)
+		? params.questions
+				.map(
+					(question: AskQuestionInput, index) =>
+						question.label || `Q${index + 1}`
+				)
+				.join(", ")
+		: "";
+	let text = theme.fg("toolTitle", theme.bold("ask_user "));
+	text += theme.fg("muted", `${params.questions?.length ?? 0} question(s)`);
+	if (labels) {
+		text += theme.fg(
+			"dim",
+			` (${truncateToWidth(labels, UI_DIMENSIONS.callLabelTruncateWidth)})`
+		);
+	}
+	return new Text(text, 0, 0);
+}
+
+export function renderAskToolResult(
+	result: {
+		content: Array<{ type?: string; text?: string }>;
+		details?: AskResult;
+	},
+	_options: unknown,
+	theme: ToolTheme
+) {
+	const details = result.details;
+	if (!details) {
+		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);
+}
+
+function errorResultDetails(
+	params: AskParams,
+	issues: AskValidationIssue[]
+): AskResult {
+	return {
+		title: params.title,
+		cancelled: true,
+		mode: "submit",
+		questions: [],
+		answers: {},
+		error: {
+			kind: "invalid_input",
+			issues,
+		},
+	};
+}
+
+function formatValidationError(issues: AskValidationIssue[]): string {
+	return [
+		"Invalid ask_user payload:",
+		...issues.map((issue) => `- ${issue.path}: ${issue.message}`),
+	].join("\n");
+}
+
+function formatNonInteractiveMessage(
+	state: ReturnType<typeof createInitialState>
+): string {
+	const lines = [
+		"Needs user input: ask_user requires interactive TUI mode.",
+		"Run same tool call in interactive TUI mode, or ask user these questions manually:",
+	];
+
+	for (const [index, question] of state.questions.entries()) {
+		lines.push(`${index + 1}. ${question.label}: ${question.prompt}`);
+		for (const option of question.options) {
+			lines.push(`   - ${option.label} [${option.value}]`);
+		}
+		lines.push("   - Type your own [custom]");
+	}
+
+	lines.push(
+		"details.questions contains normalized pending questions. details.answers stays empty until user responds."
+	);
+	return lines.join("\n");
+}

package/src/ask-tool.ts

@@ -0,0 +1,84 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { appendAskPayload } from "./ask-payload-store.ts";
+import {
+	ASK_TOOL_DESCRIPTION,
+	ASK_TOOL_PROMPT_GUIDELINES,
+	invalidPayloadResponse,
+	nonInteractiveResponse,
+	renderAskToolCall,
+	renderAskToolResult,
+	successfulResponse,
+	validateParams,
+} from "./ask-tool-helpers.ts";
+import { getAskConfigStore } from "./config/store.ts";
+import type { RemoteAskRuntime } from "./remote-ask.ts";
+import { AskParamsSchema } from "./schema.ts";
+import type { AskParams } from "./types.ts";
+import { runAskFlow } from "./ui/controller.ts";
+
+export function registerAskTool(
+	pi: ExtensionAPI,
+	remoteAsk?: RemoteAskRuntime
+) {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User",
+		description: ASK_TOOL_DESCRIPTION,
+		promptSnippet:
+			"Clarify ambiguous or preference-sensitive decisions with a short interactive interview before proceeding",
+		promptGuidelines: [...ASK_TOOL_PROMPT_GUIDELINES],
+		parameters: AskParamsSchema,
+		execute: (toolCallId, params, signal, onUpdate, ctx) =>
+			executeAskTool(
+				pi,
+				toolCallId,
+				params as AskParams,
+				signal,
+				onUpdate,
+				ctx,
+				remoteAsk
+			),
+		renderCall: renderAskToolCall,
+		renderResult: renderAskToolResult,
+	});
+}
+
+async function executeAskTool(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	toolCallId: string,
+	params: AskParams,
+	_signal: AbortSignal | undefined,
+	_onUpdate: unknown,
+	ctx: ExtensionContext,
+	remoteAsk?: RemoteAskRuntime
+) {
+	const config = await getAskConfigStore().getConfig();
+	const validation = validateParams(params, {
+		presentSingleAsMulti: config.behaviour.presentSingleAsMulti,
+	});
+	if (!validation.ok) {
+		return invalidPayloadResponse(params, validation.issues);
+	}
+	appendAskPayload(pi, {
+		params,
+		source: "tool",
+		sourceEntryId: toolCallId,
+	});
+	if (ctx.mode !== "tui") {
+		return nonInteractiveResponse(validation.state);
+	}
+	ctx.ui.setWorkingVisible(false);
+	try {
+		const result = await runAskFlow(ctx, params, {
+			remote: remoteAsk
+				? { runtime: remoteAsk, source: "tool", toolCallId }
+				: undefined,
+		});
+		return successfulResponse(result);
+	} finally {
+		ctx.ui.setWorkingVisible(true);
+	}
+}