ultimate-pi 0.20.0 → 0.22.0

package/.pi/lib/ask-user/policy.mjs

@@ -0,0 +1,43 @@
+/** @sync .pi/lib/ask-user/policy.ts — test / node entrypoint */
+
+export const PLAN_APPROVE_OPTION =
+	/^(approve(d)?(\s+plan)?|yes,?\s+proceed|looks\s+good)$/i;
+export const PLAN_CANCEL_OPTION =
+	/^(cancel(led)?|revise|request\s+changes|needs?\s+clarification)$/i;
+
+const PLAN_APPROVAL_PHRASE = /plan|approve/i;
+
+function optionTitlesFromParams(input) {
+	const titles = [];
+	for (const o of input.options ?? []) {
+		if (typeof o === "string") titles.push(o.trim());
+		else if (o && typeof o === "object" && "title" in o) {
+			titles.push(String(o.title ?? "").trim());
+		}
+	}
+	for (const q of input.questions ?? []) {
+		if (q && typeof q === "object" && "title" in q) {
+			titles.push(String(q.title ?? "").trim());
+		}
+		if (q && typeof q === "object" && "options" in q) {
+			for (const o of q.options ?? []) {
+				if (typeof o === "string") titles.push(o.trim());
+				else if (o && typeof o === "object" && "title" in o) {
+					titles.push(String(o.title ?? "").trim());
+				}
+			}
+		}
+	}
+	return titles.filter(Boolean);
+}
+
+export function isPlanApprovalAskUser(input) {
+	const q = String(input.question ?? "").trim();
+	const titles = optionTitlesFromParams(input);
+	const hasPlanOptions =
+		titles.some(
+			(t) => PLAN_APPROVE_OPTION.test(t) || PLAN_CANCEL_OPTION.test(t),
+		) || PLAN_APPROVE_OPTION.test(q);
+	if (!hasPlanOptions) return false;
+	return PLAN_APPROVAL_PHRASE.test(q);
+}

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

@@ -0,0 +1,104 @@
+import type { AskUserParams } from "./types.js";
+
+/** Match plan-approval option labels — keep in sync with plan-approval/types. */
+export const PLAN_APPROVE_OPTION =
+	/^(approve(d)?(\s+plan)?|yes,?\s+proceed|looks\s+good)$/i;
+export const PLAN_CANCEL_OPTION =
+	/^(cancel(led)?|revise|request\s+changes|needs?\s+clarification)$/i;
+
+const PLAN_APPROVAL_PHRASE = /plan|approve/i;
+
+function optionTitlesFromParams(input: {
+	options?: unknown[];
+	questions?: unknown[];
+}): string[] {
+	const titles: string[] = [];
+	for (const o of input.options ?? []) {
+		if (typeof o === "string") titles.push(o.trim());
+		else if (o && typeof o === "object" && "title" in o) {
+			titles.push(String((o as { title?: string }).title ?? "").trim());
+		}
+	}
+	for (const q of input.questions ?? []) {
+		if (q && typeof q === "object" && "title" in q) {
+			titles.push(String((q as { title?: string }).title ?? "").trim());
+		}
+		if (q && typeof q === "object" && "options" in q) {
+			const qOpts = (q as { options?: unknown[] }).options ?? [];
+			for (const o of qOpts) {
+				if (typeof o === "string") titles.push(o.trim());
+				else if (o && typeof o === "object" && "title" in o) {
+					titles.push(String((o as { title?: string }).title ?? "").trim());
+				}
+			}
+		}
+	}
+	return titles.filter(Boolean);
+}
+
+/** Detect ask_user calls that duplicate plan approval (must use approve_plan). */
+export function isPlanApprovalAskUser(input: {
+	question?: string;
+	options?: unknown[];
+	questions?: unknown[];
+}): boolean {
+	const q = String(input.question ?? "").trim();
+	const titles = optionTitlesFromParams(input);
+	const hasPlanOptions =
+		titles.some(
+			(t) => PLAN_APPROVE_OPTION.test(t) || PLAN_CANCEL_OPTION.test(t),
+		) || PLAN_APPROVE_OPTION.test(q);
+	if (!hasPlanOptions) return false;
+	return PLAN_APPROVAL_PHRASE.test(q);
+}
+
+/** True when harness setup/CI forbids interactive prompts. */
+export function isHarnessNonInteractive(): boolean {
+	return (
+		process.env.HARNESS_NON_INTERACTIVE === "1" ||
+		process.argv.some((a) => a.includes("non-interactive"))
+	);
+}
+
+export function assertSubagentCannotAskUser(agentType: string | undefined): {
+	blocked: boolean;
+	reason?: string;
+} {
+	if (!agentType) return { blocked: false };
+	if (agentType.startsWith("harness/reviewing/")) {
+		return {
+			blocked: true,
+			reason: `Tool "ask_user" is not available for ${agentType} (orchestrator-only).`,
+		};
+	}
+	if (agentType.startsWith("harness/planning/")) {
+		return {
+			blocked: true,
+			reason: `Tool "ask_user" is not available for ${agentType} (orchestrator-only).`,
+		};
+	}
+	if (agentType === "harness/running/executor") {
+		return {
+			blocked: true,
+			reason: `Tool "ask_user" is not available for ${agentType} (orchestrator-only).`,
+		};
+	}
+	return { blocked: false };
+}
+
+export function nonInteractiveAskUserResult(question: string): {
+	text: string;
+	details: Partial<import("./types.js").AskToolDetails>;
+} {
+	return {
+		text: "ask_user blocked in non-interactive mode — set needs_clarification; do not guess defaults.",
+		details: {
+			question,
+			options: [],
+			response: null,
+			cancelled: true,
+			ui_backend: "headless",
+			non_interactive_blocked: true,
+		},
+	};
+}

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

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { parseGlimpseRawResult } from "../contracts/glimpse-parse.js";
+import { buildGlimpsePayload } from "../contracts/glimpse-payload-build.js";
+import type { DialogResult, ValidatedAskParams } from "../types.js";
+import type { PresenterContext } from "./types.js";
+
+function glimpsePackageJson(): string {
+	const roots = [process.env.UP_PKG, process.cwd()].filter((r): r is string =>
+		Boolean(r),
+	);
+	for (const root of roots) {
+		const pkgJson = join(
+			root,
+			".pi/npm/node_modules/@alexleekt/pi-ask-user-glimpse/package.json",
+		);
+		try {
+			return createRequire(pkgJson).resolve(
+				"@alexleekt/pi-ask-user-glimpse/package.json",
+			);
+		} catch {
+			// try next root
+		}
+	}
+	throw new Error(
+		"@alexleekt/pi-ask-user-glimpse not installed — run npm install in .pi/npm",
+	);
+}
+
+const require = createRequire(glimpsePackageJson());
+
+let warnedUnavailable = false;
+
+function resolveWebviewHtml(): string {
+	const pkgRoot = dirname(
+		require.resolve("@alexleekt/pi-ask-user-glimpse/package.json"),
+	);
+	const distPath = join(pkgRoot, "dist", "index.html");
+	const html = readFileSync(distPath, "utf-8");
+	if (!html.includes("/*ASK_USER_PAYLOAD*/")) {
+		throw new Error(
+			"@alexleekt/pi-ask-user-glimpse dist/index.html missing ASK_USER_PAYLOAD placeholder",
+		);
+	}
+	return html;
+}
+
+export function isGlimpseAvailable(): boolean {
+	try {
+		resolveWebviewHtml();
+		require.resolve("glimpseui");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function summarizeTitle(question: string, maxWords = 3): string {
+	const words = question.trim().split(/\s+/).slice(0, maxWords);
+	const title = words.join(" ");
+	return title.length < question.length ? `${title}…` : title;
+}
+
+export async function runGlimpsePresenter(
+	validated: ValidatedAskParams,
+	ctx: PresenterContext,
+): Promise<DialogResult> {
+	const payload = buildGlimpsePayload(validated, ctx.sessionName);
+	const baseHtml = resolveWebviewHtml();
+	const html = baseHtml.replace(
+		"/*ASK_USER_PAYLOAD*/",
+		JSON.stringify(payload)
+			.replace(/</g, "\\u003c")
+			.replace(/>/g, "\\u003e")
+			.replace(/&/g, "\\u0026"),
+	);
+
+	const sessionName = ctx.sessionName;
+	const questionTitle = summarizeTitle(validated.question);
+	const title = sessionName
+		? `Pi · ${sessionName} · ${questionTitle}`
+		: `Pi · ${questionTitle}`;
+
+	const windowOptions = {
+		width: 1200,
+		height: 900,
+		title: title.length > 60 ? `${title.slice(0, 57)}…` : title,
+	};
+
+	try {
+		const { prompt } = await import("glimpseui");
+		const raw = (await prompt(html, windowOptions)) as Record<
+			string,
+			unknown
+		> | null;
+
+		const cancelled = raw === null || raw?.__cancelled === true;
+		const response = parseGlimpseRawResult(raw, cancelled);
+
+		return {
+			response,
+			cancelled,
+			ui_backend: "glimpse",
+		};
+	} catch (err) {
+		if (!warnedUnavailable) {
+			warnedUnavailable = true;
+			console.warn(
+				"[harness-ask-user] Glimpse unavailable:",
+				err instanceof Error ? err.message : err,
+			);
+		}
+		throw err;
+	}
+}
+
+/** Probe glimpse without opening a dialog. */
+export function glimpseHealthCheck(): { ok: boolean; error?: string } {
+	try {
+		resolveWebviewHtml();
+		require.resolve("glimpseui");
+		return { ok: true };
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e),
+		};
+	}
+}

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

@@ -0,0 +1,131 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { FREEFORM_OPTION_TITLE } from "../constants.js";
+import {
+	detailFromFlatResult,
+	mergeQuestionnaireResults,
+	questionToFlatParams,
+} from "../core/questionnaire.js";
+import type { DialogResult, ValidatedAskParams } from "../types.js";
+
+async function runFlatHeadless(
+	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, ui_backend: "headless" };
+		}
+		const text = await ui.input(title, "");
+		if (!text?.trim()) {
+			return { response: null, cancelled: true, ui_backend: "headless" };
+		}
+		return {
+			response: { kind: "freeform", text: text.trim() },
+			cancelled: false,
+			ui_backend: "headless",
+		};
+	}
+
+	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, ui_backend: "headless" };
+			}
+			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, ui_backend: "headless" };
+		}
+		return {
+			response: { kind: "selection", selections },
+			cancelled: false,
+			ui_backend: "headless",
+		};
+	}
+
+	const choices = allowFreeform ? [...labels, FREEFORM_OPTION_TITLE] : labels;
+	const picked = await ui.select(title, choices);
+	if (!picked) {
+		return { response: null, cancelled: true, ui_backend: "headless" };
+	}
+
+	if (picked === FREEFORM_OPTION_TITLE) {
+		const text = await ui.input(question, "");
+		if (!text?.trim()) {
+			return { response: null, cancelled: true, ui_backend: "headless" };
+		}
+		return {
+			response: { kind: "freeform", text: text.trim() },
+			cancelled: false,
+			ui_backend: "headless",
+		};
+	}
+
+	return {
+		response: { kind: "selection", selections: [picked] },
+		cancelled: false,
+		ui_backend: "headless",
+	};
+}
+
+async function runQuestionnaireHeadless(
+	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 runFlatHeadless(ui, flat);
+		last = step;
+		if (step.cancelled) {
+			return { response: null, cancelled: true, ui_backend: "headless" };
+		}
+		const label = q.description ?? q.title;
+		const detail = detailFromFlatResult(label, step);
+		if (!detail) {
+			if (!validated.allowSkip) {
+				return { response: null, cancelled: true, ui_backend: "headless" };
+			}
+			continue;
+		}
+		details.push(detail);
+	}
+
+	return mergeQuestionnaireResults(details, last);
+}
+
+export async function runHeadlessPresenter(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+): Promise<DialogResult> {
+	if (validated.mode === "questionnaire") {
+		return runQuestionnaireHeadless(ui, validated);
+	}
+	return runFlatHeadless(ui, validated);
+}
+
+/** @deprecated Use runHeadlessPresenter */
+export const runAskFallback = runHeadlessPresenter;

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

@@ -0,0 +1,60 @@
+import type { DialogResult, UiBackend, ValidatedAskParams } from "../types.js";
+import { isGlimpseAvailable, runGlimpsePresenter } from "./glimpse.js";
+import { runHeadlessPresenter } from "./headless.js";
+import { runTuiPresenter } from "./tui.js";
+import type { PresenterContext } from "./types.js";
+
+export type PresenterChoice = UiBackend;
+
+export function resolvePresenterChoice(
+	validated: ValidatedAskParams,
+	hasUI: boolean,
+): PresenterChoice {
+	if (validated.displayMode === "inline") return "tui";
+
+	const forced = process.env.HARNESS_ASK_USER_UI?.toLowerCase();
+	if (forced === "tui") return "tui";
+	if (forced === "glimpse") return "glimpse";
+	if (forced === "headless") return "headless";
+
+	if (hasUI && isGlimpseAvailable()) return "glimpse";
+	if (hasUI) return "tui";
+	return "headless";
+}
+
+async function runPresenter(
+	choice: PresenterChoice,
+	validated: ValidatedAskParams,
+	ctx: PresenterContext,
+): Promise<DialogResult> {
+	switch (choice) {
+		case "glimpse":
+			return runGlimpsePresenter(validated, ctx);
+		case "headless":
+			return runHeadlessPresenter(ctx.ui, validated);
+		default:
+			return runTuiPresenter(ctx.ui, validated);
+	}
+}
+
+/**
+ * Run ask_user UI with glimpse→tui degradation on failure.
+ */
+export async function presentAskUser(
+	validated: ValidatedAskParams,
+	ctx: PresenterContext,
+): Promise<DialogResult> {
+	let choice = resolvePresenterChoice(validated, ctx.hasUI);
+
+	if (choice === "glimpse") {
+		try {
+			return await runPresenter("glimpse", validated, ctx);
+		} catch {
+			choice = "tui";
+			const outcome = await runPresenter("tui", validated, ctx);
+			return { ...outcome, ui_degraded: true };
+		}
+	}
+
+	return runPresenter(choice, validated, ctx);
+}