Something went wrong. Try again.
This repository has no description
Something went wrong. Try again.
20 kB · 669 lines
TypeScript
at main
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";import { Editor, type EditorTheme, Key, Text, matchesKey, truncateToWidth, wrapTextWithAnsi,} from "@mariozechner/pi-tui";import { Type } from "@sinclair/typebox";
interface AskOption { label: string; value: string; description?: string;}
interface DisplayOption extends AskOption { id: string; index?: number; isOther?: boolean; isSubmit?: boolean;}
interface TextAnswer { type: "text"; label: string; value: string;}
interface OptionAnswer { type: "option"; label: string; value: string; index: number;}
interface OtherAnswer { type: "other"; label: string; value: string;}
type AskAnswer = TextAnswer | OptionAnswer | OtherAnswer;type AskUserQuestionStatus = "answered" | "cancelled" | "unavailable";type AskUserQuestionMode = "text" | "single-select" | "multi-select";
interface AskUserQuestionResultDetails { status: AskUserQuestionStatus; question: string; context?: string; mode: AskUserQuestionMode; answers: AskAnswer[]; message?: string;}
const OptionSchema = Type.Object({ label: Type.String({ description: 'Display label for the option. If you recommend an option, place it first and append "(Recommended)" to the label.', }), value: Type.Optional( Type.String({ description: "Optional machine-readable value returned for the option. Defaults to the label.", }), ), description: Type.Optional(Type.String({ description: "Optional extra detail shown below the option." })),});
const AskUserQuestionParams = Type.Object({ question: Type.String({ description: "The single question to ask the user. Ask exactly one question per tool call.", }), details: Type.Optional( Type.String({ description: "Optional extra context or instructions shown under the question.", }), ), options: Type.Optional( Type.Array(OptionSchema, { description: "Optional multiple-choice options. Omit or pass an empty array for free-form text input. Users will always be able to choose Other and type a custom answer when options are provided.", }), ), multiSelect: Type.Optional( Type.Boolean({ description: "Set to true to allow multiple answers to be selected for a question.", }), ),});
function normalizeOptions(options: Array<{ label: string; value?: string; description?: string }> | undefined): AskOption[] { return (options || []) .map((option) => ({ label: option.label.trim(), value: option.value?.trim() || option.label.trim(), description: option.description?.trim() || undefined, })) .filter((option) => option.label.length > 0);}
function getOtherLabel(options: AskOption[]): string { return options.some((option) => option.label.toLowerCase() === "other") ? "Other (custom)" : "Other";}
function createEditorTheme(theme: any): EditorTheme { return { borderColor: (s) => theme.fg("accent", s), selectList: { selectedPrefix: (t) => theme.fg("accent", t), selectedText: (t) => theme.fg("accent", t), description: (t) => theme.fg("muted", t), scrollInfo: (t) => theme.fg("dim", t), noMatch: (t) => theme.fg("warning", t), }, };}
function addWrapped(lines: string[], text: string, width: number, indent = ""): void { const contentWidth = Math.max(1, width - indent.length); for (const line of wrapTextWithAnsi(text, contentWidth)) { lines.push(truncateToWidth(`${indent}${line}`, width)); }}
function formatAnswerForModel(answer: AskAnswer): string { switch (answer.type) { case "text": return answer.label; case "other": return `Other: ${answer.label}`; case "option": return `${answer.index}. ${answer.label}`; }}
function answerSortRank(answer: AskAnswer): number { switch (answer.type) { case "option": return answer.index; case "other": return Number.MAX_SAFE_INTEGER - 1; case "text": return Number.MAX_SAFE_INTEGER; }}
function sortAnswers(answers: AskAnswer[]): AskAnswer[] { return [...answers].sort((a, b) => answerSortRank(a) - answerSortRank(b));}
function buildStructuredResult( status: AskUserQuestionStatus, question: string, mode: AskUserQuestionMode, answers: AskAnswer[], context?: string, message?: string,) { return { status, question, context, mode, answers, message, } as AskUserQuestionResultDetails;}
function cancelledResult(question: string, mode: AskUserQuestionMode, context?: string) { const message = "User cancelled the question"; return { content: [{ type: "text" as const, text: message }], details: buildStructuredResult("cancelled", question, mode, [], context, message), };}
function unavailableResult(question: string, mode: AskUserQuestionMode, message: string, context?: string) { return { content: [{ type: "text" as const, text: message }], details: buildStructuredResult("unavailable", question, mode, [], context, message), };}
function buildResult(question: string, context: string | undefined, mode: AskUserQuestionMode, answers: AskAnswer[]) { let text: string; if (mode === "text") { const answer = answers[0]; text = answer.label.trim().length > 0 ? `User answered: ${answer.label}` : "User submitted an empty response"; } else if (mode === "single-select") { text = `User selected: ${formatAnswerForModel(answers[0])}`; } else { text = `User selected:\n${answers.map((answer) => `- ${formatAnswerForModel(answer)}`).join("\n")}`; }
return { content: [{ type: "text" as const, text }], details: buildStructuredResult("answered", question, mode, answers, context), };}
async function askSingleChoice( ctx: any, question: string, context: string | undefined, options: AskOption[],): Promise<AskAnswer | null> { const otherLabel = getOtherLabel(options); const allOptions: DisplayOption[] = [ ...options.map((option, index) => ({ ...option, id: `option:${index}`, index: index + 1 })), { id: "other", label: otherLabel, value: "__other__", isOther: true }, ];
return ctx.ui.custom<AskAnswer | null>((tui: any, theme: any, _kb: any, done: (result: AskAnswer | null) => void) => { let optionIndex = 0; let editMode = false; let cachedLines: string[] | undefined; let cachedWidth = -1; const editor = new Editor(tui, createEditorTheme(theme));
editor.onSubmit = (value) => { const trimmed = value.trim(); if (!trimmed) return; done({ type: "other", label: trimmed, value: trimmed }); };
function refresh() { cachedLines = undefined; tui.requestRender(); }
function handleInput(data: string) { if (editMode) { if (matchesKey(data, Key.escape)) { editMode = false; editor.setText(""); refresh(); return; } editor.handleInput(data); refresh(); return; }
if (matchesKey(data, Key.up)) { optionIndex = Math.max(0, optionIndex - 1); refresh(); return; } if (matchesKey(data, Key.down)) { optionIndex = Math.min(allOptions.length - 1, optionIndex + 1); refresh(); return; } if (matchesKey(data, Key.enter)) { const selected = allOptions[optionIndex]; if (selected.isOther) { editMode = true; editor.setText(""); refresh(); return; } done({ type: "option", label: selected.label, value: selected.value, index: selected.index!, }); return; } if (matchesKey(data, Key.escape)) { done(null); } }
function render(width: number): string[] { // The cache MUST be keyed on width: pi-tui calls requestRender() but NOT // invalidate() on terminal resize, so render() can be re-entered with a // new width. Returning stale wider lines trips the TUI width guard and // crashes the process. if (cachedLines && cachedWidth === width) return cachedLines;
const lines: string[] = []; const add = (text: string) => lines.push(truncateToWidth(text, width));
add(theme.fg("accent", "─".repeat(width))); addWrapped(lines, theme.fg("text", ` ${question}`), width); if (context) { lines.push(""); addWrapped(lines, theme.fg("muted", ` ${context}`), width); } lines.push("");
for (let i = 0; i < allOptions.length; i++) { const option = allOptions[i]; const selected = i === optionIndex; const prefix = selected ? theme.fg("accent", "> ") : " "; const label = option.isOther ? option.label : `${option.index}. ${option.label}`; const styled = selected ? theme.fg("accent", label) : theme.fg("text", label); add(`${prefix}${styled}`); if (option.description) { addWrapped(lines, theme.fg("muted", option.description), width, " "); } }
if (editMode) { lines.push(""); add(theme.fg("muted", " Write your custom answer:")); for (const line of editor.render(Math.max(1, width - 2))) { add(` ${line}`); } lines.push(""); add(theme.fg("dim", " Enter to submit • Esc to go back")); } else { lines.push(""); add(theme.fg("dim", " ↑↓ navigate • Enter select • Esc cancel")); }
add(theme.fg("accent", "─".repeat(width))); cachedLines = lines; cachedWidth = width; return lines; }
return { render, invalidate: () => { cachedLines = undefined; }, handleInput, }; });}
async function askMultiChoice( ctx: any, question: string, context: string | undefined, options: AskOption[],): Promise<AskAnswer[] | null> { const otherLabel = getOtherLabel(options); const choiceItems: DisplayOption[] = options.map((option, index) => ({ ...option, id: `option:${index}`, index: index + 1, })); const submitItem: DisplayOption = { id: "submit", label: "Submit", value: "__submit__", isSubmit: true }; const allItems: DisplayOption[] = [ ...choiceItems, { id: "other", label: otherLabel, value: "__other__", isOther: true }, submitItem, ];
return ctx.ui.custom<AskAnswer[] | null>((tui: any, theme: any, _kb: any, done: (result: AskAnswer[] | null) => void) => { let optionIndex = 0; let editMode = false; let cachedLines: string[] | undefined; let cachedWidth = -1; const selected = new Map<string, AskAnswer>(); const editor = new Editor(tui, createEditorTheme(theme));
editor.onSubmit = (value) => { const trimmed = value.trim(); if (!trimmed) return; selected.set("other", { type: "other", label: trimmed, value: trimmed }); editMode = false; refresh(); };
function refresh() { cachedLines = undefined; tui.requestRender(); }
function toggleOption(item: DisplayOption) { if (selected.has(item.id)) { selected.delete(item.id); } else { selected.set(item.id, { type: "option", label: item.label, value: item.value, index: item.index!, }); } refresh(); }
function handleInput(data: string) { if (editMode) { if (matchesKey(data, Key.escape)) { editMode = false; editor.setText(selected.get("other")?.label || ""); refresh(); return; } editor.handleInput(data); refresh(); return; }
if (matchesKey(data, Key.up)) { optionIndex = Math.max(0, optionIndex - 1); refresh(); return; } if (matchesKey(data, Key.down)) { optionIndex = Math.min(allItems.length - 1, optionIndex + 1); refresh(); return; }
const current = allItems[optionIndex]; if (matchesKey(data, Key.space)) { if (current.isSubmit) return; if (current.isOther) { if (selected.has("other")) { selected.delete("other"); refresh(); } else { editMode = true; editor.setText(""); refresh(); } return; } toggleOption(current); return; }
if (matchesKey(data, Key.enter)) { if (current.isSubmit) { if (selected.size > 0) { done(sortAnswers(Array.from(selected.values()))); } return; } if (current.isOther) { editMode = true; editor.setText(selected.get("other")?.label || ""); refresh(); return; } toggleOption(current); return; }
if (matchesKey(data, Key.escape)) { done(null); } }
function render(width: number): string[] { // The cache MUST be keyed on width: pi-tui calls requestRender() but NOT // invalidate() on terminal resize, so render() can be re-entered with a // new width. Returning stale wider lines trips the TUI width guard and // crashes the process. if (cachedLines && cachedWidth === width) return cachedLines;
const lines: string[] = []; const add = (text: string) => lines.push(truncateToWidth(text, width));
add(theme.fg("accent", "─".repeat(width))); addWrapped(lines, theme.fg("text", ` ${question}`), width); if (context) { lines.push(""); addWrapped(lines, theme.fg("muted", ` ${context}`), width); } lines.push("");
for (let i = 0; i < allItems.length; i++) { const item = allItems[i]; const isFocused = i === optionIndex; const prefix = isFocused ? theme.fg("accent", "> ") : " ";
if (item.isSubmit) { const label = selected.size > 0 ? `✓ ${item.label} (${selected.size} selected)` : `○ ${item.label}`; const styled = isFocused ? theme.fg("accent", label) : theme.fg(selected.size > 0 ? "success" : "dim", label); add(`${prefix}${styled}`); continue; }
if (item.isOther) { const other = selected.get("other"); const marker = other ? "[x]" : "[ ]"; const suffix = other ? ` — ${other.label}` : ""; const styled = isFocused ? theme.fg("accent", `${marker} ${item.label}${suffix}`) : theme.fg(other ? "success" : "text", `${marker} ${item.label}${suffix}`); add(`${prefix}${styled}`); continue; }
const checked = selected.has(item.id); const marker = checked ? "[x]" : "[ ]"; const label = `${marker} ${item.index}. ${item.label}`; const styled = isFocused ? theme.fg("accent", label) : theme.fg(checked ? "success" : "text", label); add(`${prefix}${styled}`); if (item.description) { addWrapped(lines, theme.fg("muted", item.description), width, " "); } }
if (editMode) { lines.push(""); add(theme.fg("muted", " Write your custom answer:")); for (const line of editor.render(Math.max(1, width - 2))) { add(` ${line}`); } lines.push(""); add(theme.fg("dim", " Enter to save • Esc to go back")); } else { lines.push(""); if (selected.size === 0) { add(theme.fg("warning", " Select at least one answer before submitting.")); } add(theme.fg("dim", " ↑↓ navigate • Space toggle • Enter edit/submit • Esc cancel")); }
add(theme.fg("accent", "─".repeat(width))); cachedLines = lines; cachedWidth = width; return lines; }
return { render, invalidate: () => { cachedLines = undefined; }, handleInput, }; });}
// Shared UI mutex. ctx.ui.custom()/editor can only handle one active call at// a time, so ALL pop-up-style tools (ask_user_question, quiz, ...) must// serialize against each other, not just against themselves. We stash one// mutex on globalThis so separate extension files can share it without// importing each other.const SHARED_UI_LOCK_KEY = "__piSharedUiLock";function getSharedUiLock() { const g = globalThis as any; if (!g[SHARED_UI_LOCK_KEY]) { let chain: Promise<void> = Promise.resolve(); g[SHARED_UI_LOCK_KEY] = { withLock<T>(fn: () => T | Promise<T>): Promise<T> { const prev = chain; let release: () => void; chain = new Promise<void>((r) => { release = r; }); return prev.then(fn).finally(() => release!()); }, }; } return g[SHARED_UI_LOCK_KEY] as { withLock<T>(fn: () => T | Promise<T>): Promise<T> };}const sharedUiLock = getSharedUiLock();
function withUILock<T>(fn: () => Promise<T>): Promise<T> { return sharedUiLock.withLock(fn);}
export default function askUserQuestion(pi: ExtensionAPI) { pi.registerTool({ name: "ask_user_question", label: "ask_user_question", description: "Ask the user a single question and pause execution until they answer. Use this when requirements are ambiguous, user preferences are needed, a decision would materially affect implementation, or you need confirmation before proceeding. Ask exactly one question per tool call, and prefer multiple separate tool calls over bundling unrelated questions together.", promptSnippet: "Use this tool to ask exactly one clarifying question, missing-requirement question, preference question, or decision question before continuing.", promptGuidelines: [ "Ask exactly one question per tool call.", "If you need answers to multiple questions, make multiple separate ask_user_question tool calls instead of combining them into one prompt.", 'Users will always be able to select "Other" to provide custom text input when options are provided.', "Use multiSelect: true only when you need multiple answers to the same question.", 'If you recommend a specific option, make it the first option in the list and add "(Recommended)" at the end of the label.', "Prefer this tool over guessing when requirements, preferences, or implementation choices are unclear.", "Use this tool when multiple valid implementation paths exist and the preferred path depends on user choice.", ], parameters: AskUserQuestionParams,
async execute(_toolCallId, params, signal, _onUpdate, ctx) { const options = normalizeOptions(params.options); const context = params.details?.trim() || undefined; const mode: AskUserQuestionMode = options.length === 0 ? "text" : params.multiSelect ? "multi-select" : "single-select";
if (signal?.aborted) { return cancelledResult(params.question, mode, context); }
if (!ctx.hasUI) { return unavailableResult(params.question, mode, "ask_user_question requires interactive mode UI", context); }
return withUILock(async () => { if (mode === "text") { const editorTitle = context ? `${params.question}\n\n${context}` : params.question; const answer = await ctx.ui.editor(editorTitle); if (answer === undefined) { return cancelledResult(params.question, mode, context); } return buildResult(params.question, context, mode, [ { type: "text", label: answer.trim(), value: answer.trim() }, ]); }
if (mode === "single-select") { const answer = await askSingleChoice(ctx, params.question, context, options); if (!answer) { return cancelledResult(params.question, mode, context); } return buildResult(params.question, context, mode, [answer]); }
const answers = await askMultiChoice(ctx, params.question, context, options); if (!answers) { return cancelledResult(params.question, mode, context); } return buildResult(params.question, context, mode, answers); }); },
renderCall(args, theme) { const options = normalizeOptions(args.options as Array<{ label: string; value?: string; description?: string }> | undefined); let text = theme.fg("toolTitle", theme.bold("ask_user_question ")) + theme.fg("muted", args.question); if (args.multiSelect) { text += theme.fg("dim", " [multi-select]"); } if (options.length > 0) { const labels = [...options.map((option) => option.label), getOtherLabel(options)].join(", "); text += `\n${theme.fg("dim", ` Options: ${labels}`)}`; } return new Text(text, 0, 0); },
renderResult(result, _options, theme) { const details = result.details as AskUserQuestionResultDetails | undefined; if (!details) { const first = result.content[0]; return new Text(first?.type === "text" ? first.text : "", 0, 0); }
if (details.status === "cancelled") { return new Text(theme.fg("warning", details.message || "Cancelled"), 0, 0); }
if (details.status === "unavailable") { return new Text(theme.fg("warning", details.message || "ask_user_question unavailable"), 0, 0); }
const lines = details.answers.map((answer) => { switch (answer.type) { case "text": return `${theme.fg("success", "✓ ")}${theme.fg("accent", answer.label || "(empty response)")}`; case "other": return `${theme.fg("success", "✓ ")}${theme.fg("muted", "Other: ")}${theme.fg("accent", answer.label)}`; case "option": return `${theme.fg("success", "✓ ")}${theme.fg("accent", `${answer.index}. ${answer.label}`)}`; } }); return new Text(lines.join("\n"), 0, 0); }, });}