ultimate-pi 0.11.0 → 0.12.0

package/.pi/extensions/debate-orchestrator.ts

@@ -14,16 +14,20 @@
  * }
  */
 
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type DebateParticipant,
+	debatePhaseFromId,
+	isPlanDebateId,
+	PLAN_DEBATE_PARTICIPANTS,
+	POST_EXECUTE_DEBATE_PARTICIPANTS,
+} from "../lib/debate-orchestrator-types.js";
 import { getRunIdFromSession } from "../lib/harness-run-context.js";
 
-type DebateParticipant =
-	| "EvaluatorAgent"
-	| "AdversaryAgent"
-	| "TieBreakerAgent";
 type PolicyDecision = "pass" | "conditional_pass" | "block" | "human_required";
+type DebatePhase = "plan" | "post_execute";
 
 interface RoundPayload {
 	participants: DebateParticipant[];
@@ -46,11 +50,13 @@ interface RoundPayload {
 interface DebateState {
 	run_id: string;
 	debate_id: string;
+	debate_phase: DebatePhase;
 	round_count: number;
 	budget_used: number;
 	max_rounds: number;
 	round_token_cap: number;
 	debate_global_cap: number;
+	last_review_gate_ready?: boolean;
 }
 
 interface BusEnvelope<T = unknown> {
@@ -104,46 +110,39 @@ function getRunId(ctx: {
 	);
 }
 
-async function readRoundCapsFromSchema(): Promise<{
+const PLAN_BUDGET = {
+	max_rounds: 4,
+	round_token_cap: 2000,
+	debate_global_cap: 12000,
+} as const;
+
+const AGGRESSIVE_BUDGET = {
+	max_rounds: 6,
+	round_token_cap: 2500,
+	debate_global_cap: 35000,
+} as const;
+
+function capsForDebate(debateId: string): {
+	name: "plan" | "aggressive";
 	max_rounds: number;
 	round_token_cap: number;
 	debate_global_cap: number;
-}> {
-	try {
-		const roundSchemaPath = join(
-			process.cwd(),
-			".pi",
-			"harness",
-			"specs",
-			"round-result.schema.json",
+} {
+	if (isPlanDebateId(debateId)) {
+		return { name: "plan", ...PLAN_BUDGET };
+	}
+	return { name: "aggressive", ...AGGRESSIVE_BUDGET };
+}
+
+function participantAllowed(participant: string, phase: DebatePhase): boolean {
+	if (phase === "plan") {
+		return (PLAN_DEBATE_PARTICIPANTS as readonly string[]).includes(
+			participant,
 		);
-		const parsed = JSON.parse(await readFile(roundSchemaPath, "utf-8")) as {
-			properties?: {
-				budget_profile?: {
-					properties?: {
-						max_rounds?: { const?: number };
-						round_token_cap?: { const?: number };
-						debate_global_cap?: { const?: number };
-					};
-				};
-			};
-		};
-		return {
-			max_rounds: Number(
-				parsed?.properties?.budget_profile?.properties?.max_rounds?.const ?? 6,
-			),
-			round_token_cap: Number(
-				parsed?.properties?.budget_profile?.properties?.round_token_cap
-					?.const ?? 2500,
-			),
-			debate_global_cap: Number(
-				parsed?.properties?.budget_profile?.properties?.debate_global_cap
-					?.const ?? 35000,
-			),
-		};
-	} catch {
-		return { max_rounds: 6, round_token_cap: 2500, debate_global_cap: 35000 };
 	}
+	return (POST_EXECUTE_DEBATE_PARTICIPANTS as readonly string[]).includes(
+		participant,
+	);
 }
 
 async function writeDebateEvent(
@@ -197,13 +196,18 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 	let lastSeverity = defaultSeverity();
 
 	async function openDebate(runId: string, debateId: string): Promise<void> {
-		const caps = await readRoundCapsFromSchema();
+		const caps = capsForDebate(debateId);
+		const debate_phase = debatePhaseFromId(debateId);
 		state = {
 			run_id: runId,
 			debate_id: debateId,
+			debate_phase,
 			round_count: 0,
 			budget_used: 0,
-			...caps,
+			max_rounds: caps.max_rounds,
+			round_token_cap: caps.round_token_cap,
+			debate_global_cap: caps.debate_global_cap,
+			last_review_gate_ready: false,
 		};
 		pi.appendEntry("harness-debate-state", state);
 		const envelope: BusEnvelope = {
@@ -216,7 +220,8 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			},
 			payload: {
 				opened_at: nowIso(),
-				budget_profile: "aggressive",
+				debate_phase,
+				budget_profile: caps.name,
 			},
 		};
 		pi.appendEntry("harness-debate-envelope", envelope);
@@ -267,6 +272,15 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			return { ok: false, reason: "debate id mismatch" };
 		}
 
+		for (const p of envelope.payload.participants ?? []) {
+			if (!participantAllowed(p, state.debate_phase)) {
+				return {
+					ok: false,
+					reason: `participant ${p} invalid for debate_phase=${state.debate_phase}`,
+				};
+			}
+		}
+
 		const nextRound = state.round_count + 1;
 		if (nextRound > state.max_rounds) {
 			await emitBudgetExhausted("max_rounds_reached");
@@ -310,6 +324,11 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			};
 		}
 
+		const profileName =
+			state.debate_phase === "plan"
+				? ("plan" as const)
+				: ("aggressive" as const);
+
 		const roundRecord = {
 			schema_version: "1.0.0",
 			contract_version: "1.0.0",
@@ -322,7 +341,7 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			evidence_refs: envelope.payload.evidence_refs,
 			token_usage: envelope.payload.token_usage,
 			budget_profile: {
-				name: "aggressive",
+				name: profileName,
 				max_rounds: state.max_rounds,
 				round_token_cap: state.round_token_cap,
 				debate_global_cap: state.debate_global_cap,
@@ -354,12 +373,20 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			),
 		);
 		const decision = decidePolicy(lastSeverity, evidenceScore);
+		const planPhase = state.debate_phase === "plan";
+		const evaluatorPassed = planPhase
+			? Boolean(state.last_review_gate_ready)
+			: true;
+		const debateComplete = planPhase
+			? state.round_count >= state.max_rounds
+			: state.round_count > 0;
 
 		const consensus = {
 			schema_version: "1.0.0",
 			contract_version: "1.0.0",
 			run_id: state.run_id,
 			debate_id: state.debate_id,
+			debate_phase: state.debate_phase,
 			round_count: state.round_count,
 			budget_used: state.budget_used,
 			severity_scores: lastSeverity,
@@ -371,15 +398,25 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 			},
 			confidence_weights: WEIGHTS,
 			evidence_refs: [],
-			strict_gate_prerequisites: {
-				plan_gate_passed: true,
-				execution_completed: true,
-				evaluator_passed: true,
-				adversarial_debate_completed: state.round_count > 0,
-				severity_policy_ok: decision !== "block",
-				benchmark_delta_checks_passed: false,
-				rollback_artifacts_generated: false,
-			},
+			strict_gate_prerequisites: planPhase
+				? {
+						plan_gate_passed: false,
+						execution_completed: false,
+						evaluator_passed: evaluatorPassed,
+						adversarial_debate_completed: debateComplete,
+						severity_policy_ok: decision !== "block",
+						benchmark_delta_checks_passed: false,
+						rollback_artifacts_generated: false,
+					}
+				: {
+						plan_gate_passed: true,
+						execution_completed: true,
+						evaluator_passed: true,
+						adversarial_debate_completed: debateComplete,
+						severity_policy_ok: decision !== "block",
+						benchmark_delta_checks_passed: false,
+						rollback_artifacts_generated: false,
+					},
 			policy_decision: decision,
 			rationale,
 		};

package/.pi/extensions/harness-plan-approval.ts

@@ -236,7 +236,7 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 		name: "create_plan",
 		label: "Create Plan",
 		description:
-			"Write the approved PlanPacket to plan-packet.json for this harness run. Call only after approve_plan (Approve). Do not use write/edit.",
+			"Write the approved PlanPacket to plan-packet.yaml for this harness run. Call only after approve_plan (Approve). Do not use write/edit.",
 		promptSnippet: CREATE_PLAN_SNIPPET,
 		promptGuidelines: CREATE_PLAN_GUIDELINES,
 		parameters: CreatePlanParamsSchema,
@@ -298,7 +298,7 @@ export default function harnessPlanApproval(pi: ExtensionAPI) {
 			return new Text(
 				theme.fg(
 					"success",
-					`Wrote ${details?.plan_path ?? "plan-packet.json"}`,
+					`Wrote ${details?.plan_path ?? "plan-packet.yaml"}`,
 				),
 				0,
 				0,

package/.pi/extensions/harness-run-context.ts

@@ -5,13 +5,16 @@
  * in before_agent_start so trace-recorder reuses it on agent_start.
  */
 
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 import {
 	canonicalPlanPath,
 	createFreshRunContext,
 	driftGateActive,
 	extractCompletionStatuses,
+	extractWritePathFromToolInput,
 	formatActivePlanBlock,
 	formatPlanContextBlock,
 	getLatestHarnessTurn,
@@ -27,10 +30,12 @@ import {
 	isHarnessBootstrapPrompt,
 	isNewTaskPlanBlocked,
 	isPlanApprovalAskUser,
+	isPlanPhaseScopedWrite,
 	isStaleActiveRunPointer,
 	loadProjectActiveRun,
 	loadRunContextFromDisk,
 	nextStepAfterOutcome,
+	normalizeHarnessPath,
 	nowIso,
 	type PlanPacketSummary,
 	parseHarnessSlashInput,
@@ -45,6 +50,11 @@ import {
 	validatePlanOverridePath,
 	validatePlanPacket,
 } from "../lib/harness-run-context.js";
+import {
+	normalizeHarnessYamlContent,
+	parseStructuredDocument,
+	writeYamlFile,
+} from "../lib/harness-yaml.js";
 
 interface SessionEntryLike {
 	type?: string;
@@ -84,6 +94,32 @@ function appendHarnessTurn(pi: ExtensionAPI, turn: HarnessTurnEntry): void {
 	});
 }
 
+async function coerceScopedHarnessYamlWrite(
+	event: { toolName: string; input: Record<string, unknown> },
+	runCtx: HarnessRunContext,
+	projectRoot: string,
+): Promise<{ block: true; reason: string } | undefined> {
+	if (event.toolName !== "write") return undefined;
+	const target = extractWritePathFromToolInput(event.input);
+	if (!target.endsWith(".yaml") && !target.endsWith(".yml")) return undefined;
+	const scoped = await isPlanPhaseScopedWrite(target, runCtx, projectRoot);
+	if (!scoped) return undefined;
+	const content = event.input.content;
+	if (typeof content !== "string") return undefined;
+	try {
+		event.input.content = normalizeHarnessYamlContent(content, target);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return {
+			block: true,
+			reason:
+				`harness-run-context: ${target} must be canonical YAML, not embedded JSON. ` +
+				`Use write_harness_yaml with the subagent JSON/YAML block, or paste valid YAML. (${msg})`,
+		};
+	}
+	return undefined;
+}
+
 function syncPolicyFromPlan(
 	pi: ExtensionAPI,
 	entries: unknown[],
@@ -583,7 +619,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 				activeCtx.last_outcome = "needs_clarification";
 				activeCtx.last_completed_step = "plan";
 				const msg =
-					"Plan file exists but user approval was not recorded. Planner must call approve_plan (or bridged ask_user Approve) before writing plan-packet.json.";
+					"Plan file exists but user approval was not recorded. Planner must call approve_plan (or bridged ask_user Approve) before writing plan-packet.yaml.";
 				if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 				else
 					pi.sendMessage({
@@ -671,6 +707,18 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "write") {
+			const entries = getEntries(ctx);
+			const runCtx = getLatestRunContext(entries) ?? activeCtx;
+			if (runCtx) {
+				const blocked = await coerceScopedHarnessYamlWrite(
+					event,
+					runCtx,
+					process.cwd(),
+				);
+				if (blocked) return blocked;
+			}
+		}
 		if (activeCtx?.plan_packet_path) {
 			const entries = getEntries(ctx);
 			if (hasPlanUserApproval(entries, { sincePlanCommand: true })) {
@@ -707,11 +755,11 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 				(event.input as { filePath?: string }).filePath ??
 				"",
 		);
-		if (target.includes("plan-packet.json")) {
+		if (target.includes("plan-packet.yaml")) {
 			return {
 				block: true,
 				reason:
-					"harness-run-context: plan-packet.json is read-only in evaluate/adversary phases.",
+					"harness-run-context: plan-packet.yaml is read-only in evaluate/adversary phases.",
 			};
 		}
 		return undefined;
@@ -792,7 +840,7 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 
 	pi.registerCommand("harness-plan-commit", {
 		description:
-			"Write approved plan-packet.json to the active run (requires harness-plan-approval)",
+			"Write approved plan-packet.yaml to the active run (requires harness-plan-approval)",
 		handler: async (args, ctx) => {
 			const projectRoot = process.cwd();
 			const entries = getEntries(ctx);
@@ -867,6 +915,98 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "write_harness_yaml",
+		label: "Write Harness YAML",
+		description:
+			"Write a plan-phase harness artifact as canonical YAML (parses subagent JSON or YAML, never embeds JSON in .yaml files).",
+		promptSnippet:
+			"Persist plan artifacts (decomposition, hypothesis, stack, review rounds) as real YAML.",
+		promptGuidelines: [
+			"Use write_harness_yaml for all artifacts/*.yaml and research-brief.yaml updates during /harness-plan.",
+			"Pass the subagent fenced json or yaml block as content; the tool converts to YAML on disk.",
+			"Do not use write with stringified JSON for .yaml paths.",
+			"plan-packet.yaml after approval: prefer create_plan; write_harness_yaml is for drafts and side artifacts only.",
+		],
+		parameters: Type.Object({
+			path: Type.String({
+				description:
+					"Path under the active run, e.g. artifacts/decomposition.yaml or research-brief.yaml",
+			}),
+			content: Type.String({
+				description:
+					"YAML or JSON document (fenced or raw) matching the artifact schema",
+			}),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const entries = getEntries(ctx);
+			const runCtx = getLatestRunContext(entries) ?? activeCtx;
+			if (!runCtx?.run_id) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: 'No active harness run. Run /harness-plan "<task>" first.',
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+			const pathArg = String((params as { path?: string }).path ?? "").trim();
+			const content = String((params as { content?: string }).content ?? "");
+			if (!pathArg || !content.trim()) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "write_harness_yaml requires path and content.",
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+			const projectRoot = process.cwd();
+			const absPath = normalizeHarnessPath(pathArg, projectRoot);
+			const scoped = await isPlanPhaseScopedWrite(absPath, runCtx, projectRoot);
+			if (!scoped) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Path not allowed: ${pathArg}. Must be under .pi/harness/runs/${runCtx.run_id}/ (artifacts/*.yaml, research-brief.yaml, etc.).`,
+						},
+					],
+					details: { path: pathArg },
+					isError: true,
+				};
+			}
+			let doc: unknown;
+			try {
+				doc = parseStructuredDocument(content, pathArg);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: msg }],
+					details: { path: pathArg },
+					isError: true,
+				};
+			}
+			await mkdir(dirname(absPath), { recursive: true });
+			await writeYamlFile(absPath, doc);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Wrote ${pathArg} as canonical YAML.`,
+					},
+				],
+				details: { path: absPath },
+			};
+		},
+	});
+
 	pi.registerCommand("harness-use-run", {
 		description: "Point this session at an existing run directory (recovery)",
 		handler: async (args, ctx) => {

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

@@ -1,10 +1,10 @@
 /**
- * harness-subagents — package-resolved agents, blackboard, observation-bus handoffs.
+ * harness-subagents — vendored pi-subagents with ultimate-pi discovery and policy gates.
  */
 
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
 import { getHarnessPackageRoot } from "./lib/harness-paths.js";
-import { createHarnessSubagentsExtension } from "./lib/harness-subagents/vendored/index.js";
+import { createHarnessSubagentsExtension } from "./lib/harness-subagents-bridge.js";
 
 // @ts-expect-error pi extensions run as ESM
 const MODULE_URL = import.meta.url;

package/.pi/extensions/lib/harness-posthog.ts

@@ -22,7 +22,12 @@ export type HarnessPostHogEventName =
 	| "harness_drift_report"
 	| "harness_eval_verdict"
 	| "harness_sentrux_signal"
-	| "harness_observation";
+	| "harness_observation"
+	| "harness_subagent_spawned"
+	| "harness_subagent_completed"
+	| "harness_subagent_result_wait"
+	| "harness_subagent_setup"
+	| "harness_blackboard_op";
 
 const SCHEMA_VERSION = "1.0.0";
 

package/.pi/extensions/lib/harness-spawn-budget.ts

@@ -0,0 +1,75 @@
+/**
+ * Harness subagent spawn caps (subprocess model).
+ */
+
+export const HARNESS_MAX_ACTIVE_SUBAGENTS = 8;
+export const HARNESS_MAX_SUBAGENT_SPAWNS_PER_SESSION = 12;
+
+export function isHarnessAgentType(type: string): boolean {
+	return type.startsWith("harness/");
+}
+
+export interface SpawnBudgetState {
+	active: number;
+	totalHarnessSpawns: number;
+}
+
+export function createSpawnBudgetState(): SpawnBudgetState {
+	return { active: 0, totalHarnessSpawns: 0 };
+}
+
+export function countHarnessAgentsInRequest(params: {
+	agent?: string;
+	tasks?: { agent: string }[];
+	chain?: { agent: string }[];
+	aggregator?: { agent: string };
+}): { harnessCount: number; agents: string[] } {
+	const agents: string[] = [];
+	if (params.agent) agents.push(params.agent);
+	if (params.tasks) for (const t of params.tasks) agents.push(t.agent);
+	if (params.chain) for (const c of params.chain) agents.push(c.agent);
+	if (params.aggregator) agents.push(params.aggregator.agent);
+	const harness = agents.filter(isHarnessAgentType);
+	return { harnessCount: harness.length, agents: harness };
+}
+
+export function checkHarnessSpawnBudget(
+	state: SpawnBudgetState,
+	incomingHarnessTasks: number,
+): { ok: boolean; message?: string } {
+	if (state.active + incomingHarnessTasks > HARNESS_MAX_ACTIVE_SUBAGENTS) {
+		return {
+			ok: false,
+			message:
+				`Harness subagent limit reached (${state.active} active + ${incomingHarnessTasks} requested > ${HARNESS_MAX_ACTIVE_SUBAGENTS}). ` +
+				`Wait for in-flight subagent calls to finish before spawning more.`,
+		};
+	}
+	if (
+		state.totalHarnessSpawns + incomingHarnessTasks >
+		HARNESS_MAX_SUBAGENT_SPAWNS_PER_SESSION
+	) {
+		return {
+			ok: false,
+			message:
+				`Harness subagent spawn cap reached (${state.totalHarnessSpawns + incomingHarnessTasks}/${HARNESS_MAX_SUBAGENT_SPAWNS_PER_SESSION} this session). ` +
+				`Finish the current harness phase or start a new session.`,
+		};
+	}
+	return { ok: true };
+}
+
+export function recordSpawnStart(
+	state: SpawnBudgetState,
+	harnessCount: number,
+): void {
+	state.active += harnessCount;
+	state.totalHarnessSpawns += harnessCount;
+}
+
+export function recordSpawnEnd(
+	state: SpawnBudgetState,
+	harnessCount: number,
+): void {
+	state.active = Math.max(0, state.active - harnessCount);
+}