ultimate-pi 0.13.0 → 0.14.0

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

@@ -1,103 +1,24 @@
 /**
  * debate-orchestrator — headless debate bus (pi-messenger-inspired semantics).
  *
- * No additional UI surface:
- * - transport is extension custom entries + debate artifacts on disk
- * - command interface is machine-friendly (`/harness-debate-*`)
- *
- * Protocol envelope:
- * {
- *   protocol: "pi-debate-bus/v1",
- *   kind: "open" | "round" | "consensus" | "budget_exhausted",
- *   correlation: { run_id, debate_id, round_index?, sender },
- *   payload: { ... }
- * }
+ * Commands mirror harness_debate_* tools; shared state lives in debate-bus-core.
  */
 
-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 PolicyDecision = "pass" | "conditional_pass" | "block" | "human_required";
-type DebatePhase = "plan" | "post_execute";
-
-interface RoundPayload {
-	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;
-	};
-}
-
-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> {
-	protocol: "pi-debate-bus/v1";
-	kind: "open" | "round" | "consensus" | "budget_exhausted";
-	correlation: {
-		run_id: string;
-		debate_id: string;
-		round_index?: number;
-		sender: DebateParticipant | "system";
-	};
-	payload: T;
-}
-
-const DEBATES_DIR = join(process.cwd(), ".pi", "harness", "debates");
-const WEIGHTS = {
-	claim_quality: 0.2,
-	reproducibility: 0.4,
-	agreement: 0.4,
-};
-const THRESHOLDS = {
-	correctness: 0.7,
-	security: 0.7,
-	architecture: 0.8,
-	test_integrity: 0.8,
-};
-const HARD_STOP_DEBATE_CAPS = process.env.HARNESS_DEBATE_HARD_STOP === "true";
-
-function nowIso(): string {
-	return new Date().toISOString();
-}
-
-function toSafeFloat(value: unknown): number {
-	const n = Number(value);
-	if (Number.isNaN(n) || !Number.isFinite(n)) return 0;
-	return Math.max(0, Math.min(1, n));
-}
-
-async function ensureDebatesDir(): Promise<void> {
-	await mkdir(DEBATES_DIR, { recursive: true });
-}
+import {
+	acceptDebateRound,
+	finalizeDebateConsensus,
+	openDebateBus,
+	parseRoundEnvelope,
+} from "./lib/debate-bus-core.js";
+import {
+	getDebateState,
+	restoreDebateStateFromEntry,
+} from "./lib/debate-bus-state.js";
+import { normalizePlanDebateId } from "./lib/plan-debate-id.js";
+import { initPlanMessenger } from "./lib/plan-messenger.js";
 
 function getRunId(ctx: {
 	sessionManager: { getEntries(): unknown[]; getSessionId(): string };
@@ -110,339 +31,11 @@ function getRunId(ctx: {
 	);
 }
 
-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;
-} {
-	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,
-		);
-	}
-	return (POST_EXECUTE_DEBATE_PARTICIPANTS as readonly string[]).includes(
-		participant,
-	);
-}
-
-async function writeDebateEvent(
-	debateId: string,
-	event: unknown,
-): Promise<void> {
-	await ensureDebatesDir();
-	const path = join(DEBATES_DIR, `${debateId}.jsonl`);
-	await appendFile(path, `${JSON.stringify(event)}\n`, "utf-8");
-}
-
-function defaultSeverity(): {
-	correctness: number;
-	security: number;
-	architecture: number;
-	test_integrity: number;
-} {
-	return { correctness: 0, security: 0, architecture: 0, test_integrity: 0 };
-}
-
-function decidePolicy(
-	severity: ReturnType<typeof defaultSeverity>,
-	minEvidenceConfidence: number,
-): PolicyDecision {
-	if (
-		severity.security >= THRESHOLDS.security ||
-		severity.correctness >= THRESHOLDS.correctness ||
-		severity.architecture >= THRESHOLDS.architecture ||
-		severity.test_integrity >= THRESHOLDS.test_integrity
-	) {
-		return "block";
-	}
-	if (minEvidenceConfidence < 0.55) return "human_required";
-	if (minEvidenceConfidence < 0.75) return "conditional_pass";
-	return "pass";
-}
-
-function parseEnvelope(raw: string): BusEnvelope<RoundPayload> | null {
-	try {
-		const parsed = JSON.parse(raw) as BusEnvelope<RoundPayload>;
-		if (parsed?.protocol !== "pi-debate-bus/v1") return null;
-		if (parsed?.kind !== "round") return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
-
 export default function debateOrchestrator(pi: ExtensionAPI) {
-	let state: DebateState | null = null;
-	let lastSeverity = defaultSeverity();
-
-	async function openDebate(runId: string, debateId: string): Promise<void> {
-		const caps = capsForDebate(debateId);
-		const debate_phase = debatePhaseFromId(debateId);
-		state = {
-			run_id: runId,
-			debate_id: debateId,
-			debate_phase,
-			round_count: 0,
-			budget_used: 0,
-			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 = {
-			protocol: "pi-debate-bus/v1",
-			kind: "open",
-			correlation: {
-				run_id: runId,
-				debate_id: debateId,
-				sender: "system",
-			},
-			payload: {
-				opened_at: nowIso(),
-				debate_phase,
-				budget_profile: caps.name,
-			},
-		};
-		pi.appendEntry("harness-debate-envelope", envelope);
-		await writeDebateEvent(debateId, envelope);
-	}
-
-	async function emitBudgetExhausted(reason: string): Promise<void> {
-		if (!state) return;
-		const envelope: BusEnvelope = {
-			protocol: "pi-debate-bus/v1",
-			kind: "budget_exhausted",
-			correlation: {
-				run_id: state.run_id,
-				debate_id: state.debate_id,
-				round_index: state.round_count,
-				sender: "system",
-			},
-			payload: {
-				schema_version: "1.0.0",
-				contract_version: "1.0.0",
-				event_type: "budget_exhausted",
-				run_id: state.run_id,
-				debate_id: state.debate_id,
-				round_count: state.round_count,
-				budget_used: state.budget_used,
-				exhaustion_reason: reason,
-				caps: {
-					max_rounds: state.max_rounds,
-					round_token_cap: state.round_token_cap,
-					debate_global_cap: state.debate_global_cap,
-				},
-				minimum_evidence_confidence: 0.6,
-				default_policy_outcome: "block",
-				human_override_allowed: true,
-			},
-		};
-		pi.appendEntry("harness-debate-envelope", envelope);
-		pi.appendEntry("harness-budget-exhausted", envelope.payload);
-		await writeDebateEvent(state.debate_id, envelope);
-	}
-
-	async function acceptRound(envelope: BusEnvelope<RoundPayload>): Promise<{
-		ok: boolean;
-		reason?: string;
-	}> {
-		if (!state) return { ok: false, reason: "no active debate" };
-		if (state.debate_id !== envelope.correlation.debate_id) {
-			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");
-			if (HARD_STOP_DEBATE_CAPS) {
-				return { ok: false, reason: "max rounds reached" };
-			}
-		}
-
-		const perAgent = envelope.payload.token_usage?.per_agent ?? {};
-		for (const [agent, tokens] of Object.entries(perAgent)) {
-			if (Number(tokens) > state.round_token_cap) {
-				await emitBudgetExhausted("round_token_cap_exceeded");
-				if (HARD_STOP_DEBATE_CAPS) {
-					return { ok: false, reason: `round cap exceeded by ${agent}` };
-				}
-			}
-		}
-
-		const roundTotal = Number(envelope.payload.token_usage?.round_total ?? 0);
-		if (state.budget_used + roundTotal > state.debate_global_cap) {
-			await emitBudgetExhausted("debate_global_cap_exceeded");
-			if (HARD_STOP_DEBATE_CAPS) {
-				return { ok: false, reason: "global cap exceeded" };
-			}
-		}
-
-		state.round_count = nextRound;
-		state.budget_used += roundTotal;
-		pi.appendEntry("harness-debate-state", state);
-
-		if (envelope.payload.severity_scores) {
-			lastSeverity = {
-				correctness: toSafeFloat(envelope.payload.severity_scores.correctness),
-				security: toSafeFloat(envelope.payload.severity_scores.security),
-				architecture: toSafeFloat(
-					envelope.payload.severity_scores.architecture,
-				),
-				test_integrity: toSafeFloat(
-					envelope.payload.severity_scores.test_integrity,
-				),
-			};
-		}
-
-		const profileName =
-			state.debate_phase === "plan"
-				? ("plan" as const)
-				: ("aggressive" as const);
-
-		const roundRecord = {
-			schema_version: "1.0.0",
-			contract_version: "1.0.0",
-			run_id: state.run_id,
-			debate_id: state.debate_id,
-			round_index: state.round_count,
-			participants: envelope.payload.participants,
-			claims: envelope.payload.claims,
-			rebuttals: envelope.payload.rebuttals,
-			evidence_refs: envelope.payload.evidence_refs,
-			token_usage: envelope.payload.token_usage,
-			budget_profile: {
-				name: profileName,
-				max_rounds: state.max_rounds,
-				round_token_cap: state.round_token_cap,
-				debate_global_cap: state.debate_global_cap,
-			},
-			consensus_delta: Number(envelope.payload.consensus_delta ?? 0),
-		};
-		pi.appendEntry("harness-round-result", roundRecord);
-		pi.appendEntry("harness-debate-envelope", envelope);
-		await writeDebateEvent(state.debate_id, envelope);
-		return { ok: true };
-	}
-
-	async function finalizeConsensus(
-		rationale: string,
-	): Promise<PolicyDecision | null> {
-		if (!state) return null;
-		const evidenceScore = Math.max(
-			0,
-			Math.min(
-				1,
-				lastSeverity.correctness * WEIGHTS.claim_quality +
-					(1 - Math.max(lastSeverity.security, lastSeverity.test_integrity)) *
-						WEIGHTS.reproducibility +
-					Math.max(
-						0,
-						1 - Math.abs(lastSeverity.architecture - lastSeverity.correctness),
-					) *
-						WEIGHTS.agreement,
-			),
-		);
-		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,
-			severity_thresholds: {
-				correctness_block_at: THRESHOLDS.correctness,
-				security_block_at: THRESHOLDS.security,
-				architecture_block_at: THRESHOLDS.architecture,
-				test_integrity_block_at: THRESHOLDS.test_integrity,
-			},
-			confidence_weights: WEIGHTS,
-			evidence_refs: [],
-			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,
-		};
-
-		const envelope: BusEnvelope = {
-			protocol: "pi-debate-bus/v1",
-			kind: "consensus",
-			correlation: {
-				run_id: state.run_id,
-				debate_id: state.debate_id,
-				round_index: state.round_count,
-				sender: "system",
-			},
-			payload: consensus,
-		};
-
-		await writeFile(
-			join(DEBATES_DIR, `${state.debate_id}.consensus.json`),
-			`${JSON.stringify(consensus, null, 2)}\n`,
-			"utf-8",
-		);
-		pi.appendEntry("harness-consensus-packet", consensus);
-		pi.appendEntry("harness-debate-envelope", envelope);
-		await writeDebateEvent(state.debate_id, envelope);
-		return decision;
-	}
+	const hooks = {
+		appendEntry: (customType: string, data: unknown) =>
+			pi.appendEntry(customType, data),
+	};
 
 	pi.on("session_start", async (_event, ctx) => {
 		const entries = ctx.sessionManager.getEntries();
@@ -452,7 +45,7 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 				entry.type === "custom" &&
 				entry.customType === "harness-debate-state"
 			) {
-				state = entry.data as DebateState;
+				restoreDebateStateFromEntry(entry.data);
 				break;
 			}
 		}
@@ -461,13 +54,21 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 	pi.registerCommand("harness-debate-open", {
 		description: "Open a headless debate session",
 		handler: async (args, ctx) => {
+			const runId = getRunId(ctx);
 			const trimmed = args.trim();
-			let debateId = trimmed;
-			if (!debateId) debateId = `debate-${Date.now()}`;
-			await openDebate(getRunId(ctx), debateId);
+			const { debateId, warning } = normalizePlanDebateId(trimmed, runId);
+			await openDebateBus(runId, debateId, hooks);
+			if (debateId.startsWith("plan-")) {
+				await initPlanMessenger(
+					join(process.cwd(), ".pi", "harness", "runs", runId),
+					{ runId, debateId },
+				);
+			}
 			pi.sendMessage({
 				customType: "harness-debate-opened",
-				content: `Debate opened: ${debateId}`,
+				content: warning
+					? `Debate opened: ${debateId} (${warning})`
+					: `Debate opened: ${debateId}`,
 				display: false,
 			});
 		},
@@ -476,10 +77,12 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 	pi.registerCommand("harness-debate-round", {
 		description: "Submit a debate round envelope JSON",
 		handler: async (args, ctx) => {
-			if (!state) {
-				await openDebate(getRunId(ctx), `debate-${Date.now()}`);
+			if (!getDebateState()) {
+				const runId = getRunId(ctx);
+				const { debateId } = normalizePlanDebateId("", runId);
+				await openDebateBus(runId, debateId, hooks);
 			}
-			const envelope = parseEnvelope(args.trim());
+			const envelope = parseRoundEnvelope(args.trim());
 			if (!envelope) {
 				pi.sendMessage({
 					customType: "harness-debate-round-error",
@@ -489,7 +92,7 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 				});
 				return;
 			}
-			const result = await acceptRound(envelope);
+			const result = await acceptDebateRound(envelope, hooks);
 			if (!result.ok) {
 				pi.sendMessage({
 					customType: "harness-debate-round-rejected",
@@ -503,7 +106,7 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 	pi.registerCommand("harness-debate-consensus", {
 		description: "Finalize debate and emit consensus packet",
 		handler: async (args) => {
-			if (!state) {
+			if (!getDebateState()) {
 				pi.sendMessage({
 					customType: "harness-debate-consensus-error",
 					content: "No active debate to finalize.",
@@ -511,8 +114,9 @@ export default function debateOrchestrator(pi: ExtensionAPI) {
 				});
 				return;
 			}
-			const decision = await finalizeConsensus(
+			const decision = await finalizeDebateConsensus(
 				args.trim() || "Consensus generated by debate-orchestrator.",
+				hooks,
 			);
 			pi.sendMessage({
 				customType: "harness-debate-consensus",