ultimate-pi 0.9.0 → 0.10.0

package/.pi/extensions/lib/plan-approval/create-plan.ts

@@ -0,0 +1,131 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import {
+	canonicalPlanPath,
+	type HarnessRunContext,
+	hasPlanUserApproval,
+	type PlanPacketLike,
+	saveProjectActiveRun,
+	saveRunContextToDisk,
+	validatePlanPacket,
+} from "../../../lib/harness-run-context.js";
+
+export const CREATE_PLAN_SNIPPET =
+	"create_plan({ plan_packet: { ...approved PlanPacket } })";
+
+export const CREATE_PLAN_GUIDELINES = [
+	"Call create_plan only after the user approves via approve_plan (Approve selection).",
+	"Pass the same plan_packet you showed in approve_plan — path is resolved automatically.",
+	"Never use write or edit for plan-packet.json; create_plan is the only allowed plan write.",
+];
+
+export interface CreatePlanDeps {
+	projectRoot: string;
+	getParentEntries: () => unknown[];
+	getSubagentEntries: () => unknown[];
+	getParentRunContext: () => HarnessRunContext | null;
+	/** Persist parent harness-run-context + plan-packet summary entries. */
+	onCommitted: (
+		runCtx: HarnessRunContext,
+		packet: PlanPacketLike,
+		planPath: string,
+	) => void;
+}
+
+export type CreatePlanResult =
+	| { ok: true; planPath: string; planId: string }
+	| { ok: false; error: string };
+
+export async function executeCreatePlan(
+	planPacket: PlanPacketLike,
+	deps: CreatePlanDeps,
+): Promise<CreatePlanResult> {
+	const validation = validatePlanPacket(planPacket);
+	if (!validation.valid) {
+		return {
+			ok: false,
+			error: `create_plan: invalid plan_packet — ${validation.errors.join("; ")}`,
+		};
+	}
+
+	const runCtx = deps.getParentRunContext();
+	if (!runCtx?.run_id || !runCtx.plan_packet_path) {
+		return {
+			ok: false,
+			error:
+				"create_plan: no active harness run on parent session (missing plan_packet_path).",
+		};
+	}
+
+	const planPath = resolve(deps.projectRoot, runCtx.plan_packet_path);
+	const canonical = canonicalPlanPath(runCtx.run_id, deps.projectRoot);
+	if (resolve(planPath) !== resolve(canonical)) {
+		return {
+			ok: false,
+			error: `create_plan: plan_packet_path must be ${canonical}`,
+		};
+	}
+
+	const planId = String(planPacket.plan_id ?? "");
+	const parentEntries = deps.getParentEntries();
+	const subEntries = deps.getSubagentEntries();
+	const approved =
+		hasPlanUserApproval(parentEntries, {
+			sincePlanCommand: true,
+			planId: planId || runCtx.plan_id,
+		}) ||
+		hasPlanUserApproval(subEntries, {
+			sincePlanCommand: false,
+			planId: planId || runCtx.plan_id,
+		});
+	if (!approved) {
+		return {
+			ok: false,
+			error:
+				"create_plan: blocked until user approves via approve_plan (Approve) in this session.",
+		};
+	}
+
+	try {
+		await mkdir(dirname(planPath), { recursive: true });
+		await writeFile(
+			planPath,
+			`${JSON.stringify(planPacket, null, 2)}\n`,
+			"utf-8",
+		);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { ok: false, error: `create_plan: write failed — ${msg}` };
+	}
+
+	const updated: HarnessRunContext = {
+		...runCtx,
+		plan_id: planId || runCtx.plan_id,
+		plan_ready: true,
+		phase: "plan",
+		last_completed_step: "plan",
+		last_outcome: "ready",
+		next_recommended_command: "/harness-run",
+		updated_at: new Date().toISOString(),
+	};
+
+	try {
+		await saveRunContextToDisk(updated);
+		await saveProjectActiveRun(updated);
+	} catch {
+		/* disk mirror best-effort */
+	}
+
+	deps.onCommitted(updated, planPacket, planPath);
+
+	return {
+		ok: true,
+		planPath,
+		planId: planId || updated.plan_id || "unknown",
+	};
+}
+
+export function formatCreatePlanResultText(result: CreatePlanResult): string {
+	if (!result.ok) return result.error;
+	return `Plan written to ${result.planPath} (plan_id=${result.planId}).`;
+}

package/.pi/extensions/lib/plan-approval/dialog.ts

@@ -0,0 +1,207 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { formatPlanPacketLines } from "./format-plan.js";
+import type {
+	PlanApprovalDialogResult,
+	ValidatedApprovePlanParams,
+} from "./types.js";
+
+type FocusRegion = "plan" | "options";
+
+interface CustomAnswer {
+	response: { kind: "selection"; selections: string[] };
+}
+
+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 runPlanApprovalDialog(
+	ui: ExtensionUIContext,
+	validated: ValidatedApprovePlanParams,
+): Promise<PlanApprovalDialogResult> {
+	const planLines = formatPlanPacketLines(validated.plan_packet, 100);
+	const displayOptions = validated.options;
+
+	const result = await withTimeout(
+		ui.custom<CustomAnswer | null>((tui, theme, _kb, done) => {
+			let scrollOffset = 0;
+			let optionIndex = 0;
+			let focus: FocusRegion = "plan";
+			let cachedLines: string[] | undefined;
+
+			function refresh() {
+				cachedLines = undefined;
+				tui.requestRender();
+			}
+
+			function submitSelection() {
+				const opt = displayOptions[optionIndex];
+				done({
+					response: { kind: "selection", selections: [opt.title] },
+				});
+			}
+
+			function handleInput(data: string) {
+				if (focus === "plan") {
+					if (matchesKey(data, Key.up) || data === "k") {
+						scrollOffset = Math.max(0, scrollOffset - 1);
+						refresh();
+						return;
+					}
+					if (matchesKey(data, Key.down) || data === "j") {
+						scrollOffset += 1;
+						refresh();
+						return;
+					}
+					if (matchesKey(data, Key.pageUp)) {
+						scrollOffset = Math.max(0, scrollOffset - 8);
+						refresh();
+						return;
+					}
+					if (matchesKey(data, Key.pageDown)) {
+						scrollOffset += 8;
+						refresh();
+						return;
+					}
+					if (matchesKey(data, Key.tab)) {
+						focus = "options";
+						refresh();
+						return;
+					}
+				}
+
+				if (focus === "options") {
+					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 (matchesKey(data, Key.tab)) {
+						focus = "plan";
+						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";
+				const dims = (tui as { height?: number }).height;
+				const termHeight = typeof dims === "number" && dims > 10 ? dims : 24;
+				const footerLines = displayOptions.length * 2 + 8;
+				const planViewport = Math.max(
+					6,
+					Math.floor(termHeight * 0.55) - footerLines,
+				);
+
+				if (useOverlay) {
+					add(theme.fg("accent", "─".repeat(width)));
+				}
+
+				add(theme.fg("accent", " Plan approval"));
+				if (validated.human_summary) {
+					for (const line of validated.human_summary.split("\n")) {
+						add(theme.fg("muted", ` ${line}`));
+					}
+				}
+				lines.push("");
+
+				const maxScroll = Math.max(0, planLines.length - planViewport);
+				scrollOffset = Math.min(scrollOffset, maxScroll);
+				const visible = planLines.slice(
+					scrollOffset,
+					scrollOffset + planViewport,
+				);
+				const planLabel =
+					focus === "plan"
+						? theme.fg("accent", " [plan — ↑↓/Pg scroll, Tab → options]")
+						: theme.fg("dim", " [plan]");
+				add(planLabel);
+				for (const line of visible) {
+					add(theme.fg("text", ` ${line}`));
+				}
+				if (planLines.length > planViewport) {
+					add(
+						theme.fg(
+							"dim",
+							` … ${scrollOffset + 1}-${scrollOffset + visible.length} of ${planLines.length}`,
+						),
+					);
+				}
+				lines.push("");
+
+				const optLabel =
+					focus === "options"
+						? theme.fg("accent", " Options (↑↓, Enter, Tab → plan):")
+						: theme.fg("dim", " Options (Tab to focus):");
+				add(optLabel);
+				for (let i = 0; i < displayOptions.length; i++) {
+					const opt = displayOptions[i];
+					const focused = focus === "options" && i === optionIndex;
+					const prefix = focused ? theme.fg("accent", "> ") : "  ";
+					const num = `${i + 1}. `;
+					if (focused) {
+						add(prefix + theme.fg("accent", `${num}${opt.title}`));
+					} else {
+						add(`${prefix}${theme.fg("text", `${num}${opt.title}`)}`);
+					}
+					if (opt.description) {
+						add(`     ${theme.fg("muted", opt.description)}`);
+					}
+				}
+
+				lines.push("");
+				add(theme.fg("dim", " Tab: plan ↔ options • Esc: cancel"));
+
+				if (useOverlay) {
+					add(theme.fg("accent", "─".repeat(width)));
+				}
+
+				cachedLines = lines;
+				return lines;
+			}
+
+			return {
+				render,
+				invalidate: () => {
+					cachedLines = undefined;
+				},
+				handleInput,
+			};
+		}),
+		undefined,
+	);
+
+	if (!result) {
+		return { response: null, cancelled: true };
+	}
+
+	return { response: result.response, cancelled: false };
+}

package/.pi/extensions/lib/plan-approval/fallback.ts

@@ -0,0 +1,50 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { formatPlanPacketLines } from "./format-plan.js";
+import type {
+	PlanApprovalDialogResult,
+	ValidatedApprovePlanParams,
+} from "./types.js";
+
+export async function runPlanApprovalFallback(
+	ui: ExtensionUIContext,
+	validated: ValidatedApprovePlanParams,
+): Promise<PlanApprovalDialogResult> {
+	const lines = formatPlanPacketLines(validated.plan_packet, 80);
+	const body = lines.join("\n");
+	const summary = validated.human_summary
+		? `${validated.human_summary}\n\n`
+		: "";
+	const prompt = `${summary}${body}\n\nSelect: ${validated.options.map((o, i) => `${i + 1}. ${o.title}`).join(" | ")}`;
+	const raw = await ui.input("Plan approval", prompt);
+	if (!raw?.trim()) {
+		return { response: null, cancelled: true };
+	}
+	const pick = raw.trim();
+	const byIndex = Number.parseInt(pick, 10);
+	if (
+		Number.isFinite(byIndex) &&
+		byIndex >= 1 &&
+		byIndex <= validated.options.length
+	) {
+		return {
+			response: {
+				kind: "selection",
+				selections: [validated.options[byIndex - 1].title],
+			},
+			cancelled: false,
+		};
+	}
+	const match = validated.options.find(
+		(o) => o.title.toLowerCase() === pick.toLowerCase(),
+	);
+	if (match) {
+		return {
+			response: { kind: "selection", selections: [match.title] },
+			cancelled: false,
+		};
+	}
+	return {
+		response: { kind: "freeform", text: pick },
+		cancelled: false,
+	};
+}

package/.pi/extensions/lib/plan-approval/format-plan.ts

@@ -0,0 +1,94 @@
+import type { PlanPacketLike } from "../../../lib/harness-run-context.js";
+
+function wrapLine(text: string, width: number): string[] {
+	if (width < 20) return [text];
+	const words = text.split(/\s+/);
+	const lines: string[] = [];
+	let line = "";
+	for (const word of words) {
+		const next = line ? `${line} ${word}` : word;
+		if (next.length > width && line) {
+			lines.push(line);
+			line = word;
+		} else {
+			line = next;
+		}
+	}
+	if (line) lines.push(line);
+	return lines.length > 0 ? lines : [""];
+}
+
+function riskBadge(risk: string | undefined): string {
+	const r = (risk ?? "med").toLowerCase();
+	return `[risk: ${r}]`;
+}
+
+export function formatPlanPacketLines(
+	packet: PlanPacketLike,
+	width: number,
+): string[] {
+	const lines: string[] = [];
+	const w = Math.max(40, width - 2);
+	const add = (s: string) => {
+		for (const part of wrapLine(s, w)) lines.push(part);
+	};
+
+	lines.push(`plan_id: ${packet.plan_id ?? "?"}`);
+	lines.push(`task_id: ${packet.task_id ?? "?"}`);
+	lines.push(
+		riskBadge(
+			typeof packet.risk_level === "string" ? packet.risk_level : undefined,
+		),
+	);
+	lines.push("");
+	lines.push("scope:");
+	add(String(packet.scope ?? ""));
+	lines.push("");
+
+	const assumptions = Array.isArray(packet.assumptions)
+		? (packet.assumptions as string[])
+		: [];
+	if (assumptions.length > 0) {
+		lines.push("assumptions:");
+		for (const a of assumptions) {
+			add(`  • ${a}`);
+		}
+		lines.push("");
+	}
+
+	const checks = Array.isArray(packet.acceptance_checks)
+		? (packet.acceptance_checks as string[])
+		: [];
+	if (checks.length > 0) {
+		lines.push("acceptance_checks:");
+		for (let i = 0; i < checks.length; i++) {
+			add(`  ${i + 1}. ${checks[i]}`);
+		}
+		lines.push("");
+	}
+
+	const rollback = packet.rollback_plan as
+		| {
+				rollback_artifacts?: {
+					revert_command?: string;
+					revert_branch?: string;
+					patch_bundle?: string;
+				};
+		  }
+		| undefined;
+	const artifacts = rollback?.rollback_artifacts;
+	if (artifacts) {
+		lines.push("rollback:");
+		if (artifacts.revert_command) {
+			add(`  revert_command: ${artifacts.revert_command}`);
+		}
+		if (artifacts.revert_branch) {
+			add(`  revert_branch: ${artifacts.revert_branch}`);
+		}
+		if (artifacts.patch_bundle) {
+			add(`  patch_bundle: ${artifacts.patch_bundle}`);
+		}
+	}
+
+	return lines;
+}

package/.pi/extensions/lib/plan-approval/render.ts

@@ -0,0 +1,83 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type {
+	Theme,
+	ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { PlanPacketLike } from "../../../lib/harness-run-context.js";
+import { formatPlanPacketLines } from "./format-plan.js";
+import type { ApprovePlanToolDetails } from "./types.js";
+
+export function renderApprovePlanCall(
+	args: { plan_packet?: PlanPacketLike; human_summary?: string },
+	theme: Theme,
+): Text {
+	const packet = args.plan_packet;
+	const planId = packet?.plan_id ?? "?";
+	const risk = packet?.risk_level ?? "?";
+	const scope = typeof packet?.scope === "string" ? packet.scope : "";
+	const scopeShort = scope.length > 60 ? `${scope.slice(0, 57)}...` : scope;
+	const summary = args.human_summary?.trim();
+	const head = summary
+		? `${planId} ${risk} — ${summary}`
+		: `${planId} ${risk} — ${scopeShort || "(no scope)"}`;
+	return new Text(theme.fg("accent", `approve_plan: ${head}`), 0, 0);
+}
+
+export function renderApprovePlanResult(
+	result: AgentToolResult<unknown>,
+	_options: ToolRenderResultOptions,
+	theme: Theme,
+): Text {
+	const details = result.details as ApprovePlanToolDetails | undefined;
+	if (!details) {
+		const block = result.content[0];
+		return new Text(block?.type === "text" ? block.text : "", 0, 0);
+	}
+	if (details.cancelled) {
+		return new Text(theme.fg("warning", "Plan approval cancelled"), 0, 0);
+	}
+	const sel =
+		details.response?.kind === "selection"
+			? details.response.selections[0]
+			: details.response?.kind === "freeform"
+				? details.response.text
+				: "";
+	if (/^approve/i.test(sel ?? "")) {
+		return new Text(
+			theme.fg(
+				"success",
+				`Approved plan ${details.plan_packet.plan_id ?? ""}`.trim(),
+			),
+			0,
+			0,
+		);
+	}
+	if (sel) return new Text(theme.fg("muted", sel), 0, 0);
+	return new Text(theme.fg("muted", "No response"), 0, 0);
+}
+
+export function renderHarnessPlanDraft(
+	details: {
+		plan_packet?: PlanPacketLike;
+		human_summary?: string | null;
+	},
+	width: number,
+	theme: Theme,
+): string[] {
+	const lines: string[] = [];
+	lines.push(theme.fg("accent", "Harness plan (pending approval)"));
+	if (details.human_summary) {
+		lines.push(theme.fg("muted", details.human_summary));
+		lines.push("");
+	}
+	const packet = details.plan_packet;
+	if (!packet) {
+		lines.push(theme.fg("warning", "(no plan_packet)"));
+		return lines;
+	}
+	for (const line of formatPlanPacketLines(packet, width)) {
+		lines.push(truncateToWidth(line, width));
+	}
+	return lines;
+}

package/.pi/extensions/lib/plan-approval/schema.ts

@@ -0,0 +1,39 @@
+import { Type } from "@sinclair/typebox";
+
+export const ApprovePlanParamsSchema = Type.Object({
+	plan_packet: Type.Object(
+		{},
+		{
+			description:
+				"Full PlanPacket object (schema_version, plan_id, task_id, scope, assumptions, risk_level, acceptance_checks, rollback_plan).",
+		},
+	),
+	human_summary: Type.Optional(
+		Type.String({
+			description: "Short summary shown above the plan body.",
+		}),
+	),
+	options: Type.Optional(
+		Type.Array(
+			Type.Union([
+				Type.String(),
+				Type.Object({
+					title: Type.String(),
+					description: Type.Optional(Type.String()),
+				}),
+			]),
+		),
+	),
+	displayMode: Type.Optional(
+		Type.Union([Type.Literal("overlay"), Type.Literal("inline")]),
+	),
+});
+
+export const PROMPT_SNIPPET =
+	"approve_plan({ plan_packet: { ...PlanPacket fields... }, human_summary?: string })";
+
+export const PROMPT_GUIDELINES = [
+	"Call approve_plan once with the complete plan_packet when ready for user approval.",
+	"Use ask_user only for clarification — not for final plan approval.",
+	"On Request changes, revise the plan and call approve_plan again.",
+];

package/.pi/extensions/lib/plan-approval/types.ts

@@ -0,0 +1,32 @@
+import type { PlanPacketLike } from "../../../lib/harness-run-context.js";
+import type { AskResponse, DialogResult } from "../ask-user/types.js";
+
+export const DEFAULT_PLAN_APPROVAL_OPTIONS = [
+	"Approve",
+	"Request changes",
+	"Cancel",
+] as const;
+
+export interface ApprovePlanParams {
+	plan_packet: PlanPacketLike;
+	human_summary?: string;
+	options?: Array<string | { title: string; description?: string }>;
+	displayMode?: "overlay" | "inline";
+}
+
+export interface ValidatedApprovePlanParams {
+	plan_packet: PlanPacketLike;
+	human_summary?: string;
+	options: { title: string; description?: string }[];
+	displayMode: "overlay" | "inline";
+}
+
+export interface ApprovePlanToolDetails {
+	plan_packet: PlanPacketLike;
+	human_summary?: string;
+	options: string[];
+	response: AskResponse | null;
+	cancelled: boolean;
+}
+
+export type PlanApprovalDialogResult = DialogResult;

package/.pi/extensions/lib/plan-approval/validate.ts

@@ -0,0 +1,61 @@
+import {
+	type PlanPacketLike,
+	validatePlanPacket,
+} from "../../../lib/harness-run-context.js";
+import type { AskResponse } from "../ask-user/types.js";
+import { formatResultText } from "../ask-user/validate.js";
+import type {
+	ApprovePlanParams,
+	ApprovePlanToolDetails,
+	ValidatedApprovePlanParams,
+} from "./types.js";
+import { DEFAULT_PLAN_APPROVAL_OPTIONS } from "./types.js";
+
+export function validateApprovePlanParams(
+	params: ApprovePlanParams,
+): ValidatedApprovePlanParams | string {
+	const packet = params.plan_packet;
+	if (!packet || typeof packet !== "object") {
+		return "approve_plan: plan_packet object is required.";
+	}
+	const validation = validatePlanPacket(packet as PlanPacketLike);
+	if (!validation.valid) {
+		return `approve_plan: invalid plan_packet — ${validation.errors.join("; ")}`;
+	}
+	const rawOptions = params.options;
+	const options =
+		rawOptions && rawOptions.length > 0
+			? rawOptions.map((o) =>
+					typeof o === "string"
+						? { title: o }
+						: { title: o.title, description: o.description },
+				)
+			: DEFAULT_PLAN_APPROVAL_OPTIONS.map((title) => ({ title }));
+	return {
+		plan_packet: packet as PlanPacketLike,
+		human_summary: params.human_summary?.trim() || undefined,
+		options,
+		displayMode: params.displayMode ?? "overlay",
+	};
+}
+
+export function toApprovePlanToolDetails(
+	validated: ValidatedApprovePlanParams,
+	response: AskResponse | null,
+	cancelled: boolean,
+): ApprovePlanToolDetails {
+	return {
+		plan_packet: validated.plan_packet,
+		human_summary: validated.human_summary,
+		options: validated.options.map((o) => o.title),
+		response,
+		cancelled,
+	};
+}
+
+export function formatApprovePlanResultText(
+	response: AskResponse | null,
+	cancelled: boolean,
+): string {
+	return formatResultText(response, cancelled);
+}