ultimate-pi 0.20.0 → 0.22.0

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

@@ -1,314 +1,2 @@
-import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import {
-	Editor,
-	type EditorTheme,
-	Key,
-	matchesKey,
-	truncateToWidth,
-} from "@earendil-works/pi-tui";
-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 };
-	return {
-		response: { kind: "freeform", text: text.trim() },
-		cancelled: false,
-	};
-}
-
-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,
-	);
-}
-
-export async function runAskDialog(
-	ui: ExtensionUIContext,
-	validated: ValidatedAskParams,
-): Promise<DialogResult> {
-	const displayOptions = displayOptionsFor(validated);
-	if (displayOptions.length === 0) {
-		return runFreeformOnly(ui, validated.question);
-	}
-	const result = await runOptionDialog(ui, validated, displayOptions);
-	if (!result) return { response: null, cancelled: true };
-	return { response: result.response, cancelled: false };
-}
+/** @deprecated Import from ./presenters/tui.js */
+export { runAskDialog, runTuiPresenter } from "./presenters/tui.js";

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

@@ -1,78 +1,2 @@
-import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import type { DialogResult, ValidatedAskParams } from "./types.js";
-
-export async function runAskFallback(
-	ui: ExtensionUIContext,
-	validated: ValidatedAskParams,
-): Promise<DialogResult> {
-	const { question, context, options, allowMultiple, allowFreeform } =
-		validated;
-
-	const title = context ? `${context}\n\n${question}` : question;
-	const labels = options.map((o) => o.title);
-
-	if (labels.length === 0) {
-		if (!allowFreeform) {
-			return { response: null, cancelled: true };
-		}
-		const text = await ui.input(title, "");
-		if (!text?.trim()) {
-			return { response: null, cancelled: true };
-		}
-		return {
-			response: { kind: "freeform", text: text.trim() },
-			cancelled: false,
-		};
-	}
-
-	if (allowMultiple) {
-		const selections: string[] = [];
-		const remaining = [...labels];
-		while (remaining.length > 0) {
-			const pick = await ui.select(
-				selections.length === 0
-					? title
-					: `${title}\n(selected: ${selections.join(", ")})`,
-				[...remaining, "(done selecting)"],
-			);
-			if (!pick) {
-				return { response: null, cancelled: true };
-			}
-			if (pick === "(done selecting)") {
-				break;
-			}
-			selections.push(pick);
-			const idx = remaining.indexOf(pick);
-			if (idx >= 0) remaining.splice(idx, 1);
-		}
-		if (selections.length === 0) {
-			return { response: null, cancelled: true };
-		}
-		return {
-			response: { kind: "selection", selections },
-			cancelled: false,
-		};
-	}
-
-	const choices = allowFreeform ? [...labels, "Type something…"] : labels;
-	const picked = await ui.select(title, choices);
-	if (!picked) {
-		return { response: null, cancelled: true };
-	}
-
-	if (picked === "Type something…") {
-		const text = await ui.input(question, "");
-		if (!text?.trim()) {
-			return { response: null, cancelled: true };
-		}
-		return {
-			response: { kind: "freeform", text: text.trim() },
-			cancelled: false,
-		};
-	}
-
-	return {
-		response: { kind: "selection", selections: [picked] },
-		cancelled: false,
-	};
-}
+/** @deprecated Import from ./presenters/headless.js */
+export { runAskFallback, runHeadlessPresenter } from "./presenters/headless.js";

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

@@ -0,0 +1,85 @@
+import type {
+	AskResponse,
+	AskToolDetails,
+	UiBackend,
+	ValidatedAskParams,
+} from "./types.js";
+
+export function formatResultText(
+	response: AskResponse | null,
+	cancelled: boolean,
+	opts?: { ui_degraded?: boolean },
+): string {
+	if (cancelled || !response) {
+		return "User cancelled (no answer)";
+	}
+
+	if (opts?.ui_degraded) {
+		return `Rich ask UI unavailable; using terminal prompt.\n\n${formatResponseBody(response)}`;
+	}
+
+	return formatResponseBody(response);
+}
+
+function formatResponseBody(response: AskResponse): string {
+	if (response.kind === "freeform") {
+		const base = `User wrote: ${response.text}`;
+		return appendComments(base, response.additionalComments);
+	}
+
+	if (response.kind === "questionnaire") {
+		const lines = response.questionnaireDetails.map((d) => {
+			let line = `- ${d.question}: ${d.answer}`;
+			if (d.comment) line += ` (comment: ${d.comment})`;
+			return line;
+		});
+		const body = `User answered questionnaire:\n${lines.join("\n")}`;
+		return appendComments(body, response.additionalComments);
+	}
+
+	const sel = response.selections;
+	let base: string;
+	if (sel.length === 1) {
+		base = `User selected: ${sel[0]}`;
+	} else {
+		base = `User selected: ${sel.join(", ")}`;
+	}
+	const withComment = response.comment
+		? `${base}\nComment: ${response.comment}`
+		: base;
+	return appendComments(withComment, response.additionalComments);
+}
+
+function appendComments(body: string, additional?: string): string {
+	if (!additional?.trim()) return body;
+	return `${body}\nAdditional comments: ${additional.trim()}`;
+}
+
+export function optionTitlesForDetails(
+	validated: ValidatedAskParams,
+): string[] {
+	if (validated.mode === "questionnaire") {
+		return validated.questions.map((q) => q.title);
+	}
+	return validated.options.map((o) => o.title);
+}
+
+export function toToolDetails(
+	validated: ValidatedAskParams,
+	response: AskResponse | null,
+	cancelled: boolean,
+	ui_backend: UiBackend,
+	opts?: { ui_degraded?: boolean; non_interactive_blocked?: boolean },
+): AskToolDetails {
+	return {
+		question: validated.question,
+		context: validated.context,
+		contextFormat: validated.contextFormat,
+		options: optionTitlesForDetails(validated),
+		response,
+		cancelled,
+		ui_backend,
+		ui_degraded: opts?.ui_degraded,
+		non_interactive_blocked: opts?.non_interactive_blocked,
+	};
+}

package/.pi/lib/ask-user/glimpseui.d.ts

@@ -0,0 +1,10 @@
+declare module "glimpseui" {
+	export function prompt(
+		html: string,
+		windowOptions?: {
+			width?: number;
+			height?: number;
+			title?: string;
+		},
+	): Promise<Record<string, unknown> | null>;
+}

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

@@ -0,0 +1,114 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { formatResultText, toToolDetails } from "./format.js";
+import {
+	isHarnessNonInteractive,
+	isPlanApprovalAskUser,
+	nonInteractiveAskUserResult,
+} from "./policy.js";
+import { presentAskUser } from "./presenters/select.js";
+import type { AskUserParams, RunAskUserResult } from "./types.js";
+import { validateAskParams } from "./validate.js";
+
+export { buildGlimpsePayload } from "./contracts/glimpse-payload-build.js";
+export { formatResultText, toToolDetails } from "./format.js";
+export { applyAskUserToTaskClarification } from "./merge-task-clarification.js";
+export {
+	assertSubagentCannotAskUser,
+	isHarnessNonInteractive,
+	isPlanApprovalAskUser,
+	nonInteractiveAskUserResult,
+	PLAN_APPROVE_OPTION,
+	PLAN_CANCEL_OPTION,
+} from "./policy.js";
+export {
+	glimpseHealthCheck,
+	isGlimpseAvailable,
+} from "./presenters/glimpse.js";
+export {
+	AskUserParamsSchema,
+	PROMPT_GUIDELINES,
+	PROMPT_SNIPPET,
+} from "./schema.js";
+export type {
+	AskResponse,
+	AskToolDetails,
+	AskUserParams,
+	DialogResult,
+	ValidatedAskParams,
+} from "./types.js";
+export { normalizeOption, validateAskParams } from "./validate.js";
+
+export interface RunAskUserContext {
+	ui: ExtensionUIContext;
+	hasUI: boolean;
+	sessionName?: string;
+}
+
+export async function runAskUser(
+	params: AskUserParams,
+	ctx: RunAskUserContext,
+): Promise<
+	| RunAskUserResult
+	| { error: string; details: Partial<import("./types.js").AskToolDetails> }
+> {
+	if (isPlanApprovalAskUser(params)) {
+		return {
+			error:
+				"ask_user must not be used for plan approval — call approve_plan with the PlanPacket.",
+			details: {
+				question: params.question ?? "",
+				options: [],
+				response: null,
+				cancelled: true,
+				ui_backend: "headless",
+			},
+		};
+	}
+
+	if (isHarnessNonInteractive()) {
+		const blocked = nonInteractiveAskUserResult(params.question ?? "");
+		return {
+			error: blocked.text,
+			details: blocked.details as import("./types.js").AskToolDetails,
+		};
+	}
+
+	const validated = validateAskParams(params);
+	if (typeof validated === "string") {
+		return {
+			error: validated,
+			details: {
+				question: params.question ?? "",
+				options: [],
+				response: null,
+				cancelled: true,
+				ui_backend: "headless",
+			},
+		};
+	}
+
+	const outcome = await presentAskUser(validated, {
+		ui: ctx.ui,
+		hasUI: ctx.hasUI,
+		sessionName: ctx.sessionName,
+	});
+
+	const details = toToolDetails(
+		validated,
+		outcome.response,
+		outcome.cancelled,
+		outcome.ui_backend,
+		{
+			ui_degraded: outcome.ui_degraded,
+		},
+	);
+
+	const text = formatResultText(outcome.response, outcome.cancelled, {
+		ui_degraded: outcome.ui_degraded,
+	});
+
+	return {
+		content: [{ type: "text", text }],
+		details,
+	};
+}

package/.pi/lib/ask-user/merge-task-clarification.ts

@@ -0,0 +1,98 @@
+import type { AskToolDetails } from "./types.js";
+
+export type TaskClarificationDoc = Record<string, unknown>;
+
+const TITLE_ALIASES: Record<string, string[]> = {
+	success_definition: [
+		"done",
+		"success",
+		"success criteria",
+		"what does done look like",
+	],
+	risk_level: ["risk", "risk level"],
+	in_scope: ["scope", "in scope", "what is in scope"],
+};
+
+function normalizeKey(s: string): string {
+	return s
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim();
+}
+
+function matchField(title: string): string | null {
+	const n = normalizeKey(title);
+	for (const [field, aliases] of Object.entries(TITLE_ALIASES)) {
+		if (aliases.some((a) => n.includes(normalizeKey(a)))) return field;
+	}
+	return null;
+}
+
+function parseRiskLevel(answer: string): "low" | "med" | "high" | null {
+	const n = answer.toLowerCase();
+	if (/\blow\b/.test(n)) return "low";
+	if (/\bhigh\b/.test(n)) return "high";
+	if (/\bmed/.test(n) || /\bmedium\b/.test(n)) return "med";
+	return null;
+}
+
+/**
+ * Merge ask_user questionnaire or flat answers into a task-clarification draft.
+ */
+export function applyAskUserToTaskClarification(
+	doc: TaskClarificationDoc,
+	details: AskToolDetails,
+): TaskClarificationDoc {
+	const next = { ...doc };
+	const assumptions = Array.isArray(next.assumptions)
+		? [...(next.assumptions as string[])]
+		: [];
+
+	if (!details.response || details.cancelled) {
+		return next;
+	}
+
+	const applyPair = (question: string, answer: string) => {
+		const field = matchField(question);
+		if (field === "success_definition") {
+			next.success_definition = answer;
+			return;
+		}
+		if (field === "risk_level") {
+			const risk = parseRiskLevel(answer);
+			if (risk) next.risk_level = risk;
+			return;
+		}
+		if (field === "in_scope") {
+			const items = answer
+				.split(/[,;\n]/)
+				.map((s) => s.trim())
+				.filter(Boolean);
+			if (items.length) next.in_scope = items;
+			return;
+		}
+		assumptions.push(`${question}: ${answer}`);
+	};
+
+	const r = details.response;
+	if (r.kind === "questionnaire") {
+		for (const d of r.questionnaireDetails) {
+			applyPair(d.question, d.answer);
+		}
+	} else if (r.kind === "freeform") {
+		applyPair(details.question, r.text);
+	} else if (r.kind === "selection") {
+		applyPair(details.question, r.selections.join(", "));
+	}
+
+	if (assumptions.length) next.assumptions = assumptions;
+
+	if (Array.isArray(next.unresolved_questions)) {
+		next.unresolved_questions = [];
+	}
+	if (next.status === "draft" || next.status === "needs_user") {
+		next.status = "needs_user";
+	}
+
+	return next;
+}