ultimate-pi 0.20.0 → 0.22.0

package/.pi/lib/ask-user/presenters/tui.ts

@@ -0,0 +1,373 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import {
+	Editor,
+	type EditorTheme,
+	Key,
+	matchesKey,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
+import {
+	detailFromFlatResult,
+	mergeQuestionnaireResults,
+	questionToFlatParams,
+} from "../core/questionnaire.js";
+import type {
+	AskResponse,
+	DialogResult,
+	ValidatedAskParams,
+} from "../types.js";
+
+type DisplayOption = {
+	title: string;
+	description?: string;
+	isFreeform?: boolean;
+};
+
+interface CustomAnswer {
+	response: AskResponse;
+}
+
+type ThemeLike = { fg(color: string, text: string): string };
+type TuiLike = ConstructorParameters<typeof Editor>[0] & {
+	requestRender(): void;
+};
+type Done = (answer: CustomAnswer | null) => void;
+
+function withTimeout<T>(
+	promise: Promise<T | null>,
+	ms: number | undefined,
+): Promise<T | null> {
+	if (!ms) return promise;
+	return Promise.race([
+		promise,
+		new Promise<null>((resolve) => {
+			setTimeout(() => resolve(null), ms);
+		}),
+	]);
+}
+
+function displayOptionsFor(validated: ValidatedAskParams): DisplayOption[] {
+	const displayOptions: DisplayOption[] = [...validated.options];
+	if (validated.allowFreeform) {
+		displayOptions.push({ title: "Type something…", isFreeform: true });
+	}
+	return displayOptions;
+}
+
+async function runFreeformOnly(
+	ui: ExtensionUIContext,
+	question: string,
+): Promise<DialogResult> {
+	const text = await ui.input(question, "");
+	if (!text?.trim()) {
+		return { response: null, cancelled: true, ui_backend: "tui" };
+	}
+	return {
+		response: { kind: "freeform", text: text.trim() },
+		cancelled: false,
+		ui_backend: "tui",
+	};
+}
+
+function editorThemeFor(theme: ThemeLike): 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),
+		},
+	};
+}
+
+class AskDialogController {
+	private optionIndex = 0;
+	private editMode = false;
+	private readonly selected = new Set<number>();
+	private cachedLines: string[] | undefined;
+	private readonly editor: Editor;
+
+	constructor(
+		private readonly validated: ValidatedAskParams,
+		private readonly displayOptions: DisplayOption[],
+		private readonly tui: TuiLike,
+		private readonly theme: ThemeLike,
+		private readonly done: Done,
+	) {
+		this.editor = new Editor(tui, editorThemeFor(theme));
+		this.editor.onSubmit = (value) => this.submitFreeform(value);
+	}
+
+	invalidate(): void {
+		this.cachedLines = undefined;
+	}
+
+	handleInput(data: string): void {
+		if (this.editMode) {
+			this.handleEditInput(data);
+			return;
+		}
+		if (this.handleNavigationInput(data)) return;
+		if (this.validated.allowMultiple && matchesKey(data, Key.space)) {
+			this.toggleMultiSelect();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) this.submitSelection();
+		if (matchesKey(data, Key.escape)) this.done(null);
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines) return this.cachedLines;
+		const lines: string[] = [];
+		const add = (s: string) => lines.push(truncateToWidth(s, width));
+		const useOverlay = this.validated.displayMode !== "inline";
+		this.renderHeader(lines, add, width, useOverlay);
+		this.renderOptions(add);
+		this.renderEditor(lines, add, width);
+		this.renderFooter(add, width, useOverlay);
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	private refresh(): void {
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	private submitFreeform(value: string): void {
+		const trimmed = value.trim();
+		if (trimmed) {
+			this.done({ response: { kind: "freeform", text: trimmed } });
+			return;
+		}
+		this.editMode = false;
+		this.editor.setText("");
+		this.refresh();
+	}
+
+	private submitSelection(): void {
+		if (this.validated.allowMultiple) {
+			const titles = [...this.selected]
+				.sort((a, b) => a - b)
+				.map((i) => this.displayOptions[i].title)
+				.filter((t) => t !== "Type something…");
+			if (titles.length) {
+				this.done({ response: { kind: "selection", selections: titles } });
+			}
+			return;
+		}
+		const opt = this.displayOptions[this.optionIndex];
+		if (opt.isFreeform) {
+			this.editMode = true;
+			this.refresh();
+			return;
+		}
+		this.done({ response: { kind: "selection", selections: [opt.title] } });
+	}
+
+	private handleEditInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.editMode = false;
+			this.editor.setText("");
+		} else {
+			this.editor.handleInput(data);
+		}
+		this.refresh();
+	}
+
+	private handleNavigationInput(data: string): boolean {
+		if (matchesKey(data, Key.up)) {
+			this.optionIndex = Math.max(0, this.optionIndex - 1);
+			this.refresh();
+			return true;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.optionIndex = Math.min(
+				this.displayOptions.length - 1,
+				this.optionIndex + 1,
+			);
+			this.refresh();
+			return true;
+		}
+		return false;
+	}
+
+	private toggleMultiSelect(): void {
+		const opt = this.displayOptions[this.optionIndex];
+		if (opt.isFreeform) return;
+		if (this.selected.has(this.optionIndex)) {
+			this.selected.delete(this.optionIndex);
+		} else {
+			this.selected.add(this.optionIndex);
+		}
+		this.refresh();
+	}
+
+	private renderHeader(
+		lines: string[],
+		add: (s: string) => void,
+		width: number,
+		useOverlay: boolean,
+	): void {
+		if (useOverlay) add(this.theme.fg("accent", "─".repeat(width)));
+		if (this.validated.context) {
+			for (const line of this.validated.context.split("\n")) {
+				add(this.theme.fg("muted", ` ${line}`));
+			}
+			lines.push("");
+		}
+		add(this.theme.fg("text", ` ${this.validated.question}`));
+		lines.push("");
+	}
+
+	private renderOptions(add: (s: string) => void): void {
+		for (let i = 0; i < this.displayOptions.length; i++) {
+			const opt = this.displayOptions[i];
+			const prefix = this.optionPrefix(i, opt.isFreeform === true);
+			const label = this.optionLabel(i, opt);
+			add(`${prefix}${label}`);
+			if (opt.description)
+				add(`     ${this.theme.fg("muted", opt.description)}`);
+		}
+	}
+
+	private optionPrefix(index: number, isFreeform: boolean): string {
+		if (!this.validated.allowMultiple) {
+			return index === this.optionIndex ? this.theme.fg("accent", "> ") : "  ";
+		}
+		if (isFreeform) return "  ";
+		return this.selected.has(index) ? this.theme.fg("accent", "[x] ") : "[ ] ";
+	}
+
+	private optionLabel(index: number, opt: DisplayOption): string {
+		const raw = `${index + 1}. ${opt.title}`;
+		const focused = index === this.optionIndex;
+		if (opt.isFreeform && this.editMode && focused) {
+			return this.theme.fg("accent", `${raw} ✎`);
+		}
+		if (focused && !this.validated.allowMultiple) {
+			return this.theme.fg("accent", raw);
+		}
+		return this.theme.fg("text", raw);
+	}
+
+	private renderEditor(
+		lines: string[],
+		add: (s: string) => void,
+		width: number,
+	): void {
+		if (!this.editMode) return;
+		lines.push("");
+		add(this.theme.fg("muted", " Your answer:"));
+		for (const line of this.editor.render(width - 2)) add(` ${line}`);
+	}
+
+	private renderFooter(
+		add: (s: string) => void,
+		width: number,
+		useOverlay: boolean,
+	): void {
+		add("");
+		if (this.editMode) {
+			add(this.theme.fg("dim", " Enter to submit • Esc to go back"));
+		} else if (this.validated.allowMultiple) {
+			add(
+				this.theme.fg(
+					"dim",
+					" ↑↓ navigate • Space toggle • Enter confirm • Esc cancel",
+				),
+			);
+		} else {
+			add(
+				this.theme.fg("dim", " ↑↓ navigate • Enter to select • Esc to cancel"),
+			);
+		}
+		if (useOverlay) add(this.theme.fg("accent", "─".repeat(width)));
+	}
+}
+
+async function runOptionDialog(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+	displayOptions: DisplayOption[],
+): Promise<CustomAnswer | null> {
+	return withTimeout(
+		ui.custom<CustomAnswer | null>((tui, theme, _kb, done) => {
+			const controller = new AskDialogController(
+				validated,
+				displayOptions,
+				tui as TuiLike,
+				theme,
+				done,
+			);
+			return {
+				render: (width: number) => controller.render(width),
+				invalidate: () => controller.invalidate(),
+				handleInput: (data: string) => controller.handleInput(data),
+			};
+		}),
+		validated.timeout,
+	);
+}
+
+async function runFlatTui(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+): Promise<DialogResult> {
+	const displayOptions = displayOptionsFor(validated);
+	if (displayOptions.length === 0) {
+		const r = await runFreeformOnly(ui, validated.question);
+		return { ...r, ui_backend: "tui" };
+	}
+	const result = await runOptionDialog(ui, validated, displayOptions);
+	if (!result) {
+		return { response: null, cancelled: true, ui_backend: "tui" };
+	}
+	return { response: result.response, cancelled: false, ui_backend: "tui" };
+}
+
+async function runQuestionnaireTui(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+): Promise<DialogResult> {
+	const total = validated.questions.length;
+	const details = [];
+	let last: DialogResult | undefined;
+
+	for (let i = 0; i < total; i++) {
+		const q = validated.questions[i];
+		const flat = questionToFlatParams(validated, q, i, total);
+		const step = await runFlatTui(ui, flat);
+		last = step;
+		if (step.cancelled) {
+			return { response: null, cancelled: true, ui_backend: "tui" };
+		}
+		const label = q.description ?? q.title;
+		const detail = detailFromFlatResult(label, step);
+		if (!detail) {
+			if (!validated.allowSkip) {
+				return { response: null, cancelled: true, ui_backend: "tui" };
+			}
+			continue;
+		}
+		details.push(detail);
+	}
+
+	return mergeQuestionnaireResults(details, last);
+}
+
+/** TUI presenter (overlay or inline). */
+export async function runTuiPresenter(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+): Promise<DialogResult> {
+	if (validated.mode === "questionnaire") {
+		return runQuestionnaireTui(ui, validated);
+	}
+	return runFlatTui(ui, validated);
+}
+
+/** @deprecated Use runTuiPresenter */
+export const runAskDialog = runTuiPresenter;

package/.pi/lib/ask-user/presenters/types.ts

@@ -0,0 +1,13 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { DialogResult, ValidatedAskParams } from "../types.js";
+
+export interface PresenterContext {
+	ui: ExtensionUIContext;
+	hasUI: boolean;
+	sessionName?: string;
+}
+
+export type AskUserPresenter = (
+	validated: ValidatedAskParams,
+	ctx: PresenterContext,
+) => Promise<DialogResult>;

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

@@ -16,16 +16,25 @@ export function renderAskCall(
 	if (args.context) {
 		text += `\n${theme.fg("dim", `  ${String(args.context)}`)}`;
 	}
-	const opts = Array.isArray(args.options) ? args.options : [];
-	if (opts.length) {
-		const labels = opts.map((o: unknown) =>
-			typeof o === "string" ? o : ((o as { title?: string })?.title ?? "?"),
-		);
-		const numbered = labels.map((o, i) => `${i + 1}. ${o}`);
-		if (args.allowFreeform !== false) {
-			numbered.push(`${numbered.length + 1}. Type something…`);
+	const questions = Array.isArray(args.questions) ? args.questions : [];
+	if (questions.length > 0) {
+		text += `\n${theme.fg("dim", `  Questionnaire: ${questions.length} item(s)`)}`;
+		const first = questions[0] as { title?: string };
+		if (first?.title) {
+			text += `\n${theme.fg("dim", `  First: ${first.title}`)}`;
+		}
+	} else {
+		const opts = Array.isArray(args.options) ? args.options : [];
+		if (opts.length) {
+			const labels = opts.map((o: unknown) =>
+				typeof o === "string" ? o : ((o as { title?: string })?.title ?? "?"),
+			);
+			const numbered = labels.map((o, i) => `${i + 1}. ${o}`);
+			if (args.allowFreeform !== false) {
+				numbered.push(`${numbered.length + 1}. Type something…`);
+			}
+			text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
 		}
-		text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
 	}
 	return new Text(text, 0, 0);
 }
@@ -45,6 +54,19 @@ export function renderAskResult(
 		return new Text(theme.fg("warning", "Cancelled"), 0, 0);
 	}
 
+	if (details.ui_degraded) {
+		return new Text(
+			theme.fg("warning", "↓ TUI ") +
+				theme.fg("success", "✓ ") +
+				theme.fg(
+					"muted",
+					result.content[0]?.type === "text" ? result.content[0].text : "",
+				),
+			0,
+			0,
+		);
+	}
+
 	if (details.response.kind === "freeform") {
 		return new Text(
 			theme.fg("success", "✓ ") +
@@ -55,6 +77,15 @@ export function renderAskResult(
 		);
 	}
 
+	if (details.response.kind === "questionnaire") {
+		const count = details.response.questionnaireDetails.length;
+		return new Text(
+			theme.fg("success", "✓ ") + theme.fg("accent", `${count} answer(s)`),
+			0,
+			0,
+		);
+	}
+
 	const sel = details.response.selections;
 	const display =
 		sel.length === 1 ? sel[0] : sel.map((s, i) => `${i + 1}. ${s}`).join(", ");

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

@@ -12,24 +12,62 @@ function StringEnum<T extends string[]>(
 	});
 }
 
+const OptionObjectSchema = Type.Object({
+	title: Type.String({ description: "Short option label" }),
+	description: Type.Optional(
+		Type.String({ description: "Optional explanation" }),
+	),
+	recommended: Type.Optional(
+		Type.Boolean({ description: "Show a Recommended badge" }),
+	),
+});
+
 const OptionSchema = Type.Union([
 	Type.String({ description: "Option label" }),
-	Type.Object({
-		title: Type.String({ description: "Short option label" }),
-		description: Type.Optional(
-			Type.String({ description: "Optional explanation" }),
-		),
-	}),
+	OptionObjectSchema,
 ]);
 
+const QuestionSchema = Type.Object({
+	title: Type.String({ description: "Short label for this sub-question" }),
+	description: Type.Optional(
+		Type.String({ description: "Full question text shown in the card" }),
+	),
+	options: Type.Optional(
+		Type.Array(OptionSchema, {
+			description: "If omitted, renders as freeform textarea",
+		}),
+	),
+	allowMultiple: Type.Optional(
+		Type.Boolean({
+			description: "Allow multiple selections for this sub-question",
+			default: false,
+		}),
+	),
+});
+
 export const AskUserParamsSchema = Type.Object({
 	question: Type.String({ description: "The question to ask the user" }),
 	context: Type.Optional(
-		Type.String({ description: "Context shown above the question" }),
+		Type.String({
+			description:
+				"Additional context (markdown or HTML panel when contextFormat is set)",
+		}),
+	),
+	contextFormat: Type.Optional(
+		StringEnum(["markdown", "html"] as const, {
+			description: "How to render context in rich UI (default markdown)",
+		}),
 	),
 	options: Type.Optional(
 		Type.Array(OptionSchema, {
-			description: "Multiple-choice options (min 2 if provided)",
+			description:
+				"Flat mode: multiple-choice options (min 2 if provided). Ignored when questions is set.",
+		}),
+	),
+	questions: Type.Optional(
+		Type.Array(QuestionSchema, {
+			description:
+				"Questionnaire mode: batch independent forks in one dialog (max 8)",
 		}),
 	),
 	allowMultiple: Type.Optional(
@@ -40,18 +78,31 @@ export const AskUserParamsSchema = Type.Object({
 	),
 	allowFreeform: Type.Optional(
 		Type.Boolean({
-			description: 'Append "Type something…" freeform row',
+			description: 'Allow custom answer (TUI: "Type something…" row)',
 			default: true,
 		}),
 	),
+	allowComment: Type.Optional(
+		Type.Boolean({
+			description: "Collect optional comment after selection",
+			default: false,
+		}),
+	),
+	allowSkip: Type.Optional(
+		Type.Boolean({
+			description: "Questionnaire only: allow submit with unanswered items",
+			default: false,
+		}),
+	),
 	displayMode: Type.Optional(
 		StringEnum(["overlay", "inline"] as const, {
-			description: "overlay = modal (default), inline = in transcript flow",
+			description:
+				"overlay = modal (default); inline = transcript flow (forces TUI)",
 		}),
 	),
 	timeout: Type.Optional(
 		Type.Number({
-			description: "Auto-cancel after N milliseconds",
+			description: "Auto-cancel after N milliseconds (TUI/headless only)",
 			minimum: 1,
 		}),
 	),
@@ -62,8 +113,10 @@ export const PROMPT_SNIPPET =
 
 export const PROMPT_GUIDELINES = [
 	"Use ask_user when requirements are ambiguous, conflicting, or high-impact — never guess on harness forks (Firecrawl mode, .env creation, scope, risk, merge policy).",
-	"Prefer one focused question per call with 2–4 clear options and short descriptions for trade-offs.",
+	"Prefer one focused flat question with 2–4 options, or use questions[] when 2–4 independent dimensions must be decided in one clarification round (max 8 sub-questions).",
+	"Use context (markdown) for evidence bullets; keep under ~500 chars unless the fork is architectural.",
+	"Never use ask_user for final plan approval — use approve_plan.",
 	"If the user cancels (Esc), stop and report needs_clarification; do not proceed with assumptions.",
-	"Do not stack redundant ask_user calls — combine related choices when phase 2 batch mode exists.",
 	"Independent evaluator/adversary agents must not call ask_user; emit human_required and let the orchestrator ask.",
+	"After Phase 0 ask_user, merge answers into task-clarification.yaml via applyAskUserToTaskClarification (harness-decisions skill).",
 ];

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

@@ -1,26 +1,70 @@
 export interface NormalizedOption {
 	title: string;
 	description?: string;
+	recommended?: boolean;
 }
 
+export interface NormalizedQuestion {
+	title: string;
+	description?: string;
+	options: NormalizedOption[];
+	allowMultiple: boolean;
+}
+
+export type QuestionnaireDetail = {
+	question: string;
+	answer: string;
+	kind: "selection" | "freeform";
+	comment?: string;
+};
+
 export type AskResponse =
-	| { kind: "selection"; selections: string[] }
-	| { kind: "freeform"; text: string };
+	| {
+			kind: "selection";
+			selections: string[];
+			comment?: string;
+			additionalComments?: string;
+	  }
+	| { kind: "freeform"; text: string; additionalComments?: string }
+	| {
+			kind: "questionnaire";
+			questionnaireDetails: QuestionnaireDetail[];
+			additionalComments?: string;
+	  };
+
+export type UiBackend = "tui" | "glimpse" | "headless";
 
 export interface AskToolDetails {
 	question: string;
 	context?: string;
+	contextFormat?: "markdown" | "html";
 	options: string[];
 	response: AskResponse | null;
 	cancelled: boolean;
+	ui_backend: UiBackend;
+	ui_degraded?: boolean;
+	non_interactive_blocked?: boolean;
 }
 
 export interface AskUserParams {
 	question: string;
 	context?: string;
-	options?: Array<string | { title: string; description?: string }>;
+	contextFormat?: "markdown" | "html";
+	options?: Array<
+		string | { title: string; description?: string; recommended?: boolean }
+	>;
+	questions?: Array<{
+		title: string;
+		description?: string;
+		options?: Array<
+			string | { title: string; description?: string; recommended?: boolean }
+		>;
+		allowMultiple?: boolean;
+	}>;
 	allowMultiple?: boolean;
 	allowFreeform?: boolean;
+	allowComment?: boolean;
+	allowSkip?: boolean;
 	displayMode?: "overlay" | "inline";
 	timeout?: number;
 }
@@ -28,9 +72,15 @@ export interface AskUserParams {
 export interface ValidatedAskParams {
 	question: string;
 	context?: string;
+	contextFormat: "markdown" | "html";
+	/** Flat single/multi-select mode */
 	options: NormalizedOption[];
+	questions: NormalizedQuestion[];
+	mode: "flat" | "questionnaire";
 	allowMultiple: boolean;
 	allowFreeform: boolean;
+	allowComment: boolean;
+	allowSkip: boolean;
 	displayMode: "overlay" | "inline";
 	timeout?: number;
 }
@@ -38,4 +88,11 @@ export interface ValidatedAskParams {
 export interface DialogResult {
 	response: AskResponse | null;
 	cancelled: boolean;
+	ui_backend: UiBackend;
+	ui_degraded?: boolean;
+}
+
+export interface RunAskUserResult {
+	content: { type: "text"; text: string }[];
+	details: AskToolDetails;
 }