pi-ui-extend 0.1.1

package/extensions/question/render.ts

@@ -0,0 +1,28 @@
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+import type { QuestionTheme, QuestionToolInput, QuestionToolResult } from "./types";
+
+export function renderQuestionCall(args: Partial<QuestionToolInput>, theme: QuestionTheme): Text {
+	const questions = Array.isArray(args.questions) ? args.questions : [];
+	const count = questions.length;
+	const labels = questions.map((question) => question?.label || question?.id).filter((label): label is string => typeof label === "string" && label.length > 0).join(", ");
+	let text = theme.fg("toolTitle", (theme.bold ?? ((value: string) => value))("question "));
+	text += theme.fg("muted", `${count} question${count === 1 ? "" : "s"}`);
+	if (labels) text += theme.fg("dim", ` (${truncateToWidth(labels, 48)})`);
+	return new Text(text, 0, 0);
+}
+
+export function renderQuestionResult(result: Partial<QuestionToolResult>, theme: QuestionTheme, args?: Partial<QuestionToolInput>): Text {
+	const details = result.details;
+	if (!details) {
+		const firstContent = result.content?.[0];
+		return new Text(firstContent?.type === "text" ? firstContent.text : "", 0, 0);
+	}
+	if (details.canceled) return new Text(theme.fg("warning", details.reason === "ui_unavailable" ? "Canceled: UI unavailable" : "Canceled"), 0, 0);
+	const labels = new Map((Array.isArray(args?.questions) ? args.questions : []).map((question) => [question.id, question.label]));
+	return new Text(details.answers.map((answer) => {
+		const questionLabel = labels.get(answer.id) ?? answer.id;
+		if (answer.wasCustom) return `${theme.fg("success", "✓ ")}${theme.fg("accent", `${questionLabel}:`)} ${theme.fg("muted", "custom ")}${answer.label}`;
+		return `${theme.fg("success", "✓ ")}${theme.fg("accent", `${questionLabel}:`)} ${answer.index}. ${answer.label}`;
+	}).join("\n"), 0, 0);
+}

package/extensions/question/result.ts

@@ -0,0 +1,86 @@
+import { throwInvalid } from "./contract";
+import type { CanceledQuestionResult, NormalizedQuestion, QuestionResultDetails, QuestionSelection, QuestionToolResult, SuccessfulQuestionResult } from "./types";
+
+export function createSuccessfulQuestionResult(questions: NormalizedQuestion[], selections: QuestionSelection[]): SuccessfulQuestionResult {
+	const selectionsById = new Map(selections.map((selection) => [selection.id, selection]));
+	return {
+		answers: questions.map((question) => {
+			const selection = selectionsById.get(question.id);
+			if (!selection) throwInvalid(`Missing answer for question "${question.id}".`, "Retry after collecting one answer for each normalized question.");
+			if ("customText" in selection) {
+				const customText = selection.customText.trim();
+				if (!customText) throwInvalid(`Custom Answer for question "${question.id}" is empty after trimming.`, "Retry with non-empty Custom Answer text or choose a predefined Choice.");
+				return {
+					id: question.id,
+					value: customText,
+					label: customText,
+					wasCustom: true,
+				};
+			}
+
+			const choiceIndex = question.choices.findIndex((choice) => choice.value === selection.choiceValue);
+			if (choiceIndex === -1) throwInvalid(`Question "${question.id}" has no predefined Choice with value "${selection.choiceValue}".`, "Retry with one of the normalized predefined Choice values for that question.");
+			const choice = question.choices[choiceIndex]!;
+			return {
+				id: question.id,
+				value: choice.value,
+				label: choice.label,
+				wasCustom: false,
+				index: choiceIndex + 1,
+			};
+		}),
+		canceled: false,
+	};
+}
+
+export function createCanceledQuestionResult(reason: CanceledQuestionResult["reason"], questions: NormalizedQuestion[] = []): CanceledQuestionResult {
+	return {
+		answers: [],
+		canceled: true,
+		reason,
+		...(reason === "ui_unavailable" && questions.length > 0 ? { fallbackPrompt: createFallbackPrompt(questions) } : {}),
+	};
+}
+
+export function createFallbackPrompt(questions: NormalizedQuestion[]): string {
+	const lines = [
+		"Interactive UI is unavailable. Ask the user these structured questions in normal chat instead, then use the user's replies without inventing answers.",
+	];
+	questions.forEach((question, index) => {
+		lines.push("", `${index + 1}. ${question.label}: ${question.prompt}`);
+		question.choices.forEach((choice, choiceIndex) => {
+			const suffix = choice.description ? ` — ${choice.description}` : "";
+			lines.push(`   ${choiceIndex + 1}. ${choice.label}${suffix}`);
+		});
+		lines.push(`   ${question.choices.length + 1}. Something else… (custom answer)`);
+	});
+	return lines.join("\n");
+}
+
+export function summarizeQuestionResult(result: QuestionResultDetails, questions: NormalizedQuestion[] = []): string {
+	if (result.canceled) {
+		if (result.reason === "ui_unavailable") {
+			return result.fallbackPrompt
+				? `No interactive UI is available, so question was canceled. Do not assume an answer. Ask the user in normal chat instead.\n\n${result.fallbackPrompt}`
+				: "No interactive UI is available, so question was canceled. Do not assume an answer.";
+		}
+		return "The user canceled question. Do not assume an answer.";
+	}
+	if (result.answers.length === 0) return "question returned no answers.";
+	const questionLabels = new Map(questions.map((question) => [question.id, question.label]));
+	return `question answers: ${result.answers.map((answer) => {
+		const questionLabel = questionLabels.get(answer.id) ?? answer.id;
+		if (answer.wasCustom) return `${questionLabel}: ${answer.label} (custom answer)`;
+		return `${questionLabel}: ${answer.label} (choice ${answer.index})`;
+	}).join("; ")}.`;
+}
+
+export function createQuestionToolResult(details: QuestionResultDetails, questions: NormalizedQuestion[] = []): QuestionToolResult {
+	return {
+		content: [{
+			type: "text",
+			text: summarizeQuestionResult(details, questions),
+		}],
+		details,
+	};
+}

package/extensions/question/tool-description.ts

@@ -0,0 +1,11 @@
+export const QUESTION_TOOL_DESCRIPTION = {
+	name: "question",
+	label: "Question",
+	description: "Ask the user one to five structured questions, each with two to five choices plus an implicit custom answer path.",
+	promptSnippet: "Gather structured user feedback with predefined choices and an always-available custom answer path.",
+	promptGuidelines: [
+		"Use question when gathering user feedback, choosing between alternatives, confirming direction, or resolving ambiguity, as long as you can provide at least two meaningful choices.",
+		"question accepts 1–5 questions; each question needs 2–5 meaningful choices and automatically includes a custom answer path.",
+		"Do not use question when the user's input is purely open-ended or when a normal conversational reply is clearer.",
+	],
+};