pi-ui-extend 0.1.32 → 0.1.34

package/dist/bundled-extensions/question/render.d.ts

@@ -0,0 +1,4 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { QuestionTheme, QuestionToolInput, QuestionToolResult } from "./types.js";
+export declare function renderQuestionCall(args: Partial<QuestionToolInput>, theme: QuestionTheme): Text;
+export declare function renderQuestionResult(result: Partial<QuestionToolResult>, theme: QuestionTheme, args?: Partial<QuestionToolInput>): Text;

package/dist/bundled-extensions/question/render.js

@@ -0,0 +1,27 @@
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+export function renderQuestionCall(args, theme) {
+    const questions = Array.isArray(args.questions) ? args.questions : [];
+    const count = questions.length;
+    const labels = questions.map((question) => question?.label || question?.id).filter((label) => typeof label === "string" && label.length > 0).join(", ");
+    let text = theme.fg("toolTitle", (theme.bold ?? ((value) => 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, theme, args) {
+    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/dist/bundled-extensions/question/result.d.ts

@@ -0,0 +1,6 @@
+import type { CanceledQuestionResult, NormalizedQuestion, QuestionResultDetails, QuestionSelection, QuestionToolResult, SuccessfulQuestionResult } from "./types.js";
+export declare function createSuccessfulQuestionResult(questions: NormalizedQuestion[], selections: QuestionSelection[]): SuccessfulQuestionResult;
+export declare function createCanceledQuestionResult(reason: CanceledQuestionResult["reason"], questions?: NormalizedQuestion[]): CanceledQuestionResult;
+export declare function createFallbackPrompt(questions: NormalizedQuestion[]): string;
+export declare function summarizeQuestionResult(result: QuestionResultDetails, questions?: NormalizedQuestion[]): string;
+export declare function createQuestionToolResult(details: QuestionResultDetails, questions?: NormalizedQuestion[]): QuestionToolResult;

package/dist/bundled-extensions/question/result.js

@@ -0,0 +1,84 @@
+import { throwInvalid } from "./contract.js";
+export function createSuccessfulQuestionResult(questions, selections) {
+    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, questions = []) {
+    return {
+        answers: [],
+        canceled: true,
+        reason,
+        ...(reason === "ui_unavailable" && questions.length > 0 ? { fallbackPrompt: createFallbackPrompt(questions) } : {}),
+    };
+}
+export function createFallbackPrompt(questions) {
+    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, questions = []) {
+    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, questions = []) {
+    return {
+        content: [{
+                type: "text",
+                text: summarizeQuestionResult(details, questions),
+            }],
+        details,
+    };
+}

package/dist/bundled-extensions/question/tool-description.d.ts

@@ -0,0 +1,7 @@
+export declare const QUESTION_TOOL_DESCRIPTION: {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+};

package/dist/bundled-extensions/question/tool-description.js

@@ -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.",
+    ],
+};

package/dist/bundled-extensions/question/tui.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedQuestion, QuestionSelection, QuestionUiContext } from "./types.js";
+export declare function runQuestionnaire(questions: NormalizedQuestion[], ctx: QuestionUiContext): Promise<QuestionSelection[] | null>;