ultimate-pi 0.3.1 → 0.4.0

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

@@ -0,0 +1,260 @@
+import type { ExtensionUIContext } from "@mariozechner/pi-coding-agent";
+import {
+	Editor,
+	type EditorTheme,
+	Key,
+	matchesKey,
+	truncateToWidth,
+} from "@mariozechner/pi-tui";
+import type { AskResponse, DialogResult, ValidatedAskParams } from "./types.js";
+
+type DisplayOption = {
+	title: string;
+	description?: string;
+	isFreeform?: boolean;
+};
+
+interface CustomAnswer {
+	response: AskResponse;
+}
+
+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);
+		}),
+	]);
+}
+
+export async function runAskDialog(
+	ui: ExtensionUIContext,
+	validated: ValidatedAskParams,
+): Promise<DialogResult> {
+	const { question, context, options, allowMultiple, allowFreeform } =
+		validated;
+
+	const displayOptions: DisplayOption[] = [...options];
+	if (allowFreeform) {
+		displayOptions.push({
+			title: "Type something…",
+			isFreeform: true,
+		});
+	}
+
+	// Freeform-only: no listed options
+	if (displayOptions.length === 0) {
+		const text = await ui.input(question, "");
+		if (!text?.trim()) {
+			return { response: null, cancelled: true };
+		}
+		return {
+			response: { kind: "freeform", text: text.trim() },
+			cancelled: false,
+		};
+	}
+
+	const result = await withTimeout(
+		ui.custom<CustomAnswer | null>((tui, theme, _kb, done) => {
+			let optionIndex = 0;
+			let editMode = false;
+			const selected = new Set<number>();
+			let cachedLines: string[] | undefined;
+
+			const editorTheme: EditorTheme = {
+				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),
+				},
+			};
+			const editor = new Editor(tui, editorTheme);
+
+			editor.onSubmit = (value) => {
+				const trimmed = value.trim();
+				if (trimmed) {
+					done({ response: { kind: "freeform", text: trimmed } });
+				} else {
+					editMode = false;
+					editor.setText("");
+					refresh();
+				}
+			};
+
+			function refresh() {
+				cachedLines = undefined;
+				tui.requestRender();
+			}
+
+			function submitSelection() {
+				if (allowMultiple) {
+					const titles = [...selected]
+						.sort((a, b) => a - b)
+						.map((i) => displayOptions[i].title)
+						.filter((t) => t !== "Type something…");
+					if (titles.length === 0) return;
+					done({ response: { kind: "selection", selections: titles } });
+					return;
+				}
+				const opt = displayOptions[optionIndex];
+				if (opt.isFreeform) {
+					editMode = true;
+					refresh();
+					return;
+				}
+				done({
+					response: { kind: "selection", selections: [opt.title] },
+				});
+			}
+
+			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(displayOptions.length - 1, optionIndex + 1);
+					refresh();
+					return;
+				}
+
+				if (allowMultiple && matchesKey(data, Key.space)) {
+					const opt = displayOptions[optionIndex];
+					if (!opt.isFreeform) {
+						if (selected.has(optionIndex)) {
+							selected.delete(optionIndex);
+						} else {
+							selected.add(optionIndex);
+						}
+						refresh();
+					}
+					return;
+				}
+
+				if (matchesKey(data, Key.enter)) {
+					submitSelection();
+					return;
+				}
+
+				if (matchesKey(data, Key.escape)) {
+					done(null);
+				}
+			}
+
+			function render(width: number): string[] {
+				if (cachedLines) return cachedLines;
+
+				const lines: string[] = [];
+				const add = (s: string) => lines.push(truncateToWidth(s, width));
+				const useOverlay = validated.displayMode !== "inline";
+
+				if (useOverlay) {
+					add(theme.fg("accent", "─".repeat(width)));
+				}
+
+				if (context) {
+					for (const line of context.split("\n")) {
+						add(theme.fg("muted", ` ${line}`));
+					}
+					lines.push("");
+				}
+
+				add(theme.fg("text", ` ${question}`));
+				lines.push("");
+
+				for (let i = 0; i < displayOptions.length; i++) {
+					const opt = displayOptions[i];
+					const isFreeform = opt.isFreeform === true;
+					const focused = i === optionIndex;
+					const checked = selected.has(i);
+					let prefix = "  ";
+					if (allowMultiple && !isFreeform) {
+						prefix = checked ? theme.fg("accent", "[x] ") : "[ ] ";
+					} else if (focused) {
+						prefix = theme.fg("accent", "> ");
+					}
+
+					const num = `${i + 1}. `;
+					const label = opt.title;
+					if (isFreeform && editMode && focused) {
+						add(prefix + theme.fg("accent", `${num}${label} ✎`));
+					} else if (focused && !allowMultiple) {
+						add(prefix + theme.fg("accent", `${num}${label}`));
+					} else {
+						add(`${prefix}${theme.fg("text", `${num}${label}`)}`);
+					}
+
+					if (opt.description) {
+						add(`     ${theme.fg("muted", opt.description)}`);
+					}
+				}
+
+				if (editMode) {
+					lines.push("");
+					add(theme.fg("muted", " Your answer:"));
+					for (const line of editor.render(width - 2)) {
+						add(` ${line}`);
+					}
+				}
+
+				lines.push("");
+				if (editMode) {
+					add(theme.fg("dim", " Enter to submit • Esc to go back"));
+				} else if (allowMultiple) {
+					add(
+						theme.fg(
+							"dim",
+							" ↑↓ navigate • Space toggle • Enter confirm • Esc cancel",
+						),
+					);
+				} else {
+					add(
+						theme.fg("dim", " ↑↓ navigate • Enter to select • Esc to cancel"),
+					);
+				}
+
+				if (useOverlay) {
+					add(theme.fg("accent", "─".repeat(width)));
+				}
+
+				cachedLines = lines;
+				return lines;
+			}
+
+			return {
+				render,
+				invalidate: () => {
+					cachedLines = undefined;
+				},
+				handleInput,
+			};
+		}),
+		validated.timeout,
+	);
+
+	if (!result) {
+		return { response: null, cancelled: true };
+	}
+
+	return { response: result.response, cancelled: false };
+}

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

@@ -0,0 +1,78 @@
+import type { ExtensionUIContext } from "@mariozechner/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,
+	};
+}

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

@@ -0,0 +1,66 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type {
+	Theme,
+	ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import type { AskToolDetails } from "./types.js";
+
+export function renderAskCall(
+	args: Record<string, unknown>,
+	theme: Theme,
+): Text {
+	let text =
+		theme.fg("toolTitle", theme.bold("ask_user ")) +
+		theme.fg("muted", String(args.question ?? ""));
+	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…`);
+		}
+		text += `\n${theme.fg("dim", `  Options: ${numbered.join(", ")}`)}`;
+	}
+	return new Text(text, 0, 0);
+}
+
+export function renderAskResult(
+	result: AgentToolResult<unknown>,
+	_options: ToolRenderResultOptions,
+	theme: Theme,
+): Text {
+	const details = result.details as AskToolDetails | undefined;
+	if (!details) {
+		const block = result.content[0];
+		return new Text(block?.type === "text" ? block.text : "", 0, 0);
+	}
+
+	if (details.cancelled || !details.response) {
+		return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+	}
+
+	if (details.response.kind === "freeform") {
+		return new Text(
+			theme.fg("success", "✓ ") +
+				theme.fg("muted", "(wrote) ") +
+				theme.fg("accent", details.response.text),
+			0,
+			0,
+		);
+	}
+
+	const sel = details.response.selections;
+	const display =
+		sel.length === 1 ? sel[0] : sel.map((s, i) => `${i + 1}. ${s}`).join(", ");
+	return new Text(
+		theme.fg("success", "✓ ") + theme.fg("accent", display),
+		0,
+		0,
+	);
+}

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

@@ -0,0 +1,69 @@
+import { type TUnsafe, Type } from "@sinclair/typebox";
+
+/** Google-safe string enum (flat enum, not Type.Union of literals). */
+function StringEnum<T extends string[]>(
+	values: T,
+	options?: { description?: string },
+): TUnsafe<T[number]> {
+	return Type.Unsafe({
+		type: "string",
+		enum: [...values],
+		...(options?.description ? { description: options.description } : {}),
+	});
+}
+
+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" }),
+		),
+	}),
+]);
+
+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" }),
+	),
+	options: Type.Optional(
+		Type.Array(OptionSchema, {
+			description: "Multiple-choice options (min 2 if provided)",
+		}),
+	),
+	allowMultiple: Type.Optional(
+		Type.Boolean({
+			description: "Allow selecting more than one option (Space to toggle)",
+			default: false,
+		}),
+	),
+	allowFreeform: Type.Optional(
+		Type.Boolean({
+			description: 'Append "Type something…" freeform row',
+			default: true,
+		}),
+	),
+	displayMode: Type.Optional(
+		StringEnum(["overlay", "inline"] as const, {
+			description: "overlay = modal (default), inline = in transcript flow",
+		}),
+	),
+	timeout: Type.Optional(
+		Type.Number({
+			description: "Auto-cancel after N milliseconds",
+			minimum: 1,
+		}),
+	),
+});
+
+export const PROMPT_SNIPPET =
+	"Structured user input for ambiguous or high-impact harness decisions";
+
+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.",
+	"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.",
+];

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

@@ -0,0 +1,41 @@
+export interface NormalizedOption {
+	title: string;
+	description?: string;
+}
+
+export type AskResponse =
+	| { kind: "selection"; selections: string[] }
+	| { kind: "freeform"; text: string };
+
+export interface AskToolDetails {
+	question: string;
+	context?: string;
+	options: string[];
+	response: AskResponse | null;
+	cancelled: boolean;
+}
+
+export interface AskUserParams {
+	question: string;
+	context?: string;
+	options?: Array<string | { title: string; description?: string }>;
+	allowMultiple?: boolean;
+	allowFreeform?: boolean;
+	displayMode?: "overlay" | "inline";
+	timeout?: number;
+}
+
+export interface ValidatedAskParams {
+	question: string;
+	context?: string;
+	options: NormalizedOption[];
+	allowMultiple: boolean;
+	allowFreeform: boolean;
+	displayMode: "overlay" | "inline";
+	timeout?: number;
+}
+
+export interface DialogResult {
+	response: AskResponse | null;
+	cancelled: boolean;
+}

package/.pi/extensions/lib/ask-user/validate-core.mjs

@@ -0,0 +1,79 @@
+/** Keep in sync with validate.ts — test entrypoint for node --test */
+
+/**
+ * @param {string | { title: string, description?: string }} raw
+ */
+export function normalizeOption(raw) {
+	if (typeof raw === "string") {
+		return { title: raw.trim() };
+	}
+	return {
+		title: raw.title.trim(),
+		description: raw.description?.trim() || undefined,
+	};
+}
+
+/** @param {import('./types.js').AskUserParams} params */
+export function validateAskParams(params) {
+	const question = params.question?.trim();
+	if (!question) {
+		return "ask_user: question is required";
+	}
+
+	const options = (params.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return "ask_user: provide at least 2 options, or omit options for freeform-only";
+	}
+
+	const allowFreeform = params.allowFreeform !== false;
+	if (options.length === 0 && !allowFreeform) {
+		return "ask_user: options required when allowFreeform is false";
+	}
+
+	const displayMode =
+		process.env.HARNESS_ASK_USER_DISPLAY_MODE === "inline"
+			? "inline"
+			: params.displayMode === "inline"
+				? "inline"
+				: "overlay";
+
+	return {
+		question,
+		context: params.context?.trim() || undefined,
+		options,
+		allowMultiple: params.allowMultiple === true,
+		allowFreeform,
+		displayMode,
+		timeout:
+			typeof params.timeout === "number" && params.timeout > 0
+				? params.timeout
+				: undefined,
+	};
+}
+
+/** @param {import('./types.js').AskResponse | null} response @param {boolean} cancelled */
+export function formatResultText(response, cancelled) {
+	if (cancelled || !response) {
+		return "User cancelled (no answer)";
+	}
+	if (response.kind === "freeform") {
+		return `User wrote: ${response.text}`;
+	}
+	if (response.selections.length === 1) {
+		return `User selected: ${response.selections[0]}`;
+	}
+	return `User selected: ${response.selections.join(", ")}`;
+}
+
+/** @param {import('./types.js').ValidatedAskParams} validated */
+export function toToolDetails(validated, response, cancelled) {
+	return {
+		question: validated.question,
+		context: validated.context,
+		options: validated.options.map((o) => o.title),
+		response,
+		cancelled,
+	};
+}

package/.pi/extensions/lib/ask-user/validate.ts

@@ -0,0 +1,92 @@
+import type {
+	AskResponse,
+	AskToolDetails,
+	AskUserParams,
+	NormalizedOption,
+	ValidatedAskParams,
+} from "./types.js";
+
+export type { ValidatedAskParams };
+
+export function normalizeOption(
+	raw: string | { title: string; description?: string },
+): NormalizedOption {
+	if (typeof raw === "string") {
+		return { title: raw.trim() };
+	}
+	return {
+		title: raw.title.trim(),
+		description: raw.description?.trim() || undefined,
+	};
+}
+
+export function validateAskParams(
+	params: AskUserParams,
+): ValidatedAskParams | string {
+	const question = params.question?.trim();
+	if (!question) {
+		return "ask_user: question is required";
+	}
+
+	const options = (params.options ?? [])
+		.map(normalizeOption)
+		.filter((o) => o.title);
+	if (options.length > 0 && options.length < 2) {
+		return "ask_user: provide at least 2 options, or omit options for freeform-only";
+	}
+
+	const allowFreeform = params.allowFreeform !== false;
+	if (options.length === 0 && !allowFreeform) {
+		return "ask_user: options required when allowFreeform is false";
+	}
+
+	const displayMode =
+		process.env.HARNESS_ASK_USER_DISPLAY_MODE === "inline"
+			? "inline"
+			: params.displayMode === "inline"
+				? "inline"
+				: "overlay";
+
+	return {
+		question,
+		context: params.context?.trim() || undefined,
+		options,
+		allowMultiple: params.allowMultiple === true,
+		allowFreeform,
+		displayMode,
+		timeout:
+			typeof params.timeout === "number" && params.timeout > 0
+				? params.timeout
+				: undefined,
+	};
+}
+
+export function formatResultText(
+	response: AskResponse | null,
+	cancelled: boolean,
+): string {
+	if (cancelled || !response) {
+		return "User cancelled (no answer)";
+	}
+	if (response.kind === "freeform") {
+		return `User wrote: ${response.text}`;
+	}
+	if (response.selections.length === 1) {
+		return `User selected: ${response.selections[0]}`;
+	}
+	return `User selected: ${response.selections.join(", ")}`;
+}
+
+export function toToolDetails(
+	validated: ValidatedAskParams,
+	response: AskResponse | null,
+	cancelled: boolean,
+): AskToolDetails {
+	return {
+		question: validated.question,
+		context: validated.context,
+		options: validated.options.map((o) => o.title),
+		response,
+		cancelled,
+	};
+}