ultimate-pi 0.19.1 → 0.22.0

package/.pi/lib/ask-user/validate-core.mjs

@@ -1,7 +1,12 @@
-/** Keep in sync with validate.ts — test entrypoint for node --test */
+/** Keep in sync with validate.ts + format.ts — test entrypoint for node --test */
+
+import { createRequire } from "node:module";
+import { MAX_QUESTIONNAIRE_QUESTIONS } from "./constants.mjs";
+
+const require = createRequire(import.meta.url);
 
 /**
- * @param {string | { title: string, description?: string }} raw
+ * @param {string | { title: string, description?: string, recommended?: boolean }} raw
  */
 export function normalizeOption(raw) {
 	if (typeof raw === "string") {
@@ -10,6 +15,26 @@ export function normalizeOption(raw) {
 	return {
 		title: raw.title.trim(),
 		description: raw.description?.trim() || undefined,
+		recommended: raw.recommended === true ? true : undefined,
+	};
+}
+
+function normalizeQuestion(raw) {
+	const title = raw.title?.trim();
+	if (!title) return "ask_user: each questions[] item requires title";
+
+	const options = (raw.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return `ask_user: question "${title}" needs at least 2 options or omit options for freeform`;
+	}
+
+	return {
+		title,
+		description: raw.description?.trim() || undefined,
+		options,
+		allowMultiple: raw.allowMultiple === true,
 	};
 }
 
@@ -20,6 +45,22 @@ export function validateAskParams(params) {
 		return "ask_user: question is required";
 	}
 
+	const rawQuestions = params.questions ?? [];
+	if (rawQuestions.length > MAX_QUESTIONNAIRE_QUESTIONS) {
+		return `ask_user: at most ${MAX_QUESTIONNAIRE_QUESTIONS} questions in questionnaire mode`;
+	}
+
+	if (rawQuestions.length > 0 && (params.options?.length ?? 0) > 0) {
+		return "ask_user: use either options or questions[], not both";
+	}
+
+	const questions = [];
+	for (const q of rawQuestions) {
+		const normalized = normalizeQuestion(q);
+		if (typeof normalized === "string") return normalized;
+		questions.push(normalized);
+	}
+
 	const options = (params.options ?? [])
 		.map(normalizeOption)
 		.filter((o) => o.title);
@@ -28,7 +69,9 @@ export function validateAskParams(params) {
 	}
 
 	const allowFreeform = params.allowFreeform !== false;
-	if (options.length === 0 && !allowFreeform) {
+	const mode = questions.length > 0 ? "questionnaire" : "flat";
+
+	if (mode === "flat" && options.length === 0 && !allowFreeform) {
 		return "ask_user: options required when allowFreeform is false";
 	}
 
@@ -42,9 +85,15 @@ export function validateAskParams(params) {
 	return {
 		question,
 		context: params.context?.trim() || undefined,
+		contextFormat:
+			params.contextFormat === "html" ? "html" : "markdown",
 		options,
+		questions,
+		mode,
 		allowMultiple: params.allowMultiple === true,
 		allowFreeform,
+		allowComment: params.allowComment === true,
+		allowSkip: params.allowSkip === true,
 		displayMode,
 		timeout:
 			typeof params.timeout === "number" && params.timeout > 0
@@ -53,14 +102,30 @@ export function validateAskParams(params) {
 	};
 }
 
-/** @param {import('./types.js').AskResponse | null} response @param {boolean} cancelled */
-export function formatResultText(response, cancelled) {
+/** @param {import('./types.js').AskResponse | null} response @param {boolean} cancelled @param {{ ui_degraded?: boolean }} [opts] */
+export function formatResultText(response, cancelled, opts) {
 	if (cancelled || !response) {
 		return "User cancelled (no answer)";
 	}
+	if (opts?.ui_degraded) {
+		return `Rich ask UI unavailable; using terminal prompt.\n\n${formatResponseBody(response)}`;
+	}
+	return formatResponseBody(response);
+}
+
+/** @param {import('./types.js').AskResponse} response */
+function formatResponseBody(response) {
 	if (response.kind === "freeform") {
 		return `User wrote: ${response.text}`;
 	}
+	if (response.kind === "questionnaire") {
+		const lines = response.questionnaireDetails.map((d) => {
+			let line = `- ${d.question}: ${d.answer}`;
+			if (d.comment) line += ` (comment: ${d.comment})`;
+			return line;
+		});
+		return `User answered questionnaire:\n${lines.join("\n")}`;
+	}
 	if (response.selections.length === 1) {
 		return `User selected: ${response.selections[0]}`;
 	}
@@ -68,12 +133,133 @@ export function formatResultText(response, cancelled) {
 }
 
 /** @param {import('./types.js').ValidatedAskParams} validated */
-export function toToolDetails(validated, response, cancelled) {
+export function toToolDetails(validated, response, cancelled, ui_backend = "headless", opts = {}) {
+	const options =
+		validated.mode === "questionnaire"
+			? validated.questions.map((q) => q.title)
+			: validated.options.map((o) => o.title);
 	return {
 		question: validated.question,
 		context: validated.context,
-		options: validated.options.map((o) => o.title),
+		contextFormat: validated.contextFormat,
+		options,
 		response,
 		cancelled,
+		ui_backend,
+		ui_degraded: opts.ui_degraded,
+	};
+}
+
+export { isPlanApprovalAskUser } from "./policy.mjs";
+
+/** @param {import('./types.js').ValidatedAskParams} validated */
+export function buildGlimpsePayload(validated, sessionName) {
+	const hasQuestions = validated.mode === "questionnaire";
+	const hasOptions = validated.options.length > 0;
+	let payloadType;
+	if (hasQuestions) payloadType = "questionnaire";
+	else if (!hasOptions) payloadType = "freeform";
+	else if (validated.allowMultiple) payloadType = "multi-select";
+	else payloadType = "single-select";
+
+	let question = validated.question;
+	let context = validated.context;
+	if (!context && validated.question.length > 120) {
+		const match = validated.question.match(/^(.+?[.?!])(\s+|$)/);
+		if (match && match[0].length < validated.question.length) {
+			question = match[1].trim();
+			context = validated.question.slice(match[0].length).trim();
+		}
+	}
+
+	return {
+		type: payloadType,
+		question,
+		context,
+		contextFormat: validated.contextFormat,
+		options: validated.options.map((o) => ({
+			title: o.title,
+			description: o.description,
+			recommended: o.recommended,
+		})),
+		questions: validated.questions.map((q) => ({
+			title: q.title,
+			description: q.description,
+			allowMultiple: q.allowMultiple,
+			options: q.options.map((o) => ({
+				title: o.title,
+				description: o.description,
+				recommended: o.recommended,
+			})),
+		})),
+		allowMultiple: validated.allowMultiple,
+		allowFreeform: validated.allowFreeform,
+		allowComment: validated.allowComment,
+		allowSkip: validated.allowSkip,
+		sessionName,
+	};
+}
+
+function isGlimpseAvailable() {
+	try {
+		require.resolve("@alexleekt/pi-ask-user-glimpse/package.json");
+		require.resolve("glimpseui");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** @param {import('./types.js').ValidatedAskParams} validated @param {boolean} hasUI */
+export function resolvePresenterChoice(validated, hasUI) {
+	if (validated.displayMode === "inline") return "tui";
+
+	const forced = process.env.HARNESS_ASK_USER_UI?.toLowerCase();
+	if (forced === "tui") return "tui";
+	if (forced === "glimpse") return "glimpse";
+	if (forced === "headless") return "headless";
+	if (hasUI && isGlimpseAvailable()) return "glimpse";
+	if (hasUI) return "tui";
+	return "headless";
+}
+
+/** @param {Record<string, unknown>} doc @param {import('./types.js').AskToolDetails} details */
+export function applyAskUserToTaskClarification(doc, details) {
+	const next = { ...doc };
+	const assumptions = Array.isArray(next.assumptions) ? [...next.assumptions] : [];
+	if (!details.response || details.cancelled) return next;
+
+	const applyPair = (question, answer) => {
+		const n = question.toLowerCase();
+		if (n.includes("done") || n.includes("success")) {
+			next.success_definition = answer;
+			return;
+		}
+		if (n.includes("risk")) {
+			const a = answer.toLowerCase();
+			if (/\blow\b/.test(a)) next.risk_level = "low";
+			else if (/\bhigh\b/.test(a)) next.risk_level = "high";
+			else if (/\bmed/.test(a) || /\bmedium\b/.test(a)) next.risk_level = "med";
+			return;
+		}
+		if (n.includes("scope") || n.includes("in scope")) {
+			const items = answer.split(/[,;\n]/).map((s) => s.trim()).filter(Boolean);
+			if (items.length) next.in_scope = items;
+			return;
+		}
+		assumptions.push(`${question}: ${answer}`);
 	};
+
+	const r = details.response;
+	if (r.kind === "questionnaire") {
+		for (const d of r.questionnaireDetails) applyPair(d.question, d.answer);
+	} else if (r.kind === "freeform") {
+		applyPair(details.question, r.text);
+	} else if (r.kind === "selection") {
+		applyPair(details.question, r.selections.join(", "));
+	}
+
+	if (assumptions.length) next.assumptions = assumptions;
+	if (Array.isArray(next.unresolved_questions)) next.unresolved_questions = [];
+	return next;
 }

package/.pi/lib/ask-user/validate.ts

@@ -1,15 +1,15 @@
+import { MAX_QUESTIONNAIRE_QUESTIONS } from "./constants.js";
 import type {
-	AskResponse,
-	AskToolDetails,
 	AskUserParams,
 	NormalizedOption,
+	NormalizedQuestion,
 	ValidatedAskParams,
 } from "./types.js";
 
 export type { ValidatedAskParams };
 
 export function normalizeOption(
-	raw: string | { title: string; description?: string },
+	raw: string | { title: string; description?: string; recommended?: boolean },
 ): NormalizedOption {
 	if (typeof raw === "string") {
 		return { title: raw.trim() };
@@ -17,6 +17,28 @@ export function normalizeOption(
 	return {
 		title: raw.title.trim(),
 		description: raw.description?.trim() || undefined,
+		recommended: raw.recommended === true ? true : undefined,
+	};
+}
+
+function normalizeQuestion(
+	raw: NonNullable<AskUserParams["questions"]>[number],
+): NormalizedQuestion | string {
+	const title = raw.title?.trim();
+	if (!title) return "ask_user: each questions[] item requires title";
+
+	const options = (raw.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return `ask_user: question "${title}" needs at least 2 options or omit options for freeform`;
+	}
+
+	return {
+		title,
+		description: raw.description?.trim() || undefined,
+		options,
+		allowMultiple: raw.allowMultiple === true,
 	};
 }
 
@@ -28,6 +50,22 @@ export function validateAskParams(
 		return "ask_user: question is required";
 	}
 
+	const rawQuestions = params.questions ?? [];
+	if (rawQuestions.length > MAX_QUESTIONNAIRE_QUESTIONS) {
+		return `ask_user: at most ${MAX_QUESTIONNAIRE_QUESTIONS} questions in questionnaire mode`;
+	}
+
+	if (rawQuestions.length > 0 && (params.options?.length ?? 0) > 0) {
+		return "ask_user: use either options or questions[], not both";
+	}
+
+	const questions: NormalizedQuestion[] = [];
+	for (const q of rawQuestions) {
+		const normalized = normalizeQuestion(q);
+		if (typeof normalized === "string") return normalized;
+		questions.push(normalized);
+	}
+
 	const options = (params.options ?? [])
 		.map(normalizeOption)
 		.filter((o) => o.title);
@@ -36,10 +74,16 @@ export function validateAskParams(
 	}
 
 	const allowFreeform = params.allowFreeform !== false;
-	if (options.length === 0 && !allowFreeform) {
+	const mode = questions.length > 0 ? "questionnaire" : "flat";
+
+	if (mode === "flat" && options.length === 0 && !allowFreeform) {
 		return "ask_user: options required when allowFreeform is false";
 	}
 
+	if (mode === "questionnaire" && questions.length === 0) {
+		return "ask_user: questions[] must not be empty";
+	}
+
 	const displayMode =
 		process.env.HARNESS_ASK_USER_DISPLAY_MODE === "inline"
 			? "inline"
@@ -50,9 +94,14 @@ export function validateAskParams(
 	return {
 		question,
 		context: params.context?.trim() || undefined,
+		contextFormat: params.contextFormat === "html" ? "html" : "markdown",
 		options,
+		questions,
+		mode,
 		allowMultiple: params.allowMultiple === true,
 		allowFreeform,
+		allowComment: params.allowComment === true,
+		allowSkip: params.allowSkip === true,
 		displayMode,
 		timeout:
 			typeof params.timeout === "number" && params.timeout > 0
@@ -60,33 +109,3 @@ export function validateAskParams(
 				: undefined,
 	};
 }
-
-export function formatResultText(
-	response: AskResponse | null,
-	cancelled: boolean,
-): string {
-	if (cancelled || !response) {
-		return "User cancelled (no answer)";
-	}
-	if (response.kind === "freeform") {
-		return `User wrote: ${response.text}`;
-	}
-	if (response.selections.length === 1) {
-		return `User selected: ${response.selections[0]}`;
-	}
-	return `User selected: ${response.selections.join(", ")}`;
-}
-
-export function toToolDetails(
-	validated: ValidatedAskParams,
-	response: AskResponse | null,
-	cancelled: boolean,
-): AskToolDetails {
-	return {
-		question: validated.question,
-		context: validated.context,
-		options: validated.options.map((o) => o.title),
-		response,
-		cancelled,
-	};
-}