pi-ui-extend 0.1.1

package/dist/tool-renderers/utils.js

@@ -0,0 +1,230 @@
+export function normalizeToolName(toolName) {
+    const lastPart = toolName.split(/[.:/]/).filter(Boolean).at(-1) ?? toolName;
+    return lastPart.trim();
+}
+export function parseArgsText(argsText) {
+    const trimmed = argsText.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+}
+export function argsRecord(input) {
+    const parsed = parseArgsText(input.argsText);
+    return isPlainRecord(parsed) ? parsed : undefined;
+}
+export function stringArg(input, keys) {
+    const record = argsRecord(input);
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+        if (typeof value === "number" || typeof value === "boolean")
+            return String(value);
+    }
+    return undefined;
+}
+export function numberArg(input, keys) {
+    const record = argsRecord(input);
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+}
+export function defaultToolRender(input) {
+    const args = parseArgsText(input.argsText);
+    const argsInline = formatArgsInline(args);
+    const argsBlock = formatArgsBlock(args);
+    const expanded = argsAndResultExpandedText(input, argsBlock);
+    return {
+        headerArgs: argsInline,
+        collapsedBody: input.output || argsBlock,
+        ...expanded,
+    };
+}
+export function renderWithArgsAndResult(input, options = {}) {
+    const args = parseArgsText(input.argsText);
+    const argsBlock = options.argumentsBody ?? formatArgsBlock(args);
+    const expanded = argsAndResultExpandedText(input, argsBlock);
+    return {
+        headerArgs: options.headerArgs ?? formatArgsInline(args),
+        collapsedBody: (options.collapsedBody ?? input.output) || argsBlock,
+        ...expanded,
+    };
+}
+export function resultSection(input) {
+    if (input.output)
+        return input.isError ? labeledBlock("error", input.output) : input.output;
+    return input.status === "running" ? "running…" : "(empty)";
+}
+export function argsAndResultExpandedText(input, argsBlock) {
+    const formattedArgs = argsBlock.trimEnd();
+    const showArgs = formattedArgs.length > 0 && formattedArgs !== "(empty)";
+    return expandedTextFromParts(...(showArgs ? [{ text: formattedArgs, color: "muted" }] : []), { text: resultText(input, { empty: !showArgs }) });
+}
+export function resultText(input, options = {}) {
+    if (input.output)
+        return input.isError ? labeledBlock("error", input.output) : input.output;
+    if (input.status === "running")
+        return "running…";
+    return options.empty === false ? "" : "(empty)";
+}
+export function expandedTextFromParts(...parts) {
+    const textParts = [];
+    const bodyLineStyles = [];
+    let startLine = 0;
+    for (const part of parts) {
+        const text = part.text?.trimEnd();
+        if (!text)
+            continue;
+        if (textParts.length > 0)
+            startLine += 1;
+        textParts.push(text);
+        const partLines = lineCount(text);
+        if (part.color || part.foreground || part.bold || part.underline || part.strikethrough) {
+            bodyLineStyles.push({
+                startLine,
+                endLine: startLine + partLines,
+                ...(part.color ? { color: part.color } : {}),
+                ...(part.foreground ? { foreground: part.foreground } : {}),
+                ...(part.bold != null ? { bold: part.bold } : {}),
+                ...(part.underline != null ? { underline: part.underline } : {}),
+                ...(part.strikethrough != null ? { strikethrough: part.strikethrough } : {}),
+            });
+        }
+        startLine += partLines;
+    }
+    return {
+        expandedText: joinSections(...textParts),
+        ...(bodyLineStyles.length > 0 ? { bodyLineStyles } : {}),
+    };
+}
+export function labeledBlock(title, body) {
+    const content = body?.trimEnd();
+    return content ? `${title}\n${content}` : "";
+}
+export function joinSections(...parts) {
+    const joined = parts.filter((part) => part.trim()).join("\n\n");
+    return joined || "(empty)";
+}
+export function indent(text, spaces = 2) {
+    const prefix = " ".repeat(spaces);
+    return text.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
+export function lineCount(text) {
+    return text.split("\n").length;
+}
+export function formatArgsInline(args, preferredKeys) {
+    if (args == null)
+        return "";
+    if (typeof args === "string")
+        return oneLine(args);
+    if (!isPlainRecord(args))
+        return formatInlineValue(args);
+    const entries = orderedEntries(args, preferredKeys);
+    return entries.map(([key, value]) => `${key}: ${formatInlineValue(value)}`).join(" · ");
+}
+export function formatArgsBlock(args, preferredKeys) {
+    if (args == null)
+        return "(empty)";
+    if (typeof args === "string")
+        return args;
+    if (!isPlainRecord(args))
+        return formatBlockValue(args, 0);
+    const entries = orderedEntries(args, preferredKeys);
+    if (entries.length === 0)
+        return "(empty)";
+    return entries.map(([key, value]) => formatRecordEntry(key, value, 0)).join("\n");
+}
+export function summarizePatch(text) {
+    if (!text)
+        return undefined;
+    const files = new Set();
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        const match = /^(?:\*\*\* (?:Update|Add|Delete) File:\s*|Index:\s+|---\s+(?:a\/)?|\+\+\+\s+(?:b\/)?|diff --git a\/)(.+?)(?:\s|$)/.exec(trimmed);
+        const file = match?.[1]?.trim();
+        if (file && !file.startsWith("/dev/null"))
+            files.add(file.replace(/^[ab]\//, ""));
+    }
+    if (files.size === 0)
+        return undefined;
+    const list = [...files];
+    const shown = list.slice(0, 3).join(", ");
+    return list.length > 3 ? `${shown}, +${list.length - 3}` : shown;
+}
+export function compactCommand(command) {
+    return command ? command.replace(/\s+/g, " ").trim() : undefined;
+}
+function orderedEntries(record, preferredKeys) {
+    const entries = Object.entries(record).filter(([, value]) => value !== undefined);
+    if (!preferredKeys || preferredKeys.length === 0)
+        return entries;
+    const order = new Map(preferredKeys.map((key, index) => [key, index]));
+    return entries.sort(([left], [right]) => (order.get(left) ?? Number.MAX_SAFE_INTEGER) - (order.get(right) ?? Number.MAX_SAFE_INTEGER));
+}
+function formatRecordEntry(key, value, depth) {
+    if (isPlainRecord(value) || Array.isArray(value)) {
+        return `${key}:\n${indent(formatBlockValue(value, depth + 1))}`;
+    }
+    return `${key}: ${formatBlockValue(value, depth)}`;
+}
+function formatBlockValue(value, depth) {
+    if (value == null)
+        return String(value);
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (depth >= 2)
+            return `[${value.length} items]`;
+        return value.map((item) => `- ${formatBlockValue(item, depth + 1).replace(/\n/g, "\n  ")}`).join("\n");
+    }
+    if (isPlainRecord(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return "{}";
+        if (depth >= 2)
+            return `{${entries.map(([key]) => key).join(", ")}}`;
+        return entries.map(([key, nested]) => formatRecordEntry(key, nested, depth + 1)).join("\n");
+    }
+    return String(value);
+}
+function formatInlineValue(value) {
+    if (value == null)
+        return String(value);
+    if (typeof value === "string")
+        return oneLine(value);
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const preview = value.slice(0, 3).map(formatInlineValue).join(", ");
+        return value.length > 3 ? `[${preview}, +${value.length - 3}]` : `[${preview}]`;
+    }
+    if (isPlainRecord(value)) {
+        const keys = Object.keys(value);
+        return keys.length === 0 ? "{}" : `{${keys.slice(0, 4).join(", ")}${keys.length > 4 ? ", …" : ""}}`;
+    }
+    return String(value);
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/tool-renderers/web.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRendererMiddleware } from "./types.js";
+export declare const renderWebSearchTool: ToolRendererMiddleware;
+export declare const renderWebFetchTool: ToolRendererMiddleware;

package/dist/tool-renderers/web.js

@@ -0,0 +1,9 @@
+import { renderWithArgsAndResult, stringArg } from "./utils.js";
+export const renderWebSearchTool = (input) => {
+    const query = stringArg(input, ["query"]);
+    return renderWithArgsAndResult(input, { headerArgs: query, collapsedBody: input.output });
+};
+export const renderWebFetchTool = (input) => {
+    const url = stringArg(input, ["url"]);
+    return renderWithArgsAndResult(input, { headerArgs: url, collapsedBody: input.output });
+};

package/dist/tool-renderers/write.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRendererMiddleware } from "./types.js";
+export declare const renderWriteTool: ToolRendererMiddleware;

package/dist/tool-renderers/write.js

@@ -0,0 +1,42 @@
+import { isAbsolute, relative, sep } from "node:path";
+import { syntaxHighlightLanguageForPath } from "../syntax-highlight.js";
+import { argsRecord, expandedTextFromParts, lineCount, resultText, stringArg } from "./utils.js";
+export const renderWriteTool = (input) => {
+    const filePath = stringArg(input, ["path", "file_path", "filePath"]);
+    if (!filePath)
+        return undefined;
+    const displayPath = pathForDisplay(filePath, input.cwd);
+    const content = writeContent(input);
+    const expanded = expandedTextFromParts({ text: content !== undefined ? content || "(empty)" : "" }, { text: resultText(input, { empty: content === undefined }) });
+    const rendered = {
+        headerArgs: displayPath,
+        collapsedBody: content ?? input.output,
+        ...expanded,
+    };
+    if (content === undefined)
+        return rendered;
+    const syntaxLanguage = !input.isError ? syntaxHighlightLanguageForPath(filePath) : undefined;
+    if (!syntaxLanguage)
+        return rendered;
+    return {
+        ...rendered,
+        syntaxHighlight: {
+            language: syntaxLanguage,
+            startLine: 0,
+            endLine: lineCount(content || "(empty)"),
+            startColumn: 0,
+        },
+    };
+};
+function writeContent(input) {
+    const content = argsRecord(input)?.content;
+    return typeof content === "string" ? content : undefined;
+}
+function pathForDisplay(filePath, cwd) {
+    if (!cwd || !isAbsolute(filePath))
+        return filePath;
+    const relativePath = relative(cwd, filePath);
+    if (!relativePath)
+        return ".";
+    return relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath) ? filePath : relativePath.replace(/\\/gu, "/");
+}

package/dist/ui.d.ts

@@ -0,0 +1,56 @@
+export type PopupMenuItem<T> = {
+    value: T;
+    label: string;
+    description?: string;
+};
+export type VisiblePopupMenuItem<T> = PopupMenuItem<T> & {
+    index: number;
+    selected: boolean;
+};
+export declare class PopupMenu<T> {
+    readonly maxVisibleRows: number;
+    items: PopupMenuItem<T>[];
+    selectedIndex: number;
+    scrollOffset: number;
+    open: boolean;
+    constructor(options: {
+        maxVisibleRows: number;
+    });
+    setItems(items: readonly PopupMenuItem<T>[]): void;
+    openWithItems(items: readonly PopupMenuItem<T>[]): void;
+    close(): void;
+    selectedItem(): PopupMenuItem<T> | undefined;
+    moveSelection(delta: number): void;
+    scroll(delta: number): void;
+    visibleItems(): VisiblePopupMenuItem<T>[];
+    maxScrollOffset(): number;
+    private ensureSelectedVisible;
+}
+export declare const TOAST_KINDS: readonly ["success", "error", "warning", "info"];
+export type ToastKind = (typeof TOAST_KINDS)[number];
+export type ToastState = {
+    message: string;
+    kind: ToastKind;
+};
+export type ToastEntry = ToastState & {
+    id: number;
+    createdAt: number;
+};
+export type ToastNotifier = {
+    show(message: string, kind?: ToastKind): void;
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info(message: string): void;
+};
+export declare function isToastKind(value: unknown): value is ToastKind;
+export declare class Toast {
+    private readonly entries;
+    private nextId;
+    show(message: string, kind?: ToastKind): number;
+    hide(id?: number): void;
+    get state(): ToastState | undefined;
+    get visibleStates(): readonly ToastEntry[];
+    entry(toastId: number): ToastEntry | undefined;
+    get visible(): boolean;
+}

package/dist/ui.js

@@ -0,0 +1,94 @@
+export class PopupMenu {
+    maxVisibleRows;
+    items = [];
+    selectedIndex = 0;
+    scrollOffset = 0;
+    open = false;
+    constructor(options) {
+        this.maxVisibleRows = Math.max(1, options.maxVisibleRows);
+    }
+    setItems(items) {
+        this.items = [...items];
+        this.selectedIndex = clamp(this.selectedIndex, 0, Math.max(0, this.items.length - 1));
+        this.scrollOffset = clamp(this.scrollOffset, 0, this.maxScrollOffset());
+        this.ensureSelectedVisible();
+    }
+    openWithItems(items) {
+        this.open = true;
+        this.setItems(items);
+    }
+    close() {
+        this.open = false;
+    }
+    selectedItem() {
+        return this.items[this.selectedIndex];
+    }
+    moveSelection(delta) {
+        if (this.items.length === 0)
+            return;
+        this.selectedIndex = clamp(this.selectedIndex + delta, 0, this.items.length - 1);
+        this.ensureSelectedVisible();
+    }
+    scroll(delta) {
+        this.scrollOffset = clamp(this.scrollOffset + delta, 0, this.maxScrollOffset());
+        this.selectedIndex = clamp(this.selectedIndex, this.scrollOffset, Math.min(this.items.length - 1, this.scrollOffset + this.maxVisibleRows - 1));
+    }
+    visibleItems() {
+        return this.items.slice(this.scrollOffset, this.scrollOffset + this.maxVisibleRows).map((item, offset) => {
+            const index = this.scrollOffset + offset;
+            return { ...item, index, selected: index === this.selectedIndex };
+        });
+    }
+    maxScrollOffset() {
+        return Math.max(0, this.items.length - this.maxVisibleRows);
+    }
+    ensureSelectedVisible() {
+        if (this.selectedIndex < this.scrollOffset) {
+            this.scrollOffset = this.selectedIndex;
+            return;
+        }
+        const lastVisibleIndex = this.scrollOffset + this.maxVisibleRows - 1;
+        if (this.selectedIndex > lastVisibleIndex) {
+            this.scrollOffset = this.selectedIndex - this.maxVisibleRows + 1;
+        }
+    }
+}
+export const TOAST_KINDS = ["success", "error", "warning", "info"];
+export function isToastKind(value) {
+    return typeof value === "string" && TOAST_KINDS.includes(value);
+}
+export class Toast {
+    entries = [];
+    nextId = 1;
+    show(message, kind = "info") {
+        const id = this.nextId;
+        this.nextId += 1;
+        this.entries.push({ id, message, kind, createdAt: Date.now() });
+        return id;
+    }
+    hide(id) {
+        if (id === undefined) {
+            this.entries.splice(0, this.entries.length);
+            return;
+        }
+        const index = this.entries.findIndex((entry) => entry.id === id);
+        if (index >= 0)
+            this.entries.splice(index, 1);
+    }
+    get state() {
+        const entry = this.entries.at(-1);
+        return entry ? { message: entry.message, kind: entry.kind } : undefined;
+    }
+    get visibleStates() {
+        return this.entries;
+    }
+    entry(toastId) {
+        return this.entries.find((entry) => entry.id === toastId);
+    }
+    get visible() {
+        return this.entries.length > 0;
+    }
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}

package/docs/release.md

@@ -0,0 +1,81 @@
+# Release and update verification
+
+Use this checklist before publishing `pi-ui-extend` so installs work on macOS, Linux, and Windows and the `pi-tools-suite` extension payload is included.
+
+## Local release check
+
+```bash
+npm install --ignore-scripts
+npm run release:check
+npm run smoke-test
+```
+
+`release:check` runs type checking, the test suite, a production build, and `npm pack --dry-run`.
+`smoke-test` packs the real tarball, installs it into an isolated temp directory, checks the bundled files, and runs non-interactive `pix` commands from the installed package.
+
+## Publish a new npm version
+
+Pix uses the same release style as `indexer-cli`: a local command bumps the version, smoke-tests the tarball, then pushes the release commit and tag. GitHub Actions publishes the tag to npm using the `NPM_TOKEN` repository secret.
+
+One-time setup:
+
+```bash
+gh secret set NPM_TOKEN
+```
+
+Release commands:
+
+```bash
+npm run publish-npm              # patch release
+npm run publish-npm -- minor      # minor release
+npm run publish-npm -- major      # major release
+npm run publish-npm -- 0.2.0      # exact version
+```
+
+The command requires a clean working tree on `master`, pulls latest from `origin/master`, runs `release:check`, runs `npm version`, runs the tarball smoke test, then pushes the branch and `v*` tag. The tag workflow verifies that `package.json` matches the tag before `npm publish --access public`.
+
+Only the root `package.json` version is bumped for Pix releases. Do not bump `external/pi-tools-suite/package.json` unless publishing the suite as a separate package.
+
+## Tarball smoke test
+
+From a clean temporary directory:
+
+```bash
+npm pack /path/to/pi-ui-extend
+npm install -g ./pi-ui-extend-*.tgz --ignore-scripts
+pix update --check
+```
+
+Confirm the dry-run/pack output contains:
+
+- `bin/pix.mjs`
+- `dist/**`
+- `extensions/**`
+- `external/pi-tools-suite/**`
+- `README.md` and `docs/release.md`
+
+## External suite checks
+
+`external/pi-tools-suite` is a real checked-in package directory, not a symlink. Pix links it into the standard user extension location (`~/.pi/agent/extensions/pi-tools-suite` on macOS/Linux) before creating SDK services. The normal test suite verifies both the renderer-owned bundled extensions and the suite installer/link behavior.
+
+When Bun is available, also run the suite's own checks:
+
+```bash
+npm --prefix external/pi-tools-suite test
+```
+
+Some modules have optional runtime dependencies or host services:
+
+- `web-search` requires a local Ollama web-search/web-fetch API.
+- `terminal-bell` uses optional platform notification helpers when present.
+- `async-subagents` writes run state under the workspace `.pi/subagents/` directory.
+
+## Update UX
+
+- `/update` inside Pix performs a non-mutating npm latest-version check and tells the user what to run.
+- `pix update --check` performs the same check without a TTY.
+- `pix update` updates package-manager installs of Pix and therefore also updates the `external/pi-tools-suite` payload. The next Pix startup refreshes the user extension link.
+- Source checkouts are intentionally not self-mutated; update them with `git pull`, `npm install --ignore-scripts`, `npm run build:pix`, and `npm run link:pix`.
+- Separately installed Pi packages are updated by Pi itself with `pi update --extensions` or `pi update`.
+
+Update checks respect `PI_OFFLINE=1`, `PI_SKIP_VERSION_CHECK=1`, and `PIX_SKIP_VERSION_CHECK=1`.

package/extensions/question/contract.ts

@@ -0,0 +1,100 @@
+import { Type } from "typebox";
+
+import type { NormalizedQuestion, QuestionToolInput } from "./types";
+
+export const CUSTOM_ANSWER_LABEL = "Something else…";
+export const CUSTOM_ANSWER_SENTINEL_VALUE = "__question_custom_answer__";
+export const MIN_QUESTIONS = 1;
+export const MAX_QUESTIONS = 5;
+export const MIN_CHOICES = 2;
+export const MAX_CHOICES = 5;
+export const QUESTION_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+export const questionParameters = Type.Object({
+	questions: Type.Array(Type.Object({
+		id: Type.String({ description: "Unique stable question id." }),
+		label: Type.String({ description: "Short label for the question." }),
+		prompt: Type.String({ description: "Full question prompt to show the user." }),
+		choices: Type.Array(Type.Object({
+			value: Type.String({ description: "Value returned if this choice is selected." }),
+			label: Type.String({ description: "Display label for this choice." }),
+			description: Type.Optional(Type.String({ description: "Optional supporting text for this choice." })),
+		}), {
+			minItems: MIN_CHOICES,
+			maxItems: MAX_CHOICES,
+			description: "Two to five meaningful predefined choices.",
+		}),
+	}), {
+		minItems: MIN_QUESTIONS,
+		maxItems: MAX_QUESTIONS,
+		description: "One to five questions to ask the user.",
+	}),
+});
+
+export function normalizeQuestionInput(input: QuestionToolInput): NormalizedQuestion[] {
+	const questions = input.questions;
+	if (!Array.isArray(questions) || questions.length < MIN_QUESTIONS || questions.length > MAX_QUESTIONS) {
+		throwInvalid(`question requires ${MIN_QUESTIONS} to ${MAX_QUESTIONS} questions; received ${Array.isArray(questions) ? questions.length : "no"}.`, "Retry with a questions array containing one to five questions.");
+	}
+
+	const seenQuestionIds = new Set<string>();
+	const seenQuestionLabels = new Set<string>();
+	return questions.map((question, questionIndex) => {
+		const questionNumber = questionIndex + 1;
+		const id = trimString(question.id, `question ${questionNumber} id`);
+		const label = trimString(question.label, `question ${questionNumber} label`);
+		const prompt = trimString(question.prompt, `question ${questionNumber} prompt`);
+		if (!QUESTION_ID_PATTERN.test(id)) throwInvalid(`Question ${questionNumber} has invalid id "${id}". IDs must match ${QUESTION_ID_PATTERN.source}.`, "Retry with a stable id starting with a lowercase letter and containing only lowercase letters, numbers, underscores, or hyphens.");
+		if (seenQuestionIds.has(id)) throwInvalid(`Duplicate question id "${id}" makes question answers ambiguous.`, "Retry with a unique stable id for each question.");
+		seenQuestionIds.add(id);
+
+		const normalizedLabel = normalizeForUniqueness(label);
+		if (seenQuestionLabels.has(normalizedLabel)) throwInvalid(`Duplicate question label "${label}" makes question summaries ambiguous.`, "Retry with a unique short label for each question; labels are compared case-insensitively.");
+		seenQuestionLabels.add(normalizedLabel);
+		if (label.includes("\n") || label.includes("\r")) throwInvalid(`Question ${questionNumber} label must be single-line.`, "Retry with a short single-line label and put longer text in the prompt.");
+
+		if (!Array.isArray(question.choices) || question.choices.length < MIN_CHOICES || question.choices.length > MAX_CHOICES) {
+			throwInvalid(`Question "${id}" requires ${MIN_CHOICES} to ${MAX_CHOICES} predefined Choices; received ${Array.isArray(question.choices) ? question.choices.length : "no"}.`, "Retry with two to five meaningful predefined Choices for each question.");
+		}
+
+		const seenChoiceValues = new Set<string>();
+		const seenChoiceLabels = new Set<string>();
+		return {
+			id,
+			label,
+			prompt,
+			choices: question.choices.map((choice, choiceIndex) => {
+				const choiceNumber = choiceIndex + 1;
+				const value = trimString(choice.value, `question "${id}" Choice ${choiceNumber} value`);
+				const choiceLabel = trimString(choice.label, `question "${id}" Choice ${choiceNumber} label`);
+				const description = choice.description === undefined ? undefined : choice.description.trim();
+				if (value === CUSTOM_ANSWER_SENTINEL_VALUE) throwInvalid(`Question "${id}" Choice ${choiceNumber} uses the reserved Custom Answer sentinel value "${CUSTOM_ANSWER_SENTINEL_VALUE}".`, "Retry with a different Choice value; ordinary values like other or custom are allowed.");
+
+				const normalizedValue = normalizeForUniqueness(value);
+				if (seenChoiceValues.has(normalizedValue)) throwInvalid(`Question "${id}" has duplicate Choice value "${value}".`, "Retry with unique Choice values within each question; values are compared case-insensitively.");
+				seenChoiceValues.add(normalizedValue);
+
+				const normalizedChoiceLabel = normalizeForUniqueness(choiceLabel);
+				if (seenChoiceLabels.has(normalizedChoiceLabel)) throwInvalid(`Question "${id}" has duplicate Choice label "${choiceLabel}".`, "Retry with unique visible Choice labels within each question; labels are compared case-insensitively.");
+				seenChoiceLabels.add(normalizedChoiceLabel);
+				if (normalizedChoiceLabel === normalizeForUniqueness(CUSTOM_ANSWER_LABEL)) throwInvalid(`Question "${id}" Choice label "${choiceLabel}" collides with the implicit Custom Answer row label "${CUSTOM_ANSWER_LABEL}".`, "Retry with a different predefined Choice label; the Custom Answer row is added automatically.");
+
+				return description === undefined ? { value, label: choiceLabel } : { value, label: choiceLabel, description };
+			}),
+		};
+	});
+}
+
+export function trimString(value: string, field: string): string {
+	const trimmed = value.trim();
+	if (!trimmed) throwInvalid(`${field} must not be empty after trimming.`, "Retry with non-empty text for every required question field.");
+	return trimmed;
+}
+
+export function normalizeForUniqueness(value: string): string {
+	return value.toLocaleLowerCase();
+}
+
+export function throwInvalid(problem: string, repair: string): never {
+	throw new Error(`Invalid question input: ${problem} ${repair}`);
+}

package/extensions/question/index.ts

@@ -0,0 +1,34 @@
+import { QUESTION_TOOL_DESCRIPTION } from "./tool-description";
+import { questionParameters, normalizeQuestionInput } from "./contract";
+import { renderQuestionCall, renderQuestionResult } from "./render";
+import { createCanceledQuestionResult, createQuestionToolResult, createSuccessfulQuestionResult } from "./result";
+import { runQuestionnaire } from "./tui";
+import type { QuestionToolInput, QuestionUiContext } from "./types";
+
+interface ExtensionApiLike {
+	registerTool(tool: unknown): void;
+}
+
+export default function questionExtension(pi: ExtensionApiLike): void {
+	pi.registerTool({
+		...QUESTION_TOOL_DESCRIPTION,
+		parameters: questionParameters,
+		renderCall(args: Partial<QuestionToolInput>, theme: any) {
+			return renderQuestionCall(args, theme);
+		},
+		renderResult(result: any, _options: unknown, theme: any, context: { args?: Partial<QuestionToolInput> }) {
+			return renderQuestionResult(result, theme, context.args);
+		},
+		async execute(_toolCallId: string, params: QuestionToolInput, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: QuestionUiContext) {
+			const questions = normalizeQuestionInput(params);
+			if (!ctx.hasUI) return createQuestionToolResult(createCanceledQuestionResult("ui_unavailable", questions), questions);
+			const selections = await runQuestionnaire(questions, ctx);
+			if (selections === null) return createQuestionToolResult(createCanceledQuestionResult("user_canceled"), questions);
+			return createQuestionToolResult(createSuccessfulQuestionResult(questions, selections), questions);
+		},
+	});
+}
+
+export { questionParameters, normalizeQuestionInput } from "./contract";
+export { createCanceledQuestionResult, createFallbackPrompt, createQuestionToolResult, createSuccessfulQuestionResult, summarizeQuestionResult } from "./result";
+export type { QuestionResultDetails, QuestionToolInput } from "./types";