@milanglacier/pi-plan-mode 0.5.1

package/qna/scroll-select.ts

@@ -0,0 +1,353 @@
+import { requirePiTuiModule } from "./pi-tui-loader.js";
+
+let cachedPiTui:
+	| {
+			Key: {
+				enter: string;
+				escape: string;
+				up: string;
+				down: string;
+				ctrl: (key: string) => string;
+			};
+			matchesKey: (input: string, key: string) => boolean;
+			truncateToWidth: (text: string, width: number) => string;
+			visibleWidth: (text: string) => number;
+			wrapTextWithAnsi: (text: string, width: number) => string[];
+	  }
+	| undefined;
+
+function getPiTui() {
+	if (cachedPiTui) {
+		return cachedPiTui;
+	}
+
+	cachedPiTui = requirePiTuiModule() as {
+		Key: {
+			enter: string;
+			escape: string;
+			up: string;
+			down: string;
+			ctrl: (key: string) => string;
+		};
+		matchesKey: (input: string, key: string) => boolean;
+		truncateToWidth: (text: string, width: number) => string;
+		visibleWidth: (text: string) => number;
+		wrapTextWithAnsi: (text: string, width: number) => string[];
+	};
+	return cachedPiTui;
+}
+
+export interface ScrollSelectOption<T> {
+	value: T;
+	label: string;
+}
+
+export interface ScrollSelectSearchConfig<T> {
+	title: string;
+	placeholder?: string;
+	getOptions: (query: string) => Promise<ScrollSelectOption<T>[]> | ScrollSelectOption<T>[];
+	emptyMessage?: (query: string) => string;
+}
+
+export interface ScrollSelectConfig<T> {
+	title: string;
+	options: ScrollSelectOption<T>[];
+	footerHint?: string;
+	emptyMessage?: string;
+	initialValue?: T;
+	maxVisibleOptions?: number;
+	overlayWidth?: number | string;
+	overlayMaxHeight?: number | string;
+	search?: ScrollSelectSearchConfig<T>;
+}
+
+type ScrollSelectUi = {
+	custom?: <T>(
+		factory: (
+			tui: { requestRender: () => void },
+			theme: ScrollSelectTheme,
+			keybindings: unknown,
+			done: (value: T) => void,
+		) => {
+			render: (width: number) => string[];
+			handleInput: (data: string) => void;
+			dispose?: () => void;
+		},
+		options?: unknown,
+	) => Promise<T>;
+	select?: (title: string, options: string[]) => Promise<string | null | undefined>;
+	input?: (title: string, placeholder?: string) => Promise<string | null | undefined>;
+	notify?: (message: string, type?: "error" | "info" | "warning") => void;
+};
+
+type ScrollSelectTheme = {
+	fg: (color: string, text: string) => string;
+	bg?: (color: string, text: string) => string;
+	bold: (text: string) => string;
+};
+
+class ScrollSelectComponent<T> {
+	focused = false;
+
+	private readonly tui: { requestRender: () => void };
+	private readonly theme: ScrollSelectTheme;
+	private readonly done: (value: T | null) => void;
+	private readonly input: ScrollSelectUi["input"];
+	private readonly notify: ScrollSelectUi["notify"];
+	private readonly baseOptions: ScrollSelectOption<T>[];
+	private readonly title: string;
+	private readonly footerHint: string;
+	private readonly emptyMessage: string;
+	private readonly maxVisibleOptions: number;
+	private readonly search?: ScrollSelectSearchConfig<T>;
+
+	private options: ScrollSelectOption<T>[];
+	private cursorIndex: number;
+	private searchQuery = "";
+	private searching = false;
+
+	constructor(
+		config: ScrollSelectConfig<T>,
+		dependencies: {
+			tui: { requestRender: () => void };
+			theme: ScrollSelectTheme;
+			done: (value: T | null) => void;
+			input: ScrollSelectUi["input"];
+			notify: ScrollSelectUi["notify"];
+		},
+	) {
+		this.tui = dependencies.tui;
+		this.theme = dependencies.theme;
+		this.done = dependencies.done;
+		this.input = dependencies.input;
+		this.notify = dependencies.notify;
+		this.baseOptions = [...config.options];
+		this.options = [...config.options];
+		this.title = config.title;
+		this.footerHint = config.footerHint ?? "";
+		this.emptyMessage = config.emptyMessage ?? "No options available.";
+		this.maxVisibleOptions = Math.max(4, config.maxVisibleOptions ?? 10);
+		this.search = config.search;
+		this.cursorIndex = this.getInitialCursorIndex(config.initialValue);
+	}
+
+	render(width: number): string[] {
+		const { truncateToWidth, visibleWidth, wrapTextWithAnsi } = getPiTui();
+		const safeWidth = Math.max(20, width);
+		const contentWidth = Math.max(12, safeWidth - 2);
+		const lines: string[] = [];
+		const selectedLineIndexes = new Set<number>();
+
+		for (const line of this.title.split("\n")) {
+			for (const wrapped of wrapTextWithAnsi(line, contentWidth)) {
+				lines.push(truncateToWidth(wrapped, contentWidth));
+			}
+		}
+
+		lines.push("");
+
+		if (this.search) {
+			const filterText = this.searchQuery.trim().length > 0 ? `Filter: ${this.searchQuery}` : "Filter: all";
+			lines.push(truncateToWidth(this.theme.fg("dim", filterText), contentWidth));
+			lines.push("");
+		}
+
+		if (this.options.length === 0) {
+			lines.push(truncateToWidth(this.theme.fg("dim", this.emptyMessage), contentWidth));
+		} else {
+			const { start, end } = this.getVisibleRange();
+
+			if (start > 0) {
+				lines.push(truncateToWidth(this.theme.fg("dim", `↑ ${start} more`), contentWidth));
+			}
+
+			for (let index = start; index < end; index++) {
+				const option = this.options[index];
+				if (!option) {
+					continue;
+				}
+
+				const prefix = index === this.cursorIndex ? this.theme.fg("accent", "→ ") : "  ";
+				const availableWidth = Math.max(4, contentWidth - visibleWidth(prefix));
+				const label = truncateToWidth(option.label, availableWidth);
+				const line = `${prefix}${index === this.cursorIndex ? this.theme.fg("accent", label) : label}`;
+				lines.push(truncateToWidth(line, contentWidth));
+				if (index === this.cursorIndex) {
+					selectedLineIndexes.add(lines.length - 1);
+				}
+			}
+
+			const hiddenBelow = this.options.length - end;
+			if (hiddenBelow > 0) {
+				lines.push(truncateToWidth(this.theme.fg("dim", `↓ ${hiddenBelow} more`), contentWidth));
+			}
+		}
+
+		lines.push("");
+		lines.push(truncateToWidth(this.footerText(), contentWidth));
+		return lines.map((line, index) =>
+			this.renderSurfaceLine(line, contentWidth, {
+				selected: selectedLineIndexes.has(index),
+			}),
+		);
+	}
+
+	handleInput(data: string): void {
+		const { Key, matchesKey } = getPiTui();
+
+		if (matchesKey(data, Key.escape) || data === "q") {
+			this.done(null);
+			return;
+		}
+
+		if (matchesKey(data, Key.enter) || data === "\r") {
+			this.done(this.options[this.cursorIndex]?.value ?? null);
+			return;
+		}
+
+		if (matchesKey(data, Key.up) || data === "k" || matchesKey(data, Key.ctrl("p"))) {
+			this.moveCursor(-1);
+			return;
+		}
+
+		if (matchesKey(data, Key.down) || data === "j" || matchesKey(data, Key.ctrl("n"))) {
+			this.moveCursor(1);
+			return;
+		}
+
+		if (this.search && (data === "/" || data === "s")) {
+			void this.promptSearch();
+		}
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {}
+
+	private renderSurfaceLine(line: string, contentWidth: number, options: { selected?: boolean } = {}): string {
+		const { visibleWidth } = getPiTui();
+		const paddedLine = `${line}${" ".repeat(Math.max(0, contentWidth - visibleWidth(line)))}`;
+		const boxedLine = ` ${paddedLine} `;
+		if (typeof this.theme.bg !== "function") {
+			return boxedLine;
+		}
+		return this.theme.bg(options.selected ? "selectedBg" : "customMessageBg", boxedLine);
+	}
+
+	private footerText(): string {
+		const parts = ["[↑↓/j/k] scroll", "[enter] select", "[esc] cancel"];
+		if (this.search) {
+			parts.push("[/] search");
+		}
+		if (this.footerHint.trim().length > 0) {
+			parts.push(this.footerHint.trim());
+		}
+		return this.theme.fg("dim", parts.join(" • "));
+	}
+
+	private getInitialCursorIndex(initialValue: T | undefined): number {
+		if (initialValue === undefined) {
+			return 0;
+		}
+
+		const index = this.baseOptions.findIndex((option) => Object.is(option.value, initialValue));
+		return index >= 0 ? index : 0;
+	}
+
+	private getVisibleRange(): { start: number; end: number } {
+		const count = this.options.length;
+		const visible = Math.min(this.maxVisibleOptions, count);
+		if (count <= visible) {
+			return { start: 0, end: count };
+		}
+
+		let start = Math.max(0, this.cursorIndex - Math.floor(visible / 2));
+		start = Math.min(start, count - visible);
+		return { start, end: Math.min(count, start + visible) };
+	}
+
+	private moveCursor(delta: number): void {
+		if (this.options.length === 0) {
+			return;
+		}
+
+		this.cursorIndex = Math.max(0, Math.min(this.options.length - 1, this.cursorIndex + delta));
+		this.tui.requestRender();
+	}
+
+	private async promptSearch(): Promise<void> {
+		if (!this.search || typeof this.input !== "function" || this.searching) {
+			return;
+		}
+
+		this.searching = true;
+		try {
+			const raw = await this.input(this.search.title, this.searchQuery || this.search.placeholder);
+			if (raw === null || raw === undefined) {
+				return;
+			}
+
+			const query = raw.trim();
+			if (query === this.searchQuery) {
+				return;
+			}
+
+			const nextOptions = await this.search.getOptions(query);
+			if (nextOptions.length === 0) {
+				this.notify?.(
+					this.search.emptyMessage?.(query) ?? `No option matched ${query ? `"${query}"` : "the current filter"}.`,
+					"warning",
+				);
+				return;
+			}
+
+			this.searchQuery = query;
+			this.options = [...nextOptions];
+			this.cursorIndex = 0;
+			this.tui.requestRender();
+		} finally {
+			this.searching = false;
+		}
+	}
+}
+
+export async function openScrollableSelect<T>(ui: ScrollSelectUi, config: ScrollSelectConfig<T>): Promise<T | null> {
+	if (config.options.length === 0) {
+		return null;
+	}
+
+	if (config.options.length === 1) {
+		return config.options[0]?.value ?? null;
+	}
+
+	if (typeof ui.custom !== "function") {
+		if (typeof ui.select !== "function") {
+			return null;
+		}
+
+		const selected = await ui.select(
+			config.title,
+			config.options.map((option) => option.label),
+		);
+		return config.options.find((option) => option.label === selected)?.value ?? null;
+	}
+
+	return await ui.custom<T | null>(
+		(tui, theme, _keybindings, done) =>
+			new ScrollSelectComponent(config, {
+				tui,
+				theme,
+				done,
+				input: ui.input,
+				notify: ui.notify,
+			}),
+		{
+			overlay: true,
+			overlayOptions: {
+				anchor: "center",
+				width: config.overlayWidth ?? 84,
+				maxHeight: config.overlayMaxHeight ?? "75%",
+			},
+		},
+	);
+}

package/request-user-input.ts

@@ -0,0 +1,259 @@
+import type { QnAResponse, QnAResult } from "./qna";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { QnATuiComponent, requirePiTuiModule } from "./qna";
+
+import type {
+	NormalizedRequestUserInputQuestion,
+	PlanModeState,
+	RequestUserInputAnswer,
+	RequestUserInputDetails,
+	RequestUserInputQuestion,
+	RequestUserInputResponse,
+} from "./types";
+
+import { findDuplicateId } from "./utils";
+
+function createText(text: string) {
+	const { Text } = requirePiTuiModule() as {
+		Text: new (text: string, x: number, y: number) => unknown;
+	};
+	return new Text(text, 0, 0);
+}
+
+export function normalizeRequestUserInputQuestions(
+	rawQuestions: RequestUserInputQuestion[],
+): { questions: NormalizedRequestUserInputQuestion[] } | { error: string } {
+	const questions: NormalizedRequestUserInputQuestion[] = rawQuestions.map((question) => ({
+		...question,
+		id: question.id.trim(),
+		options: question.options ?? [],
+	}));
+
+	for (const question of questions) {
+		if (!question.id) {
+			return { error: "request_user_input question ids must be non-empty." };
+		}
+	}
+
+	const duplicateQuestionId = findDuplicateId(questions.map((question) => question.id));
+	if (duplicateQuestionId) {
+		return {
+			error: `request_user_input question ids must be unique. Duplicate id: ${duplicateQuestionId}`,
+		};
+	}
+
+	return { questions };
+}
+
+export function buildRequestUserInputAnswer(
+	question: NormalizedRequestUserInputQuestion,
+	response: QnAResponse,
+): RequestUserInputAnswer {
+	const hasOptions = question.options.length > 0;
+	const otherIndex = question.options.length;
+	const trimmed = response.customText.trim();
+
+	if (!hasOptions) {
+		if (trimmed.length === 0) {
+			return { answers: [] };
+		}
+
+		return { answers: [`user_note: ${trimmed}`] };
+	}
+
+	if (response.selectedOptionIndex === otherIndex) {
+		if (trimmed.length === 0) {
+			return { answers: [] };
+		}
+
+		return { answers: ["Other", `user_note: ${trimmed}`] };
+	}
+
+	const label = question.options[response.selectedOptionIndex]?.label;
+	if (!label) {
+		return { answers: [] };
+	}
+
+	return { answers: [label] };
+}
+
+export function buildRequestUserInputResponse(
+	questions: NormalizedRequestUserInputQuestion[],
+	responses: QnAResponse[],
+): RequestUserInputResponse {
+	const answers: Record<string, RequestUserInputAnswer> = {};
+	for (let i = 0; i < questions.length; i++) {
+		answers[questions[i].id] = buildRequestUserInputAnswer(questions[i], responses[i]);
+	}
+	return { answers };
+}
+
+export function summarizeRequestUserInputAnswer(answer: RequestUserInputAnswer | undefined): string {
+	const entries = answer?.answers ?? [];
+	if (entries.length === 0) {
+		return "(no answer)";
+	}
+
+	const notes = entries
+		.filter((entry) => entry.startsWith("user_note: "))
+		.map((entry) => entry.slice("user_note: ".length).trim())
+		.filter((entry) => entry.length > 0);
+	const selected = entries
+		.filter((entry) => !entry.startsWith("user_note: "))
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+
+	if (selected.length === 0 && notes.length > 0) {
+		return notes.join(" · ");
+	}
+
+	if (selected.length > 0 && notes.length > 0) {
+		return `${selected.join(", ")} (${notes.join(" · ")})`;
+	}
+
+	return selected.join(", ") || "(no answer)";
+}
+
+export function buildRequestUserInputSummary(details: RequestUserInputDetails): string {
+	const lines: string[] = [];
+	for (let i = 0; i < details.questions.length; i++) {
+		const question = details.questions[i];
+		const answer = details.response.answers[question.id];
+		lines.push(`${i + 1}. ${question.question}`);
+		lines.push(`   Answer: ${summarizeRequestUserInputAnswer(answer)}`);
+	}
+	return lines.join("\n");
+}
+
+async function collectRequestUserInputAnswers(
+	ctx: ExtensionContext,
+	questions: NormalizedRequestUserInputQuestion[],
+): Promise<RequestUserInputResponse | null> {
+	const result = await ctx.ui.custom<QnAResult | null>(
+		(tui, theme, _kb, done) =>
+			new QnATuiComponent(questions, tui, done, {
+				title: "Questions",
+				questionSummaryLabel: (question) => question.header?.trim() || question.question,
+				accentColor: (text) => theme.fg("accent", text),
+				successColor: (text) => theme.fg("success", text),
+				warningColor: (text) => theme.fg("warning", text),
+				mutedColor: (text) => theme.fg("muted", text),
+				dimColor: (text) => theme.fg("dim", text),
+				boldText: (text) => theme.bold(text),
+			}),
+	);
+
+	if (!result) {
+		return null;
+	}
+
+	return buildRequestUserInputResponse(questions, result.responses);
+}
+
+export function registerRequestUserInputTool(
+	pi: ExtensionAPI,
+	dependencies: {
+		getState: () => PlanModeState;
+		requestUserInputSchema: unknown;
+	},
+) {
+	pi.registerTool({
+		description:
+			"Request user input for one to three short questions and wait for the response. This tool is only available in Plan mode.",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx): Promise<AgentToolResult<RequestUserInputDetails>> {
+			if (!dependencies.getState().active) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "request_user_input is unavailable when plan mode is inactive",
+						},
+					],
+				};
+			}
+
+			if (!ctx.hasUI) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "request_user_input requires interactive mode",
+						},
+					],
+				};
+			}
+
+			const normalized = normalizeRequestUserInputQuestions(params.questions as RequestUserInputQuestion[]);
+			if ("error" in normalized) {
+				return {
+					isError: true,
+					content: [{ type: "text", text: normalized.error }],
+				};
+			}
+
+			const response = await collectRequestUserInputAnswers(ctx, normalized.questions);
+			if (!response) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "request_user_input was cancelled before receiving a response",
+						},
+					],
+				};
+			}
+
+			const details: RequestUserInputDetails = {
+				questions: normalized.questions,
+				response,
+			};
+			return {
+				content: [
+					{
+						type: "text",
+						text: buildRequestUserInputSummary(details),
+					},
+				],
+				details,
+			};
+		},
+		label: "request_user_input",
+		name: "request_user_input",
+		parameters: dependencies.requestUserInputSchema,
+		renderCall(args, theme) {
+			const questions = ((args.questions as RequestUserInputQuestion[] | undefined) ?? []).length;
+			const label = `${questions} question${questions === 1 ? "" : "s"}`;
+			return createText(`${theme.fg("toolTitle", theme.bold("request_user_input "))}${theme.fg("muted", label)}`);
+		},
+		renderResult(result, { isPartial }, theme) {
+			if (isPartial) {
+				return createText(theme.fg("muted", "Waiting for user input..."));
+			}
+
+			const details = result.details as RequestUserInputDetails | undefined;
+			if (!details) {
+				const text = result.content.find((item) => item.type === "text");
+				return createText(text?.type === "text" ? text.text : "(no output)");
+			}
+
+			const lines: string[] = [];
+			for (let i = 0; i < details.questions.length; i++) {
+				const question = details.questions[i];
+				const answer = summarizeRequestUserInputAnswer(details.response.answers[question.id]);
+				lines.push(`${theme.fg("accent", `${i + 1}.`)} ${question.question}`);
+				if (answer === "(no answer)") {
+					lines.push(`   ${theme.fg("muted", "Answer:")} ${theme.fg("warning", answer)}`);
+				} else {
+					lines.push(`   ${theme.fg("muted", "Answer:")} ${answer}`);
+				}
+			}
+
+			return createText(lines.join("\n"));
+		},
+	});
+}

package/schemas.ts

@@ -0,0 +1,53 @@
+import { Type } from "typebox";
+
+export const SetPlanSchema = Type.Object(
+	{
+		plan: Type.String({
+			description:
+				"Full plan document text. This overwrites the current plan file and should include the complete latest plan.",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+export const RequestUserInputOptionSchema = Type.Object(
+	{
+		description: Type.String({
+			description: "One short sentence explaining impact/tradeoff if selected.",
+		}),
+		label: Type.String({ description: "User-facing label (1-5 words)." }),
+	},
+	{ additionalProperties: false },
+);
+
+export const RequestUserInputQuestionSchema = Type.Object(
+	{
+		header: Type.String({
+			description: "Short header label shown in the UI (12 or fewer chars).",
+		}),
+		id: Type.String({
+			description: "Stable identifier for mapping answers (snake_case).",
+		}),
+		options: Type.Optional(
+			Type.Array(RequestUserInputOptionSchema, {
+				description:
+					"Optional multiple-choice options. When omitted or empty, the question is treated as open-ended and accepts freeform input.",
+			}),
+		),
+		question: Type.String({
+			description: "Single-sentence prompt shown to the user.",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+export const RequestUserInputSchema = Type.Object(
+	{
+		questions: Type.Array(RequestUserInputQuestionSchema, {
+			description: "Questions to show the user. Prefer 1 and do not exceed 3.",
+			maxItems: 3,
+			minItems: 1,
+		}),
+	},
+	{ additionalProperties: false },
+);