pi-plans 0.2.0 → 0.3.0

package/tools/ask-choice.ts

@@ -15,8 +15,118 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { disableAutoComplete, enableAutoComplete, isAutoCompleteEnabled, recordAskChoice } from "../src/autocomplete.ts";
+import { truncateToWidth, visibleWidth } from "../src/refine-ui-helpers.ts";
 import { normalizeWorkdir, readActive, recordDecision } from "../src/state.ts";
 
+// ---------------------------------------------------------------------------
+// Panel fitting: pi's ExtensionSelectorComponent renders each option as an
+// auto-wrapping Text with NO height cap — an oversized panel exceeds the
+// terminal rows and the TUI thrashes (flicker). These helpers sanitize and
+// shrink the question/labels before they reach ctx.ui.select.
+// ---------------------------------------------------------------------------
+
+export const STATUS_BAR_HEIGHT = 1;
+export const PANEL_SAFETY_MARGIN = 2;
+export const PANEL_CHROME_LINES = 9; // 8 measured in extension-selector.js (DynamicBorder×2 + Spacer×4 + title + keyHint) + 1 slack
+/** Each option renders in at most three wrapped lines (user-facing contract). */
+export const OPTION_MAX_LINES = 3;
+/**
+ * Per-row width overhead, pinned to extension-selector.js: DynamicBorder 1 +
+ * Text padding 1 + selected marker "→ " 2 = 4, plus 2 columns of slack for
+ * word-wrap inefficiency. Re-verify against that file if pi changes its layout.
+ */
+export const SELECTOR_WIDTH_OVERHEAD = 6;
+export const FALLBACK_COLUMNS = 100;
+export const FALLBACK_ROWS = 30;
+/** Minimal-form floor for tiny terminals (stage-3 width). */
+const MINIMAL_LINE_WIDTH = 20;
+/**
+ * Truncation floor for fixed tail labels (Other…/Auto-complete/Auto-refine
+ * loop): the longest magic prefix ("Auto-refine loop", 16 cols) plus slack.
+ * These labels drive startsWith() answer routing and must never lose it.
+ */
+const FIXED_LABEL_FLOOR = 18;
+
+export interface PanelItem {
+	/** Label without description (degradation stage 1+). */
+	core: string;
+	/** Full display label: core + description (degradation stage 0). */
+	display: string;
+	/** Fixed tail labels (Other…/Auto-complete/Auto-refine loop): truncation keeps at least the magic prefix. */
+	fixed?: boolean;
+}
+
+export interface FittedPanel {
+	question: string;
+	labels: string[];
+	/** True when even the minimal form exceeds the terminal budget. */
+	overflowWarned: boolean;
+}
+
+function sanitizeLine(text: string): string {
+	return text.replace(/\r\n|\n|\r/g, " ");
+}
+
+function truncateWithDotDot(text: string, budget: number): string {
+	if (visibleWidth(text) <= budget) return text;
+	return `${truncateToWidth(text, Math.max(0, budget - 2), "")}..`;
+}
+
+function truncateForItem(item: PanelItem, budget: number): string {
+	const effective = item.fixed ? Math.max(budget, FIXED_LABEL_FLOOR) : budget;
+	return truncateWithDotDot(item.display, effective);
+}
+
+function wrappedLineCount(text: string, lineWidth: number): number {
+	return Math.max(1, Math.ceil(visibleWidth(text) / lineWidth));
+}
+
+/**
+ * Sanitize and shrink the question/labels so the projected panel height stays
+ * under rows − statusBar − margin. Degradation order (D-001): per-label 3-line
+ * budget → strip descriptions → labels to one line → truncate the question →
+ * minimal 20-column form (overflowWarned; never fails closed).
+ */
+export function fitAskChoicePanel(question: string, items: PanelItem[], columns: number, rows: number): FittedPanel {
+	const cols = columns > 0 ? columns : FALLBACK_COLUMNS;
+	const termRows = rows > 0 ? rows : FALLBACK_ROWS;
+	const lineBudget = Math.max(20, cols - SELECTOR_WIDTH_OVERHEAD);
+	const rowBudget = Math.max(10, termRows - STATUS_BAR_HEIGHT - PANEL_SAFETY_MARGIN);
+
+	const cleanQuestion = sanitizeLine(question);
+	const clean = items.map((item) => ({ core: sanitizeLine(item.core), display: sanitizeLine(item.display), fixed: item.fixed === true }));
+
+	const projected = (q: string, ls: string[]) =>
+		PANEL_CHROME_LINES + wrappedLineCount(q, lineBudget) + ls.reduce((sum, l) => sum + wrappedLineCount(l, lineBudget), 0);
+
+	// Stage 0: full display labels, each within the 3-line budget.
+	// (Signature note: items carry {core, display} because D-001 stage 1 strips
+	// descriptions, which a plain string list cannot express.)
+	let currentQuestion = cleanQuestion;
+	let currentLabels = clean.map((item) => truncateForItem(item, OPTION_MAX_LINES * lineBudget));
+
+	if (projected(currentQuestion, currentLabels) >= rowBudget) {
+		// Stage 1: strip descriptions (core labels only).
+		currentLabels = clean.map((item) => truncateForItem({ ...item, display: item.core }, OPTION_MAX_LINES * lineBudget));
+	}
+	if (projected(currentQuestion, currentLabels) >= rowBudget) {
+		// Stage 2: labels to a single line.
+		currentLabels = clean.map((item) => truncateForItem({ ...item, display: item.core }, lineBudget));
+	}
+	if (projected(currentQuestion, currentLabels) >= rowBudget) {
+		// Stage 3: truncate the question too.
+		currentQuestion = truncateWithDotDot(currentQuestion, lineBudget);
+	}
+	let overflowWarned = false;
+	if (projected(currentQuestion, currentLabels) >= rowBudget) {
+		// Minimal form for tiny terminals: 20-column floor; still over → warn, never fail closed.
+		currentQuestion = truncateWithDotDot(cleanQuestion, MINIMAL_LINE_WIDTH);
+		currentLabels = clean.map((item) => truncateForItem({ ...item, display: item.core }, MINIMAL_LINE_WIDTH));
+		overflowWarned = projected(currentQuestion, currentLabels) >= rowBudget;
+	}
+	return { question: currentQuestion, labels: currentLabels, overflowWarned };
+}
+
 const Option = Type.Object({
 	label: Type.String({ description: "Option label" }),
 	description: Type.Optional(Type.String({ description: "Short tradeoff that matters, shown to the user" })),
@@ -33,6 +143,12 @@ const AskChoiceParams = Type.Object({
 				"Offer the Auto-complete option (default true). MUST be false for the execution handoff, install waivers, publishing, deployment, merge, push, credential use, or any external-state change.",
 		}),
 	),
+	trailing: Type.Optional(
+		StringEnum(["auto-refine-loop"] as const, {
+			description:
+				'Replace the trailing Auto-complete option with "Auto-refine loop" (post-execution amelioration prompt). Selecting it returns instructions to ask the rounds/termination follow-up; Auto-complete is suppressed entirely for this question.',
+		}),
+	),
 	workdir: Type.Optional(Type.String({ description: "Target workspace; default current working directory" })),
 });
 
@@ -48,7 +164,7 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 		name: "ask_choice",
 		label: "Ask Choice",
 		description:
-			"Ask the user one planning or refinement question as a numbered choice prompt: recommended option first, alternatives next, then Other and Auto-complete. One question per call. Use for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff (with autoComplete: false).",
+			"Ask the user one planning or refinement question as a numbered choice prompt: recommended option first, alternatives next, then Other and Auto-complete. One question per call. Use for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff (with autoComplete: false). The optional trailing parameter swaps the trailing option to Auto-refine loop for the post-execution amelioration prompt.",
 		promptSnippet: "Ask structured planning questions with recommended/Other/Auto-complete ordering",
 		promptGuidelines: [
 			"Use ask_choice for every pi-plans question to the user instead of plain-text questions; it enforces option ordering and records decisions.",
@@ -59,7 +175,10 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const workdir = normalizeWorkdir(params.workdir ?? ctx.cwd);
 			const allowOther = params.allowOther ?? true;
-			const autoComplete = params.autoComplete ?? true;
+			// Param normalization: a trailing option replaces Auto-complete entirely,
+			// so an erroneously passed autoComplete flag is suppressed here.
+			const trailing = params.trailing;
+			const autoComplete = (params.autoComplete ?? true) && trailing === undefined;
 			const options = params.options;
 			if (options.length === 0) throw new Error("ask_choice requires at least one option");
 			const recommended = options.find((option) => option.recommended) ?? options[0];
@@ -120,16 +239,30 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				};
 			}
 
-			const displayLabels: string[] = options.map((option, index) => {
-				let label = `${index + 1}. ${option.label}`;
-				if (option === recommended) label += "  (recommended)";
-				if (option.description) label += ` — ${option.description}`;
-				return label;
+			const AUTO_REFINE_LOOP_LABEL =
+				"Auto-refine loop  (run refinement rounds until no high-severity finding or the 5-round cap)";
+			const panelItems: PanelItem[] = options.map((option, index) => {
+				const core = `${index + 1}. ${option.label}${option === recommended ? "  (recommended)" : ""}`;
+				let display = `${index + 1}. ${option.label}`;
+				if (option === recommended) display += "  (recommended)";
+				if (option.description) display += ` — ${option.description}`;
+				return { core, display };
 			});
-			if (allowOther) displayLabels.push("Other…  (type your own answer)");
-			if (autoComplete) displayLabels.push("Auto-complete  (take the recommended option)");
+			if (allowOther) panelItems.push({ core: "Other…  (type your own answer)", display: "Other…  (type your own answer)", fixed: true });
+			if (autoComplete) panelItems.push({ core: "Auto-complete  (take the recommended option)", display: "Auto-complete  (take the recommended option)", fixed: true });
+			else if (trailing) panelItems.push({ core: AUTO_REFINE_LOOP_LABEL, display: AUTO_REFINE_LOOP_LABEL, fixed: true });
+
+			const panel = fitAskChoicePanel(
+				params.question,
+				panelItems,
+				process.stdout.columns ?? 0,
+				process.stdout.rows ?? 0,
+			);
+			if (panel.overflowWarned) {
+				ctx.ui.notify?.("Terminal too small: the ask_choice panel may overflow even in its minimal form.", "warning");
+			}
 
-			const selected = await ctx.ui.select(params.question, displayLabels);
+			const selected = await ctx.ui.select(panel.question, panel.labels);
 			if (selected === undefined) {
 				disableAutoComplete(ctx, "question cancelled");
 				return {
@@ -158,6 +291,20 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				};
 			}
 
+			if (trailing && selected.startsWith("Auto-refine loop")) {
+				recordAskChoice(ctx, false);
+				record("Auto-refine loop", "user");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `User selected Auto-refine loop. Immediately ask the follow-up with ask_choice (autoComplete: false, in the session language): how should the amelioration loop terminate? Options (recommended first): 1. until no high-severity finding (hard cap 5 rounds) 2. 1 round 3. 2 rounds 4. 3 rounds. Then run the loop per the completion instructions: each round calls refine (role: "reviewer", target: "implementation"), accepts findings on evidence, applies fixes, re-runs relevant tests, and continues until the termination condition or the 5-round cap.`,
+						},
+					],
+					details: details("Auto-refine loop", "user"),
+				};
+			}
+
 			if (allowOther && selected.startsWith("Other…")) {
 				const typed = await ctx.ui.input(`${params.question} — your answer:`);
 				if (typed === undefined || !typed.trim()) {
@@ -176,7 +323,7 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				};
 			}
 
-			const index = displayLabels.indexOf(selected);
+			const index = panel.labels.indexOf(selected);
 			const option = index >= 0 && index < options.length ? options[index] : undefined;
 			if (!option) {
 				recordAskChoice(ctx, false);

package/tools/code-graph.ts

@@ -0,0 +1,254 @@
+/**
+ * Agent-facing graph tool. Eagerly avoids importing node:sqlite or the
+ * parsers at module load; both are loaded on first action call.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	loadGraphRuntime,
+	describeRuntimeIssues,
+	type RuntimeStatus,
+} from "../src/code-graph/runtime.ts";
+import { resolveCanonicalWorktree } from "../src/code-graph/paths.ts";
+import type { WorktreePaths } from "../src/code-graph/paths.ts";
+import { Store } from "../src/code-graph/store.ts";
+import { makeBackend } from "../src/code-graph/parsers/javascript.ts";
+import { PythonBackend } from "../src/code-graph/parsers/python.ts";
+import type { ParserBackend } from "../src/code-graph/parser.ts";
+import { hashText } from "../src/code-graph/parser.ts";
+import type { Language } from "../src/code-graph/types.ts";
+import { screeningQuery } from "../src/code-graph/screening.ts";
+import { deleteFile, listPending, updateFile, updateFunction } from "../src/code-graph/mutations.ts";
+
+const CodeGraphParams = Type.Object({
+	action: StringEnum(
+		[
+			"status",
+			"screening",
+			"get-function",
+			"update-function",
+			"update-file",
+			"delete-file",
+			"list-pending",
+			"reindex",
+			"manifest",
+		] as const,
+		{ description: "Code graph action to perform" },
+	),
+	workdir: Type.Optional(Type.String({ description: "Target workspace directory" })),
+	language: Type.Optional(StringEnum(["javascript", "typescript", "tsx", "python"] as const)),
+	functionName: Type.Optional(Type.String()),
+	fileDir: Type.Optional(Type.String({ description: "File directory (POSIX, '.' for root)" })),
+	fileName: Type.Optional(Type.String({ description: "File name without directory" })),
+	fullCode: Type.Optional(Type.String({ description: "New function body text for update-function" })),
+	text: Type.Optional(Type.String({ description: "New whole-file text for update-file" })),
+	limit: Type.Optional(Type.Number()),
+	force: Type.Optional(Type.Boolean()),
+});
+
+export type CodeGraphContext = Parameters<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>[4];
+
+export interface RuntimeCacheEntry {
+	runtime: Awaited<ReturnType<typeof loadGraphRuntime>>["runtime"];
+	parsers: Record<Language, ParserBackend>;
+	paths: WorktreePaths;
+	store: Store;
+}
+
+let runtimeCache: RuntimeCacheEntry | null = null;
+
+export async function ensureRuntime(workdir: string, ctx: CodeGraphContext): Promise<{ entry: RuntimeCacheEntry; status: RuntimeStatus } | null> {
+	const { runtime, status } = await loadGraphRuntime();
+	if (status.issues.length > 0 && !status.sqliteAvailable && !status.parserAvailable) {
+		ctx.ui?.notify?.(`code-graph unavailable: ${describeRuntimeIssues(status).join("; ")}`, "warning");
+		return null;
+	}
+	const paths = resolveCanonicalWorktree(workdir);
+	if (!runtimeCache || runtimeCache.paths.codeGraphDb !== paths.codeGraphDb) {
+		if (runtimeCache) {
+			runtimeCache.store.close();
+			runtimeCache = null;
+		}
+		const store = new Store({ dbPath: paths.codeGraphDb, worktreeRoot: paths.worktreeRoot, gitCommonDir: paths.gitCommonDir }, runtime.sqlite);
+		try {
+			store.checkWorktree(paths.worktreeRoot, paths.gitCommonDir);
+		} catch (error) {
+			store.close();
+			ctx.ui?.notify?.(`code-graph: ${(error as Error).message}`, "error");
+			return null;
+		}
+		const ParserCtor = runtime.parser.Parser as unknown as new () => { parse(input: string | Buffer): unknown; setLanguage(language: unknown): void };
+		const parsers: Record<Language, ParserBackend> = {
+			javascript: makeBackend("javascript", ParserCtor, runtime.parser.javascript),
+			typescript: makeBackend("typescript", ParserCtor, runtime.parser.typescript),
+			tsx: makeBackend("tsx", ParserCtor, runtime.parser.tsx),
+			python: new PythonBackend(ParserCtor, runtime.parser.python),
+		};
+		runtimeCache = { runtime, parsers, paths, store };
+	}
+	return { entry: runtimeCache, status };
+}
+
+export function registerCodeGraphTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "code_graph",
+		label: "Code Graph",
+		description:
+			"Read-only code-graph actions: status, screening (no full_code), function read, reindex guard, manifest summary. No agent mutation API in v1.",
+		promptSnippet: "Read-only code graph queries",
+		parameters: CodeGraphParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const workdir = params.workdir ?? ctx.cwd;
+			const ensured = await ensureRuntime(workdir, ctx);
+			if (!ensured) {
+				return {
+					content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "runtime unavailable" }) }],
+					details: {},
+				};
+			}
+			const { entry } = ensured;
+			switch (params.action) {
+				case "status":
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									ok: true,
+									dbPath: entry.paths.codeGraphDb,
+									worktreeRoot: entry.paths.worktreeRoot,
+									files: entry.store.read(() => entry.store.db.prepare("SELECT COUNT(*) AS c FROM files").get()) as { c: number } | undefined,
+									functions: entry.store.read(() => entry.store.db.prepare("SELECT COUNT(*) AS c FROM functions").get()) as { c: number } | undefined,
+								}),
+							},
+						],
+						details: {},
+					};
+				case "screening": {
+					const items = screeningQuery({
+						store: entry.store,
+						language: params.language,
+						functionNameLike: params.functionName,
+						limit: params.limit ?? 100,
+					});
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, items }) }],
+						details: {},
+					};
+				}
+				case "get-function": {
+					if (!params.functionName) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "functionName required" }) }],
+							details: {},
+						};
+					}
+					const row = entry.store.read(() =>
+						entry.store.db
+							.prepare(
+								`SELECT file_dir, file_name, function_name, full_code, render_code,
+									full_code_hash, render_code_hash, version, kind
+								 FROM functions
+								 WHERE function_name = ? LIMIT 1`,
+							)
+							.get(params.functionName),
+					) as
+						| {
+								file_dir: string;
+								file_name: string;
+								function_name: string;
+								full_code: string;
+								render_code: string;
+								full_code_hash: string;
+								render_code_hash: string;
+								version: number;
+								kind: string;
+						  }
+						| undefined;
+					if (!row) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "not found" }) }],
+							details: {},
+						};
+					}
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, function: row }) }],
+						details: {},
+					};
+				}
+case "update-function": {
+					if (!params.fileDir || !params.fileName || !params.functionName || typeof params.fullCode !== "string") {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir, fileName, functionName, and fullCode are required" }) }],
+							details: {},
+						};
+					}
+					const result = updateFunction(entry.store, {
+						fileDir: params.fileDir,
+						fileName: params.fileName,
+						functionName: params.functionName,
+						fullCode: params.fullCode,
+					});
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "update-file": {
+					if (!params.fileDir || !params.fileName || typeof params.text !== "string") {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir, fileName, and text are required" }) }],
+							details: {},
+						};
+					}
+					const result = updateFile(entry.store, {
+						fileDir: params.fileDir,
+						fileName: params.fileName,
+						text: params.text,
+						...(params.language ? { language: params.language } : {}),
+					});
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "delete-file": {
+					if (!params.fileDir || !params.fileName) {
+						return {
+							content: [{ type: "text", text: JSON.stringify({ ok: false, reason: "fileDir and fileName are required" }) }],
+							details: {},
+						};
+					}
+					const result = deleteFile(entry.store, { fileDir: params.fileDir, fileName: params.fileName });
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: {} };
+				}
+				case "list-pending": {
+					return { content: [{ type: "text", text: JSON.stringify({ ok: true, pending: listPending(entry.store) }) }], details: {} };
+				}
+				
+				case "reindex":
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({
+									ok: false,
+									reason: "reindex must run via the /init-graph slash command (D-013)",
+								}),
+							},
+						],
+						details: {},
+					};
+				case "manifest": {
+					const rows = entry.store.read(() =>
+						entry.store.db
+							.prepare(
+								`SELECT file_dir, file_name, COUNT(*) AS c FROM file_entries GROUP BY file_dir, file_name ORDER BY file_dir, file_name`,
+							)
+							.all(),
+					) as Array<{ file_dir: string; file_name: string; c: number }>;
+					return {
+						content: [{ type: "text", text: JSON.stringify({ ok: true, manifest: rows }) }],
+						details: {},
+					};
+				}
+			}
+		},
+	});
+}