@geoqiao/pi-ask 1.1.0

package/skills/ask-user/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ask-user
+description: "Use ask_user as a decision, research, and requirements gate before ambiguous or high-stakes choices."
+metadata:
+  short-description: Decision, research, and requirements gate
+---
+
+# Ask User decision/research gate
+
+Use this skill to force explicit user alignment before consequential decisions, preference-sensitive planning, research scoping, or requirements gathering.
+
+This skill is for decision control, research scoping, requirements gathering, and preference-sensitive planning, not general chat.
+
+## Trigger
+
+Classify the next step as one of:
+
+- `high_stakes`
+- `ambiguous`
+- `both`
+- `clear`
+
+Use `ask_user` when the next step is ambiguous, preference-sensitive, or high-stakes and the user has not already made the decision explicitly.
+
+Use `ask_user` for any domain where user input changes the plan, recommendation, research direction, output format, criteria, constraints, or next action.
+
+Also use `ask_user` when the user asks to gather requirements, interview them, ask questions, scope research, plan work, compare options, or answer a set of open product/design/architecture/research questions. Do not respond with a plain-text questionnaire unless the user explicitly asks for a checklist or written questionnaire.
+
+### Treat as `high_stakes` when the next step changes:
+
+- architecture, schema, API contract, deployment, or security posture
+- production-facing behavior in a costly-to-undo way
+- large refactors, migrations, or destructive edits
+- legal, financial, medical, career, hiring, vendor, purchasing, travel, or other costly-to-reverse decisions
+- public-facing claims, sensitive communications, or consequential recommendations
+
+### Treat as `ambiguous` when:
+
+- requirements, goals, constraints, evaluation criteria, or success criteria are missing/conflicting
+- multiple valid options exist and the trade-off is preference-sensitive
+- research scope, audience, budget, timeline, risk tolerance, or output format is unclear
+- you would otherwise make a material assumption
+
+## Handshake (required)
+
+1. Gather evidence first from code/docs/tools.
+2. Summarize neutral context (current state, constraints, trade-offs, recommendation).
+3. Ask one focused `ask_user` decision question, or bundle 2-5 closely related questions when the user is explicitly in requirement-gathering/interview mode.
+4. Restate the user decision and proceed explicitly with it.
+5. Re-open only for materially new ambiguity.
+
+## Question spew prevention
+
+Before sending any assistant response that contains 2+ substantive questions for the user, stop and decide whether those questions should be interactive.
+
+Use `ask_user` instead of prose when:
+
+- the questions are meant to collect requirements, goals, constraints, preferences, scope, priorities, criteria, or missing context
+- answers will materially change the next artifact, recommendation, research direction, plan, implementation, architecture, schema, UX, stack choice, or decision criteria
+- the user previously corrected you with phrases like "ask those questions", "ask interactively", or "use ask_user"
+
+Plain-text questions are acceptable only when:
+
+- the user asked for a written checklist/list of open questions
+- the questions are rhetorical or purely explanatory
+- there is exactly one small factual clarification and an interactive flow would be heavier than needed
+
+If there are too many questions, group them into the smallest coherent `ask_user` batches and ask the highest-impact batch first.
+
+## Question budget and escalation
+
+- Max 1 `ask_user` call per decision boundary in normal cases.
+- Max 2 calls for the same boundary if first answer is unclear/cancelled.
+- Never re-ask the same trade-off without new evidence.
+
+Attempt 2 (only if needed) must be narrower and include:
+
+- `Proceed with recommended option`
+- `Choose another option`
+- `Stop for now`
+
+After attempt 2:
+
+- for `high_stakes` or `both`: stop as blocked until explicit decision
+- for `ambiguous` only: if user delegates ("your call"), proceed with the most reversible default and state assumptions
+
+## ask_user payload quality
+
+- Ask one concrete decision at a time.
+- Provide clear, distinct options. Do not add filler options.
+- Choose question type from semantics: `single` means one answer is expected, `multi` means multiple answers could reasonably be selected, and `preview` means options need preview-pane detail with non-empty preview text.
+- Avoid defaulting mechanically; infer from whether options are mutually exclusive, can coexist, or need preview-pane detail.
+- Keep option labels short and outcome-oriented.
+- Include trade-off descriptions when non-obvious.
+- For research/planning, ask about goals, constraints, evaluation criteria, audience, budget, timeline, risk tolerance, and desired output only when they materially affect the result.
+- Prefer non-`preview` questions when a free-form answer may be useful, since those include an internal `Type your own` option.
+
+## Guardrails
+
+- Do not ask before reading available context.
+- Do not use for trivial formatting/style micro-decisions.
+- Do not continue implementation after unclear high-stakes answers.
+
+## Conflict rule
+
+If this skill conflicts with implementation behavior or tests, the project contract wins:
+
+1. `docs/contract.md`
+2. `tests/*.test.ts`
+3. this skill

package/src/answer-commands.ts

@@ -0,0 +1,361 @@
+import {
+	BorderedLoader,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	extractAskParams,
+	selectExtractionModel,
+} from "./answer-extraction.ts";
+import {
+	type AskPayloadSource,
+	appendAskPayload,
+	findLatestPayloadInCurrentBranch,
+} from "./ask-payload-store.ts";
+import {
+	invalidPayloadResponse,
+	successfulResponse,
+	validateParams,
+} from "./ask-tool-helpers.ts";
+import { getAskConfigStore } from "./config/store.ts";
+import type { RemoteAskRuntime, RemoteAskSource } from "./remote-ask.ts";
+import type { AskParams, AskResult } from "./types.ts";
+import { runAskFlow } from "./ui/controller.ts";
+
+interface AssistantTextSource {
+	entryId: string;
+	text: string;
+}
+
+type ExtractionSelection = Exclude<
+	Awaited<ReturnType<typeof selectExtractionModel>>,
+	{ error: string }
+>;
+
+type ExtractionUiResult =
+	| { cancelled: true }
+	| { error: string }
+	| { params: AskParams };
+
+export function registerAnswerCommands(
+	pi: ExtensionAPI,
+	remoteAsk?: RemoteAskRuntime
+): void {
+	pi.registerCommand("answer", {
+		description:
+			"Extract questions from the latest assistant message into an ask form",
+		handler: async (_args, ctx) => runAnswerCommand(pi, ctx, remoteAsk),
+	});
+
+	pi.registerCommand("answer:again", {
+		description: "Reopen the previous /answer form on this branch",
+		handler: async (_args, ctx) =>
+			runReplayCommand(pi, ctx, {
+				missingMessage:
+					"No previous /answer form found on this branch; use /answer first.",
+				noticePrefix: "Reopening previous /answer form on this branch",
+				remoteSource: "answer:again",
+				source: "answer-extraction",
+				remoteAsk,
+			}),
+	});
+
+	pi.registerCommand("ask:replay", {
+		description: "Replay the previous ask_user form on this branch",
+		handler: async (_args, ctx) =>
+			runReplayCommand(pi, ctx, {
+				missingMessage: "No previous ask_user form found on this branch.",
+				noticePrefix: "Replaying previous ask_user form on this branch",
+				remoteSource: "ask:replay",
+				source: "tool",
+				remoteAsk,
+			}),
+	});
+}
+
+async function runAnswerCommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	remoteAsk?: RemoteAskRuntime
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("/answer requires interactive TUI mode.", "error");
+		return;
+	}
+
+	const assistant = findLatestAssistantText(ctx);
+	if ("error" in assistant) {
+		ctx.ui.notify(assistant.error, "error");
+		return;
+	}
+
+	const config = await getAskConfigStore().getConfig();
+	const selected = await selectExtractionModel(
+		ctx,
+		config.answer.extractionModels
+	);
+	if ("error" in selected) {
+		ctx.ui.notify(selected.error, "error");
+		return;
+	}
+	if (selected.usedFallback) {
+		ctx.ui.notify(
+			`Configured extraction models unavailable; using current chat model ${selected.model.provider}/${selected.model.id}.`,
+			"info"
+		);
+	}
+
+	const params = await extractAndValidateAnswerParams(
+		ctx,
+		assistant,
+		selected,
+		config
+	);
+	if (!params) {
+		return;
+	}
+
+	appendAskPayload(pi, {
+		params,
+		source: "answer-extraction",
+		sourceEntryId: assistant.entryId,
+	});
+
+	await runAskAndSendSubmittedResult(pi, ctx, params, {
+		allowFreeform: true,
+		remoteAsk,
+		remoteSource: "answer",
+	});
+}
+
+async function extractAndValidateAnswerParams(
+	ctx: ExtensionCommandContext,
+	assistant: AssistantTextSource,
+	selected: ExtractionSelection,
+	config: Awaited<ReturnType<ReturnType<typeof getAskConfigStore>["getConfig"]>>
+): Promise<AskParams | undefined> {
+	const extraction = await withHiddenWorkingRow(ctx, () =>
+		runExtractionUi(ctx, assistant, selected, config)
+	);
+	if ("cancelled" in extraction) {
+		ctx.ui.notify("Question extraction cancelled.", "info");
+		return;
+	}
+	if ("error" in extraction) {
+		ctx.ui.notify(formatExtractionError(extraction.error), "error");
+		return;
+	}
+	if (!isAskParamsCandidate(extraction.params)) {
+		ctx.ui.notify("Question extraction returned an invalid ask form.", "error");
+		return;
+	}
+	if (extraction.params.questions.length === 0) {
+		ctx.ui.notify(
+			"No questions found in the latest assistant message.",
+			"info"
+		);
+		return;
+	}
+	const validation = validateParams(extraction.params, { allowFreeform: true });
+	if (!validation.ok) {
+		const response = invalidPayloadResponse(
+			extraction.params,
+			validation.issues
+		);
+		ctx.ui.notify(response.content[0].text, "error");
+		return;
+	}
+	return extraction.params;
+}
+
+function runExtractionUi(
+	ctx: ExtensionCommandContext,
+	assistant: AssistantTextSource,
+	selected: ExtractionSelection,
+	config: Awaited<ReturnType<ReturnType<typeof getAskConfigStore>["getConfig"]>>
+): Promise<ExtractionUiResult> {
+	return ctx.ui.custom<ExtractionUiResult>((tui, theme, _keybindings, done) => {
+		let completed = false;
+		const doneOnce = (result: ExtractionUiResult) => {
+			if (completed) {
+				return;
+			}
+			completed = true;
+			done(result);
+		};
+		const loader = new BorderedLoader(
+			tui,
+			theme,
+			`Extracting questions using ${selected.model.provider}/${selected.model.id}...`
+		);
+		loader.onAbort = () => doneOnce({ cancelled: true });
+		extractAskParams({
+			assistantText: assistant.text,
+			auth: selected.auth,
+			model: selected.model,
+			onRetry: (attempt, maxRetries) => {
+				ctx.ui.notify(
+					`Retrying extraction JSON repair (${attempt}/${maxRetries})...`,
+					"info"
+				);
+			},
+			retries: config.answer.extractionRetries,
+			signal: loader.signal,
+			timeoutMs: config.answer.extractionTimeoutMs,
+		})
+			.then((params) => doneOnce({ params }))
+			.catch((error) => doneOnce({ error: formatErrorMessage(error) }));
+		return loader;
+	});
+}
+
+function formatErrorMessage(error: unknown): string {
+	if (error instanceof Error) {
+		return error.name ? `${error.name}: ${error.message}` : error.message;
+	}
+	return String(error);
+}
+
+function isAskParamsCandidate(value: unknown): value is AskParams {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		Array.isArray((value as { questions?: unknown }).questions)
+	);
+}
+
+function formatExtractionError(error: string): string {
+	if (error.includes("valid JSON")) {
+		return error;
+	}
+	if (error.includes("cancelled")) {
+		return "Question extraction cancelled.";
+	}
+	if (
+		error.includes("aborted") ||
+		error.includes("AbortError") ||
+		error.includes("timed out")
+	) {
+		return "Question extraction timed out. Try again or configure a faster extraction model.";
+	}
+	return error;
+}
+
+async function runReplayCommand(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	options: {
+		missingMessage: string;
+		noticePrefix: string;
+		remoteAsk?: RemoteAskRuntime;
+		remoteSource: RemoteAskSource;
+		source: AskPayloadSource;
+	}
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("Ask replay requires interactive TUI mode.", "error");
+		return;
+	}
+	const lookup = findLatestPayloadInCurrentBranch(ctx, options.source);
+	if (!lookup.data) {
+		ctx.ui.notify(
+			lookup.invalidMatchFound
+				? "Previous form exists on this branch but is no longer compatible."
+				: options.missingMessage,
+			"info"
+		);
+		return;
+	}
+	ctx.ui.notify(
+		`${options.noticePrefix}: ${lookup.data.params.questions.length} question(s).`,
+		"info"
+	);
+	await runAskAndSendSubmittedResult(pi, ctx, lookup.data.params, {
+		allowFreeform: options.source === "answer-extraction",
+		remoteAsk: options.remoteAsk,
+		remoteSource: options.remoteSource,
+	});
+}
+
+async function runAskAndSendSubmittedResult(
+	pi: Pick<ExtensionAPI, "sendUserMessage">,
+	ctx: ExtensionContext,
+	params: AskParams,
+	options: {
+		allowFreeform: boolean;
+		remoteAsk?: RemoteAskRuntime;
+		remoteSource: RemoteAskSource;
+	}
+): Promise<void> {
+	const result = await withHiddenWorkingRow(ctx, () =>
+		runAskFlow(ctx, params, {
+			allowFreeform: options.allowFreeform,
+			remote: options.remoteAsk
+				? { runtime: options.remoteAsk, source: options.remoteSource }
+				: undefined,
+		})
+	);
+	if (result.cancelled) {
+		ctx.ui.notify("Ask form cancelled.", "info");
+		return;
+	}
+	sendAskResult(pi, result, ctx);
+}
+
+async function withHiddenWorkingRow<T>(
+	ctx: ExtensionContext,
+	run: () => Promise<T>
+): Promise<T> {
+	ctx.ui.setWorkingVisible(false);
+	try {
+		return await run();
+	} finally {
+		ctx.ui.setWorkingVisible(true);
+	}
+}
+
+function sendAskResult(
+	pi: Pick<ExtensionAPI, "sendUserMessage">,
+	result: AskResult,
+	ctx: Pick<ExtensionContext, "isIdle">
+): void {
+	const response = successfulResponse(result);
+	const text = response.content[0];
+	pi.sendUserMessage(
+		text.text,
+		ctx.isIdle() ? undefined : { deliverAs: "followUp" }
+	);
+}
+
+function findLatestAssistantText(
+	ctx: Pick<ExtensionContext, "sessionManager">
+): AssistantTextSource | { error: string } {
+	const branch = ctx.sessionManager.getBranch();
+	for (let index = branch.length - 1; index >= 0; index--) {
+		const entry = branch[index];
+		if (entry.type !== "message") {
+			continue;
+		}
+		const message = entry.message;
+		if (!("role" in message) || message.role !== "assistant") {
+			continue;
+		}
+		if (message.stopReason !== "stop") {
+			return {
+				error: `Latest assistant message is incomplete (${message.stopReason}); wait for it to finish, then run /answer again.`,
+			};
+		}
+		const text = message.content
+			.filter(
+				(part): part is { text: string; type: "text" } => part.type === "text"
+			)
+			.map((part) => part.text)
+			.join("\n")
+			.trim();
+		if (text) {
+			return { entryId: entry.id, text };
+		}
+	}
+	return { error: "No assistant message found to extract questions from." };
+}