ultimate-pi 0.10.1 → 0.12.0

package/.pi/extensions/lib/harness-subagent-precheck.ts

@@ -0,0 +1,95 @@
+/**
+ * Pre-spawn validation for harness subagent tool calls.
+ */
+
+import {
+	type AgentConfig,
+	agentAllowsMutatingTools,
+} from "../../../vendor/pi-subagents/src/agents.js";
+import type { HarnessPhase } from "../../lib/harness-run-context.js";
+import { inferHarnessPhase } from "../../lib/harness-run-context.js";
+import { classifyHarnessAgent } from "./harness-subagent-policy.js";
+
+export interface SubagentTaskRef {
+	agent: string;
+}
+
+export interface PrecheckResult {
+	ok: boolean;
+	message?: string;
+}
+
+function collectAgents(params: {
+	agent?: string;
+	tasks?: SubagentTaskRef[];
+	chain?: SubagentTaskRef[];
+	aggregator?: { agent: string };
+}): string[] {
+	const names: string[] = [];
+	if (params.agent) names.push(params.agent);
+	if (params.tasks) for (const t of params.tasks) names.push(t.agent);
+	if (params.chain) for (const c of params.chain) names.push(c.agent);
+	if (params.aggregator) names.push(params.aggregator.agent);
+	return names;
+}
+
+function resolveAgent(
+	agents: AgentConfig[],
+	name: string,
+): AgentConfig | undefined {
+	return agents.find((a) => a.name === name);
+}
+
+export function precheckHarnessSubagentSpawn(
+	params: {
+		agent?: string;
+		tasks?: SubagentTaskRef[];
+		chain?: SubagentTaskRef[];
+		aggregator?: { agent: string };
+	},
+	agents: AgentConfig[],
+	phase: HarnessPhase,
+): PrecheckResult {
+	const names = collectAgents(params);
+	const mutating = names.filter((n) => {
+		const cfg = resolveAgent(agents, n);
+		return cfg
+			? agentAllowsMutatingTools(cfg)
+			: n.startsWith("harness/executor");
+	});
+
+	if (phase === "plan" && mutating.length > 0) {
+		return {
+			ok: false,
+			message:
+				`Plan phase: cannot spawn mutating subagents (${mutating.join(", ")}). ` +
+				`Use read-only harness/planning/* agents until execute phase.`,
+		};
+	}
+
+	if ((params.tasks?.length ?? 0) > 1 && mutating.length > 1) {
+		return {
+			ok: false,
+			message:
+				"Parallel subagent tasks cannot include multiple mutating agents (file race risk). " +
+				"Run one executor at a time.",
+		};
+	}
+
+	for (const name of names) {
+		if (!name.startsWith("harness/")) continue;
+		const kind = classifyHarnessAgent(name);
+		if (kind === "planner" && phase !== "plan") {
+			// allowed — planning agents can run in plan only ideally
+		}
+	}
+
+	return { ok: true };
+}
+
+export function inferPhaseForPrecheck(
+	entries: unknown[],
+	prompt?: string,
+): HarnessPhase {
+	return inferHarnessPhase(entries as never, prompt);
+}

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

@@ -0,0 +1,176 @@
+/**
+ * ultimate-pi harness wrapper around vendored pi-subagents.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfig } from "../../../vendor/pi-subagents/src/agents.js";
+import {
+	createSubagentsExtension,
+	type HarnessSubagentsOptions,
+	type SpawnAuthForward,
+} from "../../../vendor/pi-subagents/src/subagents.js";
+import { captureHarnessEvent } from "./harness-posthog.js";
+import {
+	checkHarnessSpawnBudget,
+	countHarnessAgentsInRequest,
+	createSpawnBudgetState,
+	recordSpawnEnd,
+	recordSpawnStart,
+} from "./harness-spawn-budget.js";
+import {
+	isUsableApiKey,
+	resolveConcreteSubagentModel,
+} from "./harness-subagent-auth.js";
+import {
+	inferPhaseForPrecheck,
+	precheckHarnessSubagentSpawn,
+} from "./harness-subagent-precheck.js";
+
+const spawnBudget = createSpawnBudgetState();
+let lastSessionId = "harness";
+
+function maskApiKey(key: string | undefined): string | undefined {
+	if (!key) return undefined;
+	if (key.length <= 12) return "***";
+	return `${key.slice(0, 7)}…${key.slice(-4)}`;
+}
+
+// #region agent log
+function agentDebugLog(
+	hypothesisId: string,
+	location: string,
+	message: string,
+	data: Record<string, unknown>,
+): void {
+	fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-Debug-Session-Id": "e762d5",
+		},
+		body: JSON.stringify({
+			sessionId: "e762d5",
+			hypothesisId,
+			location,
+			message,
+			data,
+			timestamp: Date.now(),
+		}),
+	}).catch(() => {});
+}
+// #endregion
+
+async function resolveHarnessSpawnAuth(
+	ctx: ExtensionContext,
+	agent: AgentConfig,
+): Promise<SpawnAuthForward | undefined> {
+	const parentModel = ctx.model
+		? { provider: ctx.model.provider, id: ctx.model.id }
+		: undefined;
+	const concrete = resolveConcreteSubagentModel(ctx.cwd, parentModel, agent);
+	if (!concrete) {
+		// #region agent log
+		agentDebugLog(
+			"D",
+			"harness-subagents-bridge.ts:resolveHarnessSpawnAuth",
+			"no concrete model",
+			{
+				agent: agent.name,
+				agentModel: agent.model,
+				parentModel: parentModel
+					? `${parentModel.provider}/${parentModel.id}`
+					: undefined,
+			},
+		);
+		// #endregion
+		return undefined;
+	}
+	const apiKey = await ctx.modelRegistry.getApiKeyForProvider(
+		concrete.provider,
+	);
+	// #region agent log
+	agentDebugLog(
+		"F",
+		"harness-subagents-bridge.ts:resolveHarnessSpawnAuth",
+		"concrete subprocess auth",
+		{
+			agent: agent.name,
+			parentModel: parentModel
+				? `${parentModel.provider}/${parentModel.id}`
+				: undefined,
+			concreteModel: concrete.modelRef,
+			routerProfile: concrete.routerProfile,
+			routerTier: concrete.routerTier,
+			apiKey: maskApiKey(apiKey),
+			usable: isUsableApiKey(apiKey),
+		},
+	);
+	// #endregion
+	if (!isUsableApiKey(apiKey)) return undefined;
+	return {
+		provider: concrete.provider,
+		modelRef: concrete.modelRef,
+		apiKey,
+	};
+}
+
+export function createHarnessSubagentsExtension(
+	packageRoot: string,
+): (pi: ExtensionAPI) => void {
+	const options: HarnessSubagentsOptions = {
+		packageRoot,
+		defaultAgentScope: "both",
+		defaultConfirmProjectAgents: false,
+		truncateDetails: true,
+		resolveSpawnAuth: resolveHarnessSpawnAuth,
+		beforeExecute: async (params, agents, ctx) => {
+			lastSessionId = ctx.sessionManager.getSessionId();
+			const { harnessCount } = countHarnessAgentsInRequest(
+				params as Parameters<typeof countHarnessAgentsInRequest>[0],
+			);
+			if (harnessCount > 0) {
+				const budget = checkHarnessSpawnBudget(spawnBudget, harnessCount);
+				if (!budget.ok) {
+					return { ok: false, message: budget.message };
+				}
+				const phase = inferPhaseForPrecheck(ctx.sessionManager.getEntries());
+				const pre = precheckHarnessSubagentSpawn(
+					params as Parameters<typeof precheckHarnessSubagentSpawn>[0],
+					agents,
+					phase,
+				);
+				if (!pre.ok) {
+					return { ok: false, message: pre.message };
+				}
+			}
+			return { ok: true };
+		},
+		onSpawnStart: (harnessCount) => {
+			if (harnessCount <= 0) return;
+			recordSpawnStart(spawnBudget, harnessCount);
+			captureHarnessEvent(lastSessionId, "harness_subagent_spawned", {
+				active_after: spawnBudget.active,
+				spawn_count: harnessCount,
+			});
+		},
+		onSpawnEnd: (harnessCount) => {
+			if (harnessCount <= 0) return;
+			recordSpawnEnd(spawnBudget, harnessCount);
+		},
+		onCompleted: ({ agents, mode, durationMs }) => {
+			if (agents.length === 0) return;
+			captureHarnessEvent(lastSessionId, "harness_subagent_completed", {
+				mode,
+				duration_ms: durationMs,
+				agent_count: agents.length,
+			});
+		},
+	};
+
+	return (pi: ExtensionAPI) => {
+		createSubagentsExtension(pi, options);
+	};
+}

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

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import {
 	canonicalPlanPath,
@@ -9,6 +9,8 @@ import {
 	saveRunContextToDisk,
 	validatePlanPacket,
 } from "../../../lib/harness-run-context.js";
+import { writeYamlFile } from "../../../lib/harness-yaml.js";
+import { writePlanReviewMarkdown } from "./plan-review.js";
 
 export const CREATE_PLAN_SNIPPET =
 	"create_plan({ plan_packet: { ...approved PlanPacket } })";
@@ -16,7 +18,7 @@ export const CREATE_PLAN_SNIPPET =
 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.",
+	"Never use write or edit for plan-packet.yaml; create_plan is the only allowed plan write.",
 ];
 
 export interface CreatePlanDeps {
@@ -88,11 +90,7 @@ export async function executeCreatePlan(
 
 	try {
 		await mkdir(dirname(planPath), { recursive: true });
-		await writeFile(
-			planPath,
-			`${JSON.stringify(planPacket, null, 2)}\n`,
-			"utf-8",
-		);
+		await writeYamlFile(planPath, planPacket);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		return { ok: false, error: `create_plan: write failed — ${msg}` };
@@ -116,6 +114,10 @@ export async function executeCreatePlan(
 		/* disk mirror best-effort */
 	}
 
+	await writePlanReviewMarkdown(deps.projectRoot, updated, planPacket, {
+		status: "committed",
+	});
+
 	deps.onCommitted(updated, planPacket, planPath);
 
 	return {

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

@@ -0,0 +1,393 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import {
+	canonicalPlanPath,
+	canonicalPlanReviewPath,
+	type HarnessRunContext,
+	type PlanPacketLike,
+} from "../../../lib/harness-run-context.js";
+import { formatPlanPacketLines } from "./format-plan.js";
+import type { PlanResearchBrief } from "./types.js";
+
+export {
+	canonicalPlanReviewPath,
+	PLAN_REVIEW_BASENAME,
+} from "../../../lib/harness-run-context.js";
+
+export type PlanReviewStatus = "draft" | "approved" | "committed";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function str(value: unknown): string | null {
+	return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function strList(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.map((item) => (typeof item === "string" ? item.trim() : null))
+		.filter((item): item is string => Boolean(item));
+}
+
+/** Render Darwin research sections for plan-review.md. */
+export function formatResearchBriefMarkdown(
+	research: PlanResearchBrief | null | undefined,
+): string {
+	if (!research) return "";
+	const lines: string[] = [];
+	const decomp = asRecord(research.decomposition);
+	const hyp = asRecord(research.hypothesis);
+	const evalBrief = asRecord(research.eval);
+
+	if (decomp) {
+		lines.push("## Phase 1 — Problem decomposition");
+		lines.push("");
+		const restate = str(decomp.problem_restatement);
+		if (restate) {
+			lines.push("**What is being asked?**");
+			lines.push("");
+			lines.push(restate);
+			lines.push("");
+		}
+		const types = strList(decomp.problem_types);
+		if (types.length) {
+			lines.push(`**Problem type(s):** ${types.join(", ")}`);
+			lines.push("");
+		}
+		const scope = asRecord(decomp.scope);
+		if (scope) {
+			const focus = str(scope.narrowed_focus);
+			if (focus) {
+				lines.push("**Scope:**");
+				lines.push("");
+				lines.push(focus);
+				lines.push("");
+			}
+			const excluded = strList(scope.excluded);
+			if (excluded.length) {
+				lines.push("**Excluded:**");
+				for (const item of excluded) lines.push(`- ${item}`);
+				lines.push("");
+			}
+		}
+		for (const [label, key] of [
+			["Hard constraints", "hard_constraints"],
+			["Soft constraints", "soft_constraints"],
+			["Success metrics", "success_metrics"],
+		] as const) {
+			const items = strList(decomp[key]);
+			if (items.length) {
+				lines.push(`**${label}:**`);
+				for (const item of items) lines.push(`- ${item}`);
+				lines.push("");
+			}
+		}
+		const prior = asRecord(decomp.prior_art);
+		if (prior) {
+			lines.push("**Prior art:**");
+			lines.push("");
+			const best = str(prior.best_approach);
+			const gap = str(prior.gap);
+			if (best) lines.push(`- Best approach: ${best}`);
+			if (gap) lines.push(`- Gap: ${gap}`);
+			for (const dead of strList(prior.dead_ends)) {
+				lines.push(`- Dead end: ${dead}`);
+			}
+			lines.push("");
+		}
+		const core = str(decomp.core_tension);
+		if (core) {
+			lines.push("**Core tension:**");
+			lines.push("");
+			lines.push(core);
+			lines.push("");
+		}
+	}
+
+	if (hyp) {
+		lines.push("## Phase 2 — DARWIN hypothesis");
+		lines.push("");
+		const primary = asRecord(hyp.primary);
+		if (primary) {
+			for (const [label, key] of [
+				["Claim", "claim"],
+				["Mechanism", "mechanism"],
+				["Prediction", "prediction"],
+				["Experiment", "experiment"],
+				["Resolves tension", "tension_resolution"],
+			] as const) {
+				const text = str(primary[key]);
+				if (text) {
+					lines.push(`**${label}:** ${text}`);
+					lines.push("");
+				}
+			}
+		}
+		const fork = asRecord(hyp.dialectical_fork);
+		if (fork) {
+			const forkText = str(fork.fork);
+			if (forkText) {
+				lines.push(`**Dialectical fork:** ${forkText}`);
+				lines.push("");
+			}
+			const pathA = str(fork.path_a);
+			const pathB = str(fork.path_b);
+			if (pathA) lines.push(`- **Path A:** ${pathA}`);
+			if (pathB) lines.push(`- **Path B:** ${pathB}`);
+			lines.push("");
+		}
+		const alts = Array.isArray(hyp.alternatives) ? hyp.alternatives : [];
+		if (alts.length) {
+			lines.push("**Alternatives:**");
+			for (const alt of alts) {
+				const rec = asRecord(alt);
+				if (!rec) continue;
+				const claim = str(rec.claim);
+				const bet = str(rec.key_bet);
+				if (claim) lines.push(`- ${claim}${bet ? ` (bet: ${bet})` : ""}`);
+			}
+			lines.push("");
+		}
+		const steps = strList(hyp.recommended_next_steps);
+		if (steps.length) {
+			lines.push("**Recommended next steps:**");
+			for (const step of steps) lines.push(`1. ${step}`);
+			lines.push("");
+		}
+	}
+
+	if (evalBrief) {
+		lines.push("## Self-evaluation");
+		lines.push("");
+		lines.push("| Dimension | Score | Rationale |");
+		lines.push("|-----------|-------|-----------|");
+		const dims = asRecord(evalBrief.dimensions);
+		if (dims) {
+			for (const name of [
+				"novelty",
+				"coherence",
+				"testability",
+				"impact",
+			] as const) {
+				const dim = asRecord(dims[name]);
+				if (!dim) continue;
+				const score = typeof dim.score === "number" ? String(dim.score) : "?";
+				const rationale = str(dim.rationale) ?? "";
+				lines.push(`| ${name} | ${score}/100 | ${rationale} |`);
+			}
+		}
+		const rel = asRecord(evalBrief.relevance);
+		if (rel) {
+			const passes = rel.passes === true ? "✓" : "✗";
+			const rationale = str(rel.rationale) ?? "";
+			lines.push(`| Relevance | ${passes} | ${rationale} |`);
+		}
+		lines.push("");
+		const summary = str(evalBrief.human_summary);
+		if (summary) {
+			lines.push(summary);
+			lines.push("");
+		}
+	}
+
+	return lines.length ? `${lines.join("\n")}\n` : "";
+}
+
+export function formatPlanPacketMarkdown(
+	packet: PlanPacketLike,
+	opts?: {
+		human_summary?: string | null;
+		status?: PlanReviewStatus;
+		plan_packet_path?: string | null;
+		research_brief?: PlanResearchBrief | null;
+	},
+): string {
+	const lines: string[] = [];
+	const status = opts?.status ?? "draft";
+	lines.push("# Harness plan");
+	lines.push("");
+	lines.push(`- **Status:** ${status}`);
+	lines.push(`- **plan_id:** ${packet.plan_id ?? "?"}`);
+	lines.push(`- **task_id:** ${packet.task_id ?? "?"}`);
+	lines.push(
+		`- **risk_level:** ${typeof packet.risk_level === "string" ? packet.risk_level : "med"}`,
+	);
+	if (opts?.plan_packet_path) {
+		lines.push(`- **canonical JSON:** \`${opts.plan_packet_path}\``);
+	}
+	lines.push("");
+	if (opts?.human_summary?.trim()) {
+		lines.push("## Summary");
+		lines.push("");
+		lines.push(opts.human_summary.trim());
+		lines.push("");
+	}
+	const researchMd = formatResearchBriefMarkdown(opts?.research_brief);
+	if (researchMd) {
+		lines.push(researchMd.trimEnd());
+		lines.push("");
+	}
+	lines.push("## Plan packet");
+	lines.push("");
+	lines.push("```text");
+	for (const line of formatPlanPacketLines(packet, 100)) {
+		lines.push(line);
+	}
+	lines.push("```");
+	lines.push("");
+	if (status === "draft") {
+		lines.push(
+			"Review this file in your editor, then return to the harness TUI to **Approve**, **Request changes**, or **Cancel**.",
+		);
+	} else if (status === "approved") {
+		lines.push(
+			"Approved in the harness TUI. Waiting for `create_plan` to write `plan-packet.yaml`, or run `/harness-plan-commit` if that step failed.",
+		);
+	} else {
+		lines.push(
+			"Plan committed. Next: `/harness-run` to execute (do not pass `--plan` on the happy path).",
+		);
+	}
+	lines.push("");
+	return `${lines.join("\n")}\n`;
+}
+
+export async function writePlanReviewMarkdown(
+	projectRoot: string,
+	runCtx: HarnessRunContext | null,
+	packet: PlanPacketLike,
+	opts?: {
+		human_summary?: string | null;
+		status?: PlanReviewStatus;
+		research_brief?: PlanResearchBrief | null;
+	},
+): Promise<string | null> {
+	const runId = runCtx?.run_id;
+	if (!runId) return null;
+	const reviewPath = canonicalPlanReviewPath(runId, projectRoot);
+	const planPacketPath =
+		runCtx.plan_packet_path ?? canonicalPlanPath(runId, projectRoot);
+	const body = formatPlanPacketMarkdown(packet, {
+		human_summary: opts?.human_summary,
+		status: opts?.status ?? "draft",
+		plan_packet_path: planPacketPath,
+		research_brief: opts?.research_brief,
+	});
+	try {
+		await mkdir(dirname(reviewPath), { recursive: true });
+		await writeFile(reviewPath, body, "utf-8");
+		return reviewPath;
+	} catch {
+		return null;
+	}
+}
+
+interface SessionEntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+		content?: { type?: string; text?: string }[];
+	};
+}
+
+/** Latest plan_packet from drafts, approve_plan tool results, or assistant JSON blocks. */
+export function extractLatestPlanPacketFromEntries(
+	entries: unknown[],
+): { packet: PlanPacketLike; human_summary?: string | null } | null {
+	let found: { packet: PlanPacketLike; human_summary?: string | null } | null =
+		null;
+
+	const consider = (
+		packet: PlanPacketLike | undefined,
+		human_summary?: string | null,
+	) => {
+		if (!packet || typeof packet !== "object") return;
+		if (!packet.plan_id && !packet.scope) return;
+		found = { packet, human_summary: human_summary ?? null };
+	};
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as SessionEntryLike;
+		if (entry.type === "custom" && entry.customType === "harness-plan-draft") {
+			const data = entry.data as {
+				plan_packet?: PlanPacketLike;
+				human_summary?: string | null;
+			};
+			consider(data.plan_packet, data.human_summary);
+			if (found) return found;
+		}
+		if (entry.type === "message" && entry.message?.role === "toolResult") {
+			const toolName = entry.message.toolName;
+			const details = entry.message.details as
+				| {
+						plan_packet?: PlanPacketLike;
+						human_summary?: string;
+				  }
+				| undefined;
+			if (toolName === "approve_plan" && details?.plan_packet) {
+				consider(details.plan_packet, details.human_summary);
+				if (found) return found;
+			}
+		}
+	}
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as SessionEntryLike;
+		if (entry.type !== "message" || entry.message?.role !== "assistant") {
+			continue;
+		}
+		const blocks = entry.message.content ?? [];
+		for (const block of blocks) {
+			if (block.type !== "text" || !block.text) continue;
+			const match = block.text.match(/```json\s*([\s\S]*?)```/i);
+			if (!match) continue;
+			try {
+				const parsed = JSON.parse(match[1]) as {
+					plan_packet?: PlanPacketLike;
+					human_summary?: string;
+				};
+				if (parsed.plan_packet) {
+					consider(parsed.plan_packet, parsed.human_summary);
+					if (found) return found;
+				}
+			} catch {
+				/* ignore malformed assistant JSON */
+			}
+		}
+	}
+
+	return found;
+}
+
+export async function syncPlannerPlanReviewToDisk(
+	projectRoot: string,
+	runCtx: HarnessRunContext | null,
+	entries: unknown[],
+	_opts?: { agentStatus?: string },
+): Promise<string | null> {
+	const draft = extractLatestPlanPacketFromEntries(entries);
+	if (!draft) return null;
+	return writePlanReviewMarkdown(projectRoot, runCtx, draft.packet, {
+		human_summary: draft.human_summary,
+		status: "draft",
+	});
+}
+
+export function formatPlanReviewUserHint(reviewPath: string | null): string {
+	if (!reviewPath) {
+		return "No plan draft was captured yet. If the planner is still clarifying, answer in the subagent or re-run /harness-plan.";
+	}
+	const abs = resolve(reviewPath);
+	return (
+		`Full plan for editor review: ${abs}\n` +
+		`Open this markdown file in VS Code (or your editor), read the scope and acceptance checks, then return to the harness TUI to Approve / Request changes / Cancel.`
+	);
+}