ultimate-pi 0.11.0 → 0.12.0

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

@@ -0,0 +1,123 @@
+/**
+ * Resolve concrete LLM credentials for harness subagent subprocesses.
+ *
+ * Parent sessions often use `router/auto` (pi-model-router). Subagents run with
+ * `--no-extensions`, so they cannot use the logical router provider — they need
+ * a real provider/model plus that provider's API key.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentConfig } from "../../../vendor/pi-subagents/src/agents.js";
+
+const ROUTER_SENTINEL_KEY = "pi-model-router";
+const SENTINEL_API_KEYS = new Set([ROUTER_SENTINEL_KEY, "<authenticated>"]);
+
+type RouterTier = "high" | "medium" | "low";
+
+interface ModelRouterJson {
+	defaultProfile?: string;
+	profiles?: Record<string, Partial<Record<RouterTier, { model?: string }>>>;
+}
+
+export function isUsableApiKey(key: string | undefined): key is string {
+	return Boolean(key && !SENTINEL_API_KEYS.has(key));
+}
+
+export function parseModelRef(
+	ref: string,
+): { provider: string; modelId: string } | null {
+	const slash = ref.indexOf("/");
+	if (slash <= 0) return null;
+	const provider = ref.slice(0, slash).trim();
+	const modelId = ref.slice(slash + 1).trim();
+	if (!provider || !modelId) return null;
+	return { provider, modelId };
+}
+
+export function thinkingToRouterTier(thinking?: string): RouterTier {
+	if (thinking === "high" || thinking === "xhigh") return "high";
+	if (thinking === "off" || thinking === "minimal" || thinking === "low") {
+		return "low";
+	}
+	return "medium";
+}
+
+/** Map router profile tier → concrete `provider/model` from `.pi/model-router.json`. */
+export function resolveRouterConcreteModelRef(
+	cwd: string,
+	profileId: string,
+	tier: RouterTier,
+): string | undefined {
+	const path = join(cwd, ".pi", "model-router.json");
+	if (!existsSync(path)) return undefined;
+	let raw: ModelRouterJson;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8")) as ModelRouterJson;
+	} catch {
+		return undefined;
+	}
+	const profiles = raw.profiles;
+	if (!profiles) return undefined;
+	const profile =
+		profiles[profileId] ??
+		profiles[raw.defaultProfile ?? "auto"] ??
+		profiles.auto;
+	const model = profile?.[tier]?.model;
+	return typeof model === "string" && model.includes("/") ? model : undefined;
+}
+
+export interface ConcreteSubagentModel {
+	modelRef: string;
+	provider: string;
+	modelId: string;
+	routerProfile?: string;
+	routerTier?: RouterTier;
+}
+
+/**
+ * Pick the subprocess model ref before resolving API keys.
+ * Never returns `router/*` — always a concrete provider.
+ */
+export function resolveConcreteSubagentModel(
+	cwd: string,
+	parentModel: { provider: string; id: string } | undefined,
+	agent: AgentConfig,
+): ConcreteSubagentModel | undefined {
+	if (agent.model && !agent.model.startsWith("router/")) {
+		const parsed = parseModelRef(agent.model);
+		if (parsed) {
+			return { modelRef: agent.model, ...parsed };
+		}
+	}
+
+	const parentIsRouter = parentModel?.provider === "router";
+	const agentIsRouter = Boolean(agent.model?.startsWith("router/"));
+
+	if (!parentIsRouter && !agentIsRouter) {
+		if (parentModel && parentModel.provider !== "router") {
+			return {
+				modelRef: `${parentModel.provider}/${parentModel.id}`,
+				provider: parentModel.provider,
+				modelId: parentModel.id,
+			};
+		}
+		return undefined;
+	}
+
+	const profileId =
+		agentIsRouter && agent.model
+			? agent.model.slice("router/".length)
+			: (parentModel?.id ?? "auto");
+	const tier = thinkingToRouterTier(agent.thinking);
+	const concrete = resolveRouterConcreteModelRef(cwd, profileId, tier);
+	if (!concrete) return undefined;
+	const parsed = parseModelRef(concrete);
+	if (!parsed || parsed.provider === "router") return undefined;
+	return {
+		modelRef: concrete,
+		...parsed,
+		routerProfile: profileId,
+		routerTier: tier,
+	};
+}

package/.pi/extensions/lib/{harness-subagents/harness-subagent-policy.ts → harness-subagent-policy.ts}

@@ -56,17 +56,15 @@ const READ_ONLY_KINDS = new Set<HarnessAgentKind>([
 
 export function isHarnessPlanningAgent(agentType: string): boolean {
 	const id = agentType.replace(/^harness\//, "");
-	return id === "planner" || id.startsWith("planning/");
+	return id.startsWith("planning/");
 }
 
 export function classifyHarnessAgent(agentType: string): HarnessAgentKind {
 	const id = agentType.replace(/^harness\//, "");
-	if (id.startsWith("planning/") || id === "planner") {
+	if (id.startsWith("planning/")) {
 		return "planner";
 	}
 	switch (id) {
-		case "planner":
-			return "planner";
 		case "executor":
 			return "executor";
 		case "evaluator":
@@ -123,7 +121,7 @@ export function evaluateHarnessSubagentToolCall(
 	if (MUTATING_TOOLS.has(toolName)) {
 		return {
 			action: "block",
-			reason: `harness-subagent-policy: ${toolName} blocked for harness/${kind} (read-only phase agent). Use create_plan after approve_plan instead of write/edit.`,
+			reason: `harness-subagent-policy: ${toolName} blocked for harness/${kind} (read-only phase agent).`,
 		};
 	}
 
@@ -151,7 +149,6 @@ export function evaluateHarnessSubagentToolCall(
 	return { action: "allow" };
 }
 
-/** Policy phase hint seeded into subagent system prompt appendix when extensions load policy-gate. */
 export function harnessSubagentPhaseHint(agentType: string): string | null {
 	if (isHarnessPlanningAgent(agentType)) {
 		return "plan";

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,7 @@ 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 =
@@ -17,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 {
@@ -89,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}` };

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

@@ -245,7 +245,7 @@ export function formatPlanPacketMarkdown(
 		);
 	} else if (status === "approved") {
 		lines.push(
-			"Approved in the harness TUI. Waiting for `create_plan` to write `plan-packet.json`, or run `/harness-plan-commit` if that step failed.",
+			"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(

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

@@ -7,11 +7,17 @@ export const DEFAULT_PLAN_APPROVAL_OPTIONS = [
 	"Cancel",
 ] as const;
 
-/** Optional Darwin research artifacts from /harness-plan (not persisted in plan-packet.json). */
+/** Optional Darwin research artifacts from /harness-plan (research-brief.yaml, not in plan-packet). */
 export interface PlanResearchBrief {
 	decomposition?: Record<string, unknown> | null;
 	hypothesis?: Record<string, unknown> | null;
 	eval?: Record<string, unknown> | null;
+	stack?: Record<string, unknown> | null;
+	debate?: {
+		rounds?: Record<string, unknown>[];
+		hypothesis_validations?: Record<string, unknown>[];
+	} | null;
+	dag_validation?: Record<string, unknown> | null;
 }
 
 export interface ApprovePlanParams {

package/.pi/extensions/lib/plan-debate-envelope.ts

@@ -0,0 +1,84 @@
+/**
+ * Plan Review Gate — convert integrator YAML to debate bus round JSON.
+ */
+
+import type { DebateParticipant } from "../../lib/debate-orchestrator-types.js";
+
+export interface PlanReviewRoundDraft {
+	schema_version: string;
+	round_index: number;
+	debate_round_focus?: string;
+	round_summary?: string;
+	validation_summary?: string;
+	adversary_summary?: string;
+	disputes?: string[];
+	recommended_packet_patches?: Array<{ path: string; value: unknown }>;
+	review_gate_ready?: boolean;
+	participants?: DebateParticipant[];
+	claims?: string[];
+	rebuttals?: string[];
+	evidence_refs?: string[];
+	token_usage?: {
+		per_agent: Record<string, number>;
+		round_total: number;
+	};
+	consensus_delta?: number;
+	severity_scores?: {
+		correctness: number;
+		security: number;
+		architecture: number;
+		test_integrity: number;
+	};
+}
+
+export function buildPlanReviewRoundEnvelope(
+	draft: PlanReviewRoundDraft,
+	opts: { runId: string; debateId: string },
+): {
+	protocol: "pi-debate-bus/v1";
+	kind: "round";
+	correlation: {
+		run_id: string;
+		debate_id: string;
+		round_index: number;
+		sender: DebateParticipant;
+	};
+	payload: {
+		participants: DebateParticipant[];
+		claims: string[];
+		rebuttals: string[];
+		evidence_refs: string[];
+		token_usage: { per_agent: Record<string, number>; round_total: number };
+		consensus_delta: number;
+		severity_scores?: PlanReviewRoundDraft["severity_scores"];
+	};
+} {
+	const participants = (draft.participants ?? [
+		"PlanEvaluatorAgent",
+		"PlanAdversaryAgent",
+		"ReviewIntegratorAgent",
+	]) as DebateParticipant[];
+
+	return {
+		protocol: "pi-debate-bus/v1",
+		kind: "round",
+		correlation: {
+			run_id: opts.runId,
+			debate_id: opts.debateId,
+			round_index: draft.round_index,
+			sender: "ReviewIntegratorAgent",
+		},
+		payload: {
+			participants,
+			claims: draft.claims ?? [draft.round_summary ?? "review round"],
+			rebuttals: draft.rebuttals ?? draft.disputes ?? [],
+			evidence_refs: draft.evidence_refs ?? [],
+			token_usage: draft.token_usage ?? {
+				per_agent: { ReviewIntegratorAgent: 0 },
+				round_total: 0,
+			},
+			consensus_delta: draft.consensus_delta ?? 0,
+			severity_scores: draft.severity_scores,
+		},
+	};
+}

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

@@ -7,6 +7,7 @@ export const SUBAGENT_BLOCKED_TOOLS = new Set([
 	"get_subagent_result",
 	"steer_subagent",
 	"blackboard",
+	"subagent",
 ]);
 
 const ASK_USER_ALLOWED_AGENT_TYPES = new Set([

package/.pi/extensions/policy-gate.ts

@@ -243,7 +243,7 @@ export default function policyGate(pi: ExtensionAPI) {
 
 		const planPhaseHint =
 			state.phase === "plan"
-				? "\nPlan phase: scouts → decompose → hypothesis via harness/planning/*; parent builds PlanPacket, ask_user on fork, parallel plan-adversary + hypothesis-eval, approve_plan (optional research_brief), then create_plan (never write plan-packet.json directly)."
+				? "\nPlan phase: scouts → decompose → hypothesis → stack-researcher → execution-plan-author → validate-plan-dag → 4-round plan debate → approve_plan → create_plan (YAML plan-packet.yaml). Post-execute: /harness-critic."
 				: "";
 
 		return {