ultimate-pi 0.9.1 → 0.10.0

package/.pi/extensions/lib/harness-subagents/parent-harness-ui-bridge.ts

@@ -0,0 +1,306 @@
+/**
+ * Registers ask_user and approve_plan in subagent sessions, delegating UI to the parent harness session.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import type {
+	PlanPacketLike,
+	PlanUserApproval,
+} from "../../../lib/harness-run-context.js";
+import { parsePlanApprovalFromMessage } from "../../../lib/harness-run-context.js";
+import { runAskDialog } from "../ask-user/dialog.js";
+import { runAskFallback } from "../ask-user/fallback.js";
+import { renderAskCall, renderAskResult } from "../ask-user/render.js";
+import {
+	PROMPT_GUIDELINES as ASK_PROMPT_GUIDELINES,
+	PROMPT_SNIPPET as ASK_PROMPT_SNIPPET,
+	AskUserParamsSchema,
+} from "../ask-user/schema.js";
+import type { AskUserParams, DialogResult } from "../ask-user/types.js";
+import {
+	formatResultText,
+	toToolDetails,
+	validateAskParams,
+} from "../ask-user/validate.js";
+import {
+	CREATE_PLAN_GUIDELINES,
+	CREATE_PLAN_SNIPPET,
+	executeCreatePlan,
+	formatCreatePlanResultText,
+} from "../plan-approval/create-plan.js";
+import { runPlanApprovalDialog } from "../plan-approval/dialog.js";
+import { runPlanApprovalFallback } from "../plan-approval/fallback.js";
+import {
+	renderApprovePlanCall,
+	renderApprovePlanResult,
+} from "../plan-approval/render.js";
+import {
+	ApprovePlanParamsSchema,
+	PROMPT_GUIDELINES as PLAN_PROMPT_GUIDELINES,
+	PROMPT_SNIPPET as PLAN_PROMPT_SNIPPET,
+} from "../plan-approval/schema.js";
+import type { ApprovePlanParams } from "../plan-approval/types.js";
+import {
+	formatApprovePlanResultText,
+	toApprovePlanToolDetails,
+	validateApprovePlanParams,
+} from "../plan-approval/validate.js";
+
+const HARNESS_UI_AGENT_TYPES = new Set([
+	"harness/planner",
+	"harness/evaluator",
+	"harness/adversary",
+	"harness/tie-breaker",
+]);
+
+export interface ParentHarnessUiHooks {
+	projectRoot?: string;
+	getParentEntries?: () => unknown[];
+	getParentRunContext?: () =>
+		| import("../../../lib/harness-run-context.js").HarnessRunContext
+		| null;
+	onPlanApproval?: (approval: PlanUserApproval) => void;
+	appendPlanDraft?: (draft: {
+		plan_packet: PlanPacketLike;
+		human_summary?: string;
+	}) => void;
+	onPlanCommitted?: (
+		runCtx: import("../../../lib/harness-run-context.js").HarnessRunContext,
+		packet: PlanPacketLike,
+		planPath: string,
+	) => void;
+}
+
+const CreatePlanParamsSchema = Type.Object({
+	plan_packet: Type.Object(
+		{},
+		{
+			description:
+				"Approved PlanPacket to persist (same object as approve_plan).",
+		},
+	),
+});
+
+const PLANNER_ONLY_AGENT = "harness/planner";
+
+export function agentTypeAllowsParentHarnessUi(agentType: string): boolean {
+	return HARNESS_UI_AGENT_TYPES.has(agentType);
+}
+
+/** @deprecated Use agentTypeAllowsParentHarnessUi */
+export function agentTypeAllowsParentAskUser(agentType: string): boolean {
+	return agentTypeAllowsParentHarnessUi(agentType);
+}
+
+function notifyPlanApproval(
+	hooks: ParentHarnessUiHooks | undefined,
+	details: unknown,
+	toolName: "ask_user" | "approve_plan",
+): void {
+	if (!hooks?.onPlanApproval) return;
+	const approval = parsePlanApprovalFromMessage({ toolName, details });
+	if (approval) hooks.onPlanApproval(approval);
+}
+
+export function createParentHarnessUiBridgeFactory(
+	parentCtx: ExtensionContext,
+	agentType: string,
+	hooks?: ParentHarnessUiHooks,
+): ((pi: ExtensionAPI) => void) | null {
+	if (!agentTypeAllowsParentHarnessUi(agentType)) {
+		return null;
+	}
+	return (pi: ExtensionAPI) => {
+		pi.registerTool({
+			name: "ask_user",
+			label: "Ask User",
+			description:
+				"Ask the user a structured question (parent session UI). Use for clarification — not final plan approval (use approve_plan).",
+			promptSnippet: ASK_PROMPT_SNIPPET,
+			promptGuidelines: ASK_PROMPT_GUIDELINES,
+			parameters: AskUserParamsSchema,
+			async execute(_toolCallId, params, _signal, _onUpdate) {
+				const validated = validateAskParams(params as AskUserParams);
+				if (typeof validated === "string") {
+					return {
+						content: [{ type: "text", text: validated }],
+						details: {
+							question: params.question ?? "",
+							options: [],
+							response: null,
+							cancelled: true,
+						},
+					};
+				}
+				let outcome: DialogResult;
+				if (parentCtx.hasUI) {
+					outcome = await runAskDialog(parentCtx.ui, validated);
+				} else {
+					outcome = await runAskFallback(parentCtx.ui, validated);
+				}
+				const details = toToolDetails(
+					validated,
+					outcome.response,
+					outcome.cancelled,
+				);
+				notifyPlanApproval(hooks, details, "ask_user");
+				const text = formatResultText(outcome.response, outcome.cancelled);
+				return {
+					content: [{ type: "text", text }],
+					details,
+				};
+			},
+			renderCall(args, theme) {
+				return renderAskCall(args, theme);
+			},
+			renderResult(result, options, theme) {
+				return renderAskResult(result, options, theme);
+			},
+		});
+
+		if (agentType !== PLANNER_ONLY_AGENT) {
+			return;
+		}
+
+		pi.registerTool({
+			name: "approve_plan",
+			label: "Approve Plan",
+			description:
+				"Present the full PlanPacket for user approval in the parent TUI (scrollable overlay).",
+			promptSnippet: PLAN_PROMPT_SNIPPET,
+			promptGuidelines: PLAN_PROMPT_GUIDELINES,
+			parameters: ApprovePlanParamsSchema,
+			async execute(_toolCallId, params, _signal, _onUpdate) {
+				const validated = validateApprovePlanParams(
+					params as ApprovePlanParams,
+				);
+				if (typeof validated === "string") {
+					return {
+						content: [{ type: "text", text: validated }],
+						details: {
+							plan_packet: (params as ApprovePlanParams).plan_packet ?? {},
+							options: [],
+							response: null,
+							cancelled: true,
+						},
+					};
+				}
+
+				hooks?.appendPlanDraft?.({
+					plan_packet: validated.plan_packet,
+					human_summary: validated.human_summary,
+				});
+
+				let outcome: DialogResult;
+				if (parentCtx.hasUI) {
+					outcome = await runPlanApprovalDialog(parentCtx.ui, validated);
+				} else {
+					outcome = await runPlanApprovalFallback(parentCtx.ui, validated);
+				}
+				const details = toApprovePlanToolDetails(
+					validated,
+					outcome.response,
+					outcome.cancelled,
+				);
+				notifyPlanApproval(hooks, details, "approve_plan");
+				const text = formatApprovePlanResultText(
+					outcome.response,
+					outcome.cancelled,
+				);
+				return {
+					content: [{ type: "text", text }],
+					details,
+				};
+			},
+			renderCall(args, theme) {
+				return renderApprovePlanCall(args, theme);
+			},
+			renderResult(result, options, theme) {
+				return renderApprovePlanResult(result, options, theme);
+			},
+		});
+
+		pi.registerTool({
+			name: "create_plan",
+			label: "Create Plan",
+			description:
+				"Write the approved PlanPacket to the canonical plan-packet.json for this harness run. Requires approve_plan Approve first. Do not use write/edit.",
+			promptSnippet: CREATE_PLAN_SNIPPET,
+			promptGuidelines: CREATE_PLAN_GUIDELINES,
+			parameters: CreatePlanParamsSchema,
+			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+				const validated = validateApprovePlanParams(
+					params as ApprovePlanParams,
+				);
+				if (typeof validated === "string") {
+					return {
+						content: [{ type: "text", text: validated }],
+						details: { error: validated },
+					};
+				}
+				const projectRoot = hooks?.projectRoot ?? parentCtx.cwd;
+				const parentEntries = hooks?.getParentEntries?.() ?? [];
+				const subEntries = ctx.sessionManager.getEntries();
+				const result = await executeCreatePlan(validated.plan_packet, {
+					projectRoot,
+					getParentEntries: () => parentEntries,
+					getSubagentEntries: () => subEntries,
+					getParentRunContext: () => hooks?.getParentRunContext?.() ?? null,
+					onCommitted: (runCtx, packet, planPath) => {
+						hooks?.onPlanCommitted?.(runCtx, packet, planPath);
+					},
+				});
+				const text = formatCreatePlanResultText(result);
+				return {
+					content: [{ type: "text", text }],
+					details: result.ok
+						? {
+								plan_path: result.planPath,
+								plan_id: result.planId,
+							}
+						: { error: result.error },
+					isError: !result.ok,
+				};
+			},
+			renderCall(args, theme) {
+				const packet = (args as { plan_packet?: PlanPacketLike }).plan_packet;
+				const id = packet?.plan_id ?? "?";
+				return new Text(theme.fg("accent", `create_plan: ${id}`), 0, 0);
+			},
+			renderResult(result, _options, theme) {
+				const details = result.details as
+					| { plan_path?: string; error?: string }
+					| undefined;
+				if (details?.error) {
+					return new Text(
+						theme.fg("error", details.error ?? "create_plan failed"),
+						0,
+						0,
+					);
+				}
+				return new Text(
+					theme.fg(
+						"success",
+						`Wrote ${details?.plan_path ?? "plan-packet.json"}`,
+					),
+					0,
+					0,
+				);
+			},
+		});
+	};
+}
+
+/** @deprecated Use createParentHarnessUiBridgeFactory */
+export function createParentAskUserBridgeFactory(
+	parentCtx: ExtensionContext,
+	agentType: string,
+	hooks?: ParentHarnessUiHooks,
+): ((pi: ExtensionAPI) => void) | null {
+	return createParentHarnessUiBridgeFactory(parentCtx, agentType, hooks);
+}

package/.pi/extensions/lib/harness-subagents/parent-harness-ui-hooks.ts

@@ -0,0 +1,59 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	appendPlanApprovalIfNew,
+	getLatestRunContext,
+	type HarnessRunContext,
+	nowIso,
+	type PlanUserApproval,
+	planPacketSummary,
+} from "../../../lib/harness-run-context.js";
+import type { ParentHarnessUiHooks } from "./parent-harness-ui-bridge.js";
+
+function persistRunContext(pi: ExtensionAPI, runCtx: HarnessRunContext): void {
+	pi.appendEntry("harness-run-context", runCtx);
+}
+
+export function createParentHarnessUiHooks(
+	pi: ExtensionAPI,
+	getParentEntries: () => unknown[],
+	projectRoot: string,
+): ParentHarnessUiHooks {
+	return {
+		projectRoot,
+		getParentEntries,
+		getParentRunContext: () => getLatestRunContext(getParentEntries()),
+		appendPlanDraft: (draft) => {
+			const planId = String(draft.plan_packet.plan_id ?? "plan");
+			const summary =
+				draft.human_summary?.trim() || `Plan ${planId} — pending your approval`;
+			pi.sendMessage({
+				customType: "harness-plan-draft",
+				content: summary,
+				display: true,
+				details: {
+					schema_version: "1.0.0",
+					plan_packet: draft.plan_packet,
+					human_summary: draft.human_summary ?? null,
+					shown_at: nowIso(),
+				},
+			});
+		},
+		onPlanApproval: (approval: PlanUserApproval) => {
+			const entries = getParentEntries();
+			const runCtx = getLatestRunContext(entries);
+			appendPlanApprovalIfNew(
+				(type, data) => pi.appendEntry(type, data),
+				entries,
+				approval,
+				runCtx,
+			);
+		},
+		onPlanCommitted: (runCtx, packet, planPath) => {
+			persistRunContext(pi, runCtx);
+			pi.appendEntry(
+				"harness-plan-packet",
+				planPacketSummary(packet, planPath, "ready"),
+			);
+		},
+	};
+}

package/.pi/extensions/lib/harness-subagents/spawn-policy.ts

@@ -41,5 +41,14 @@ export function evaluateSubagentToolCall(
 			reason: `Tool "ask_user" is not available for ${agentType ?? "this agent"} (orchestrator-only).`,
 		};
 	}
+	if (toolName === "approve_plan" || toolName === "create_plan") {
+		if (agentType === "harness/planner") {
+			return { action: "allow" };
+		}
+		return {
+			action: "block",
+			reason: `Tool "${toolName}" is only available for harness/planner.`,
+		};
+	}
 	return { action: "allow" };
 }

package/.pi/extensions/lib/harness-subagents/vendored/agent-manager.ts

@@ -13,6 +13,7 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { ParentHarnessUiHooks } from "../parent-harness-ui-bridge.js";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
 import type {
 	AgentInvocation,
@@ -84,6 +85,8 @@ interface SpawnOptions {
 	onCompaction?: (info: CompactionInfo) => void;
 	/** Spawn context (blackboard injection) for subagent system prompt. */
 	systemPromptAppendix?: string;
+	/** Parent UI hooks for plan approval sync and draft transcript. */
+	parentHarnessUiHooks?: ParentHarnessUiHooks;
 }
 
 export class AgentManager {
@@ -253,6 +256,7 @@ export class AgentManager {
 			},
 			systemPromptAppendix: options.systemPromptAppendix,
 			parentExtensionContext: ctx,
+			parentHarnessUiHooks: options.parentHarnessUiHooks,
 		})
 			.then(({ responseText, session, aborted, steered }) => {
 				// Don't overwrite status if externally stopped via abort()

package/.pi/extensions/lib/harness-subagents/vendored/agent-runner.ts

@@ -18,7 +18,10 @@ import {
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { evaluateHarnessSubagentToolCall } from "../harness-subagent-policy.js";
-import { createParentAskUserBridgeFactory } from "../parent-ask-user-bridge.js";
+import {
+	createParentHarnessUiBridgeFactory,
+	type ParentHarnessUiHooks,
+} from "../parent-harness-ui-bridge.js";
 import {
 	getAgentConfig,
 	getConfig,
@@ -152,8 +155,10 @@ export interface RunOptions {
 	}) => void;
 	/** Blackboard or other spawn context appended to the subagent system prompt. */
 	systemPromptAppendix?: string;
-	/** Parent session context — used to bridge ask_user UI into subagents. */
+	/** Parent session context — used to bridge ask_user / approve_plan UI into subagents. */
 	parentExtensionContext?: ExtensionContext;
+	/** Parent-session hooks (plan draft transcript, approval sync). */
+	parentHarnessUiHooks?: ParentHarnessUiHooks;
 }
 
 export interface RunResult {
@@ -331,11 +336,15 @@ export async function runAgent(
 			: systemPrompt;
 
 	const extensionFactories: Array<(pi: ExtensionAPI) => void> = [];
-	const askUserBridge = options.parentExtensionContext
-		? createParentAskUserBridgeFactory(options.parentExtensionContext, type)
+	const harnessUiBridge = options.parentExtensionContext
+		? createParentHarnessUiBridgeFactory(
+				options.parentExtensionContext,
+				type,
+				options.parentHarnessUiHooks,
+			)
 		: null;
-	if (askUserBridge) {
-		extensionFactories.push(askUserBridge);
+	if (harnessUiBridge) {
+		extensionFactories.push(harnessUiBridge);
 	}
 	extensionFactories.push((pi) => {
 		pi.on("tool_call", (event) => {
@@ -410,7 +419,14 @@ export async function runAgent(
 	const filterTools = (names: string[]) =>
 		names.filter((t) => {
 			if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-			if (t === "ask_user" && askUserBridge) return true;
+			if (t === "ask_user" && harnessUiBridge) return true;
+			if (
+				(t === "approve_plan" || t === "create_plan") &&
+				harnessUiBridge &&
+				type === "harness/planner"
+			) {
+				return true;
+			}
 			if (disallowedSet?.has(t)) return false;
 			if (builtinToolNameSet.has(t)) return true;
 			if (extensions === false) return false;
@@ -425,7 +441,14 @@ export async function runAgent(
 		session.setActiveToolsByName(activeTools);
 	} else {
 		const fallback = toolNames.filter((t) => {
-			if (t === "ask_user" && askUserBridge) return true;
+			if (t === "ask_user" && harnessUiBridge) return true;
+			if (
+				(t === "approve_plan" || t === "create_plan") &&
+				harnessUiBridge &&
+				type === "harness/planner"
+			) {
+				return true;
+			}
 			return !disallowedSet?.has(t);
 		});
 		session.setActiveToolsByName(fallback);
@@ -444,10 +467,14 @@ export async function runAgent(
 		},
 	});
 
-	if (askUserBridge) {
-		const withAsk = new Set(session.getActiveToolNames());
-		withAsk.add("ask_user");
-		session.setActiveToolsByName([...withAsk]);
+	if (harnessUiBridge) {
+		const withHarnessUi = new Set(session.getActiveToolNames());
+		withHarnessUi.add("ask_user");
+		if (type === "harness/planner") {
+			withHarnessUi.add("approve_plan");
+			withHarnessUi.add("create_plan");
+		}
+		session.setActiveToolsByName([...withHarnessUi]);
 	}
 
 	options.onSessionCreated?.(session);

package/.pi/extensions/lib/harness-subagents/vendored/index.ts

@@ -18,8 +18,8 @@ import {
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import {
-	extractPlanApprovalsFromEntries,
 	getLatestRunContext,
+	syncPlannerApprovalsToParent,
 } from "../../../../lib/harness-run-context.js";
 import { getDriftReport } from "../agent-manifest.js";
 import { Blackboard } from "../blackboard.js";
@@ -27,6 +27,8 @@ import {
 	buildBlackboardContextInjection,
 	registerBlackboardTool,
 } from "../blackboard-tool.js";
+import type { ParentHarnessUiHooks } from "../parent-harness-ui-bridge.js";
+import { createParentHarnessUiHooks } from "../parent-harness-ui-hooks.js";
 import { AgentManager } from "./agent-manager.js";
 import {
 	getAgentConversation,
@@ -650,6 +652,7 @@ export function createHarnessSubagentsExtension(packageRoot: string) {
 
 		// --- Cross-extension RPC via pi.events ---
 		let currentCtx: ExtensionContext | undefined;
+		let parentHarnessUiHooks: ParentHarnessUiHooks | undefined;
 
 		// ---- Subagent scheduler ----
 		// Session-scoped: store is constructed inside session_start once sessionId
@@ -678,6 +681,11 @@ export function createHarnessSubagentsExtension(packageRoot: string) {
 		// Capture ctx from session_start for RPC spawn handler + start the scheduler.
 		pi.on("session_start", async (_event, ctx) => {
 			currentCtx = ctx;
+			parentHarnessUiHooks = createParentHarnessUiHooks(
+				pi,
+				() => ctx.sessionManager.getEntries(),
+				ctx.cwd,
+			);
 			manager.clearCompleted();
 			if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
 
@@ -1338,6 +1346,7 @@ Guidelines:
 								isolation,
 								invocation: agentInvocation,
 								systemPromptAppendix,
+								parentHarnessUiHooks,
 								...bgCallbacks,
 							});
 						} catch (err) {
@@ -1481,6 +1490,7 @@ Guidelines:
 								invocation: agentInvocation,
 								systemPromptAppendix,
 								signal,
+								parentHarnessUiHooks,
 								...fgCallbacks,
 							},
 						);
@@ -1491,6 +1501,24 @@ Guidelines:
 
 					clearInterval(spinnerInterval);
 
+					if (
+						subagentType === "harness/planner" &&
+						record.session &&
+						record.status !== "running" &&
+						record.status !== "queued"
+					) {
+						const parentEntries = ctx.sessionManager.getEntries();
+						const runCtx = getLatestRunContext(parentEntries);
+						if (runCtx) {
+							syncPlannerApprovalsToParent(
+								(type, data) => pi.appendEntry(type, data),
+								parentEntries,
+								record.session.sessionManager.getEntries(),
+								runCtx,
+							);
+						}
+					}
+
 					// Clean up foreground agent from widget
 					if (fgId) {
 						agentActivity.delete(fgId);
@@ -1607,16 +1635,12 @@ Guidelines:
 						const parentEntries = _ctx.sessionManager.getEntries();
 						const runCtx = getLatestRunContext(parentEntries);
 						if (runCtx) {
-							const subEntries = record.session.sessionManager.getEntries();
-							for (const approval of extractPlanApprovalsFromEntries(
-								subEntries,
-							)) {
-								pi.appendEntry("harness-plan-approval", {
-									plan_id: approval.plan_id ?? runCtx.plan_id,
-									approved_at: approval.approved_at,
-									source: "ask_user",
-								});
-							}
+							syncPlannerApprovalsToParent(
+								(type, data) => pi.appendEntry(type, data),
+								parentEntries,
+								record.session.sessionManager.getEntries(),
+								runCtx,
+							);
 						}
 					}