ultimate-pi 0.15.0 → 0.17.0

package/.pi/extensions/harness-debate-tools.ts

@@ -8,6 +8,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { parse as parseYaml } from "yaml";
 import type { DebateParticipant } from "../lib/debate-orchestrator-types.js";
+import {
+	extractLastSubmitCall,
+	type MessageLike,
+} from "../lib/harness-agent-output.js";
 import {
 	getLatestRunContext,
 	getRunIdFromSession,
@@ -22,6 +26,7 @@ import {
 import { getDebateState } from "./lib/debate-bus-state.js";
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
 import { captureHarnessEvent } from "./lib/harness-posthog.js";
+import { DEBATE_AGENT_SUBMIT_TOOL } from "./lib/harness-subagent-submit-registry.js";
 import {
 	type DebateEligibilityInput,
 	harnessPlanDebateEligibility,
@@ -40,6 +45,7 @@ import {
 } from "./lib/plan-debate-id.js";
 import {
 	applyDebateLane,
+	applyDebateLaneFromDoc,
 	type DebateLaneKind,
 	debateLaneForAgent,
 	formatApplyLaneMessage,
@@ -95,13 +101,19 @@ function telemetryRound(
 
 function subagentResults(
 	details: unknown,
-): Array<{ agent: string; finalOutput?: string }> {
+): Array<{ agent: string; finalOutput?: string; messages?: MessageLike[] }> {
 	const d = details as {
-		results?: Array<{ agent: string; finalOutput?: string }>;
+		results?: Array<{
+			agent: string;
+			finalOutput?: string;
+			messages?: MessageLike[];
+		}>;
 	};
 	return d?.results ?? [];
 }
 
+const USE_SUBMIT_TOOLS = process.env.HARNESS_SUBMIT_TOOLS !== "0";
+
 export default function harnessDebateTools(pi: ExtensionAPI) {
 	if (!claimExtensionLoad("harness-debate-tools", MODULE_URL)) return;
 
@@ -118,7 +130,34 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 		let lastRound = 1;
 		for (const result of subagentResults(event.details)) {
 			const lane = debateLaneForAgent(result.agent ?? "");
-			if (!lane || !result.finalOutput?.trim()) continue;
+			if (!lane) continue;
+
+			const submitTool = DEBATE_AGENT_SUBMIT_TOOL[result.agent ?? ""];
+			const submitCall =
+				USE_SUBMIT_TOOLS && submitTool && result.messages
+					? extractLastSubmitCall(result.messages, submitTool)
+					: null;
+
+			if (submitCall) {
+				const out = await applyDebateLaneFromDoc({
+					runDir: rd,
+					lane,
+					doc: submitCall.document,
+				});
+				if (out.round_index) lastRound = out.round_index;
+				pi.appendEntry("harness-debate-lane-applied", {
+					agent: result.agent,
+					source: "submit_tool",
+					tool: submitCall.toolName,
+					...out,
+				});
+				applied.push(formatApplyLaneMessage(out));
+				continue;
+			}
+
+			if (!result.finalOutput?.trim()) continue;
+			if (USE_SUBMIT_TOOLS && submitTool) continue;
+
 			const out = await applyDebateLane({
 				runDir: rd,
 				lane,
@@ -153,7 +192,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 		name: "harness_plan_debate_eligibility",
 		label: "Plan Debate Eligibility",
 		description:
-			"Pre-debate profile selection (full|standard|light). Call after DAG pass, before harness_debate_open. Uses risk, fork, implementation/stack briefs — not R1 hypothesis output.",
+			"Pre-debate profile selection (full|standard|light|fast). Call after DAG pass, before harness_debate_open. Uses risk, fork, implementation/stack briefs — not R1 hypothesis output.",
 		parameters: Type.Object({
 			risk_level: Type.Optional(
 				Type.String({ description: "low | med | high" }),
@@ -211,6 +250,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const result = harnessPlanDebateEligibility(input);
 			const lines = [
 				`profile: ${result.profile}`,
+				`review_gate_mode: ${result.review_gate_strategy.mode}`,
 				`required_focuses: ${result.required_focuses.join(", ")}`,
 				`min_focus_rounds: ${result.min_focus_rounds}`,
 				`debate_global_cap: ${result.debate_global_cap}`,
@@ -234,7 +274,7 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 				Type.String({ description: "Optional; normalized to plan-<run_id>" }),
 			),
 			debate_profile: Type.Optional(
-				Type.String({ description: "full | standard | light" }),
+				Type.String({ description: "full | standard | light | fast" }),
 			),
 			required_focuses: Type.Optional(
 				Type.Array(
@@ -258,7 +298,8 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const profile =
 				p.debate_profile === "full" ||
 				p.debate_profile === "standard" ||
-				p.debate_profile === "light"
+				p.debate_profile === "light" ||
+				p.debate_profile === "fast"
 					? p.debate_profile
 					: "standard";
 			const required_focuses = (p.required_focuses ?? []).filter((f) =>
@@ -269,11 +310,14 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 				required_focuses:
 					required_focuses.length > 0 ? required_focuses : undefined,
 			});
+			const review_gate_mode =
+				profile === "fast" ? ("consolidated" as const) : ("threaded" as const);
 			await initPlanMessenger(runDir(projectRoot, runId), {
 				runId,
 				debateId,
 				debate_profile: profile,
 				required_focuses: opened.required_focuses,
+				review_gate_mode,
 			});
 			const sessionId = ctx.sessionManager.getSessionId();
 			captureHarnessEvent(sessionId, "harness_debate_round", {
@@ -286,11 +330,15 @@ export default function harnessDebateTools(pi: ExtensionAPI) {
 			const lines = [
 				`Plan debate opened: ${debateId}`,
 				`Profile: ${profile}`,
+				`Review gate mode: ${review_gate_mode}`,
 				required_focuses.length
 					? `Required focuses: ${required_focuses.join(", ")}`
 					: opened.required_focuses?.length
 						? `Required focuses: ${opened.required_focuses.join(", ")}`
 						: "Required focuses: (default all four)",
+				review_gate_mode === "consolidated"
+					? "Consolidated path: one review round (artifacts/review-round-consolidated.yaml); escalate to threaded rounds only on blockers."
+					: "Threaded path: one review round per focus (spec → wbs → schedule → quality).",
 				`Messenger: debate-messenger/ (inbox + threads/round-N/transcript.jsonl)`,
 			];
 			if (warning) lines.push(`Note: ${warning}`);

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

@@ -5,8 +5,9 @@
  * in before_agent_start so trace-recorder reuses it on agent_start.
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { constants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import {
@@ -56,6 +57,10 @@ import {
 	writeYamlFile,
 } from "../lib/harness-yaml.js";
 import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import {
+	evaluateHarnessSubagentToolCall,
+	isSubmitToolName,
+} from "./lib/harness-subagent-policy.js";
 import { isReviewRoundArtifactPath } from "./lib/plan-debate-gate.js";
 import { isReviewRoundYamlWriteAllowed } from "./lib/plan-debate-write-guard.js";
 
@@ -714,6 +719,36 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		// #region agent log
+		fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-Debug-Session-Id": "2ca12b",
+			},
+			body: JSON.stringify({
+				sessionId: "2ca12b",
+				location: "harness-run-context.ts:tool_call",
+				message: "submit policy hook",
+				data: {
+					toolName: event.toolName,
+					typeofIsSubmitToolName: typeof isSubmitToolName,
+				},
+				timestamp: Date.now(),
+				hypothesisId: "H1",
+			}),
+		}).catch(() => {});
+		// #endregion
+		if (isSubmitToolName(event.toolName)) {
+			const decision = evaluateHarnessSubagentToolCall(
+				event.toolName,
+				event.input as Record<string, unknown>,
+				"parent-orchestrator",
+			);
+			if (decision.action === "block") {
+				return { block: true, reason: decision.reason };
+			}
+		}
 		if (event.toolName === "write") {
 			const entries = getEntries(ctx);
 			const runCtx = getLatestRunContext(entries) ?? activeCtx;
@@ -990,6 +1025,18 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 				};
 			}
 			const relForGate = pathArg.replace(/\\/g, "/");
+			if (/\.json$/i.test(relForGate) && relForGate.startsWith("artifacts/")) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Path not allowed: ${pathArg}. Plan artifacts under artifacts/ must be .yaml (use submit_* from subagents or write_harness_yaml with YAML content).`,
+						},
+					],
+					details: { path: pathArg },
+					isError: true,
+				};
+			}
 			if (
 				isReviewRoundArtifactPath(relForGate) &&
 				!isReviewRoundYamlWriteAllowed()
@@ -1030,6 +1077,65 @@ export default function harnessRunContext(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "harness_artifact_ready",
+		label: "Harness Artifact Ready",
+		description:
+			"Check that harness artifact paths exist under the active run (no JSON parsing).",
+		parameters: Type.Object({
+			paths: Type.Array(Type.String(), {
+				minItems: 1,
+				description:
+					"Relative paths under the run dir, e.g. artifacts/decomposition.yaml",
+			}),
+		}),
+		async execute(_id, 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." }],
+					details: {},
+					isError: true,
+				};
+			}
+			const paths = (params as { paths?: string[] }).paths ?? [];
+			const projectRoot = process.cwd();
+			const runRoot = join(
+				projectRoot,
+				".pi",
+				"harness",
+				"runs",
+				runCtx.run_id,
+			);
+			const missing: string[] = [];
+			const present: string[] = [];
+			for (const rel of paths) {
+				const normalized = rel.replace(/\\/g, "/");
+				const abs = join(runRoot, normalized);
+				try {
+					await access(abs, constants.R_OK);
+					present.push(normalized);
+				} catch {
+					missing.push(normalized);
+				}
+			}
+			const ok = missing.length === 0;
+			return {
+				content: [
+					{
+						type: "text",
+						text: ok
+							? `All ${present.length} artifact(s) present.`
+							: `Missing: ${missing.join(", ")}`,
+					},
+				],
+				details: { ok, present, missing, run_id: runCtx.run_id },
+				isError: !ok,
+			};
+		},
+	});
+
 	pi.registerCommand("harness-use-run", {
 		description: "Point this session at an existing run directory (recovery)",
 		handler: async (args, ctx) => {

package/.pi/extensions/harness-subagent-submit.ts

@@ -0,0 +1,172 @@
+/**
+ * Subprocess-only harness submit tools — validate + write artifacts under run_dir.
+ * Loaded via `pi --no-extensions -e harness-subagent-submit.ts` for harness agents.
+ */
+
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { claimExtensionLoad } from "./lib/extension-load-guard.js";
+import { getHarnessPackageRoot } from "./lib/harness-paths.js";
+import { evaluateHarnessSubagentToolCall } from "./lib/harness-subagent-policy.js";
+import { executeSubmitPipeline } from "./lib/harness-subagent-submit-pipeline.js";
+import { SUBMIT_TOOL_SPECS } from "./lib/harness-subagent-submit-registry.js";
+
+// @ts-expect-error pi extensions run as ESM
+const MODULE_URL = import.meta.url;
+
+const DocumentSchema = Type.Object(
+	{
+		document: Type.Record(Type.String(), Type.Unknown(), {
+			description:
+				"Plan artifact fields (validated via plan-*.schema.json, persisted as canonical YAML on disk)",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+function resolveRunContext(): {
+	projectRoot: string;
+	specsDir: string;
+	runId: string;
+	runDirEnv?: string;
+	agentId: string;
+} {
+	const projectRoot = process.env.HARNESS_PKG_ROOT ?? process.cwd();
+	const specsDir = join(projectRoot, ".pi", "harness", "specs");
+	const runId = process.env.HARNESS_RUN_ID?.trim() ?? "";
+	const runDirEnv = process.env.HARNESS_RUN_DIR?.trim();
+	const agentId = process.env.HARNESS_AGENT_ID?.trim() ?? "";
+	return { projectRoot, specsDir, runId, runDirEnv, agentId };
+}
+
+function isSubprocessHarness(): boolean {
+	return (
+		process.env.PI_HARNESS_SUBPROCESS === "1" &&
+		Boolean(process.env.HARNESS_RUN_ID?.trim())
+	);
+}
+
+export default function harnessSubagentSubmit(pi: ExtensionAPI) {
+	if (!claimExtensionLoad("harness-subagent-submit", MODULE_URL)) return;
+	// Option A: only load submit tools in subprocess (`-e` bundle), not parent discovery.
+	if (process.env.PI_HARNESS_SUBPROCESS !== "1") {
+		return;
+	}
+
+	const _packageRoot = getHarnessPackageRoot(MODULE_URL);
+
+	pi.on("tool_call", async (event) => {
+		if (!event.toolName.startsWith("submit_")) return undefined;
+		const subprocessOk = isSubprocessHarness();
+		if (!subprocessOk) {
+			return {
+				block: true,
+				reason:
+					"harness-subagent-submit: submit_* tools are only available in harness subagent subprocesses.",
+			};
+		}
+		const { agentId } = resolveRunContext();
+		if (!agentId) {
+			return {
+				block: true,
+				reason:
+					"harness-subagent-submit: HARNESS_AGENT_ID is required for submit tools.",
+			};
+		}
+		const decision = evaluateHarnessSubagentToolCall(
+			event.toolName,
+			event.input as Record<string, unknown>,
+			agentId,
+		);
+		if (decision.action === "block") {
+			return { block: true, reason: decision.reason };
+		}
+		return undefined;
+	});
+
+	for (const spec of SUBMIT_TOOL_SPECS) {
+		pi.registerTool({
+			name: spec.toolName,
+			label: spec.toolName.replace(/^submit_/, "Submit "),
+			description: `Terminal harness artifact submit for ${spec.agents.join(", ")}. Call once with the full schema document before ending the turn.`,
+			parameters: DocumentSchema,
+			async execute(_id, params, _signal, _onUpdate, _ctx) {
+				if (!isSubprocessHarness()) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "submit tools require PI_HARNESS_SUBPROCESS and HARNESS_RUN_ID",
+							},
+						],
+						details: {},
+						isError: true,
+					};
+				}
+				const { projectRoot, specsDir, runId, runDirEnv, agentId } =
+					resolveRunContext();
+				if (!spec.agents.includes(agentId)) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `${spec.toolName} is not allowed for agent ${agentId}`,
+							},
+						],
+						details: { agentId, tool: spec.toolName },
+						isError: true,
+					};
+				}
+				const document = (params as { document?: Record<string, unknown> })
+					.document;
+				if (!document || typeof document !== "object") {
+					return {
+						content: [{ type: "text", text: "document object is required" }],
+						details: {},
+						isError: true,
+					};
+				}
+				const result = await executeSubmitPipeline({
+					projectRoot,
+					specsDir,
+					spec,
+					agentId,
+					document,
+					runId,
+					runDirEnv,
+				});
+				if (!result.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Validation failed:\n${(result.validation_errors ?? []).join("\n")}`,
+							},
+						],
+						isError: true,
+						details: result,
+					};
+				}
+				const lines = [`ok: wrote ${result.artifact_path}`];
+				if (result.lane_result?.messenger_posted) {
+					lines.push("messenger updated");
+				}
+				if (result.human_required) {
+					lines.push("human_required: parent must call ask_user");
+				}
+				return {
+					content: [{ type: "text", text: lines.join("\n") }],
+					details: result as unknown,
+				};
+			},
+		});
+	}
+}
+
+/** Absolute path to the subprocess submit extension (Option A). */
+export function harnessSubagentSubmitExtensionPath(
+	packageRoot: string,
+): string {
+	return join(packageRoot, ".pi", "extensions", "harness-subagent-submit.ts");
+}

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

@@ -127,6 +127,7 @@ function propsFromRun(
 ): Record<string, unknown> {
 	return {
 		harness_run_id: runId,
+		run_id: runId,
 		harness_plan_id: planId,
 		harness_phase: phase,
 		pi_session_id: distinctId,
@@ -134,6 +135,28 @@ function propsFromRun(
 	};
 }
 
+function normalizedRunId(
+	data: Record<string, unknown>,
+	trace: TraceState | null,
+	distinctId: string,
+): string {
+	const fromData = [
+		data.harness_run_id,
+		data.run_id,
+		data.runId,
+		data.debate_id,
+	];
+	for (const candidate of fromData) {
+		if (typeof candidate === "string" && candidate.trim().length > 0) {
+			return candidate;
+		}
+	}
+	if (typeof trace?.run_id === "string" && trace.run_id.length > 0) {
+		return trace.run_id;
+	}
+	return distinctId;
+}
+
 function mapCustomEntry(
 	customType: string,
 	data: Record<string, unknown>,
@@ -144,11 +167,9 @@ function mapCustomEntry(
 	event: HarnessPostHogEventName;
 	properties: Record<string, unknown>;
 } | null {
-	const runId =
-		(typeof data.run_id === "string" && data.run_id) ||
-		trace?.run_id ||
-		distinctId;
+	const runId = normalizedRunId(data, trace, distinctId);
 	const planId =
+		(typeof data.harness_plan_id === "string" && data.harness_plan_id) ||
 		(typeof data.plan_id === "string" && data.plan_id) ||
 		policy?.planId ||
 		trace?.plan_id ||
@@ -185,6 +206,7 @@ function mapCustomEntry(
 				event: "harness_debate_consensus",
 				properties: {
 					...base,
+					debate_id: String(data.debate_id ?? runId),
 					consensus_id:
 						typeof data.debate_id === "string" ? data.debate_id : runId,
 					outcome: String(kind),
@@ -195,6 +217,8 @@ function mapCustomEntry(
 			event: "harness_debate_round",
 			properties: {
 				...base,
+				debate_id: String(data.debate_id ?? runId),
+				round_index: Number(data.round_index ?? data.round ?? 0),
 				round: Number(data.round_index ?? data.round ?? 0),
 				outcome: String(kind ?? "round"),
 			},
@@ -206,6 +230,7 @@ function mapCustomEntry(
 			event: "harness_debate_consensus",
 			properties: {
 				...base,
+				debate_id: String(data.debate_id ?? runId),
 				consensus_id:
 					typeof data.consensus_id === "string"
 						? data.consensus_id

package/.pi/extensions/lib/debate-bus-core.ts

@@ -11,6 +11,10 @@ import {
 	PLAN_DEBATE_PARTICIPANTS,
 	POST_EXECUTE_DEBATE_PARTICIPANTS,
 } from "../../lib/debate-orchestrator-types.js";
+import {
+	isHarnessBudgetEnforceOn,
+	shouldEmitBlockingBudgetExhausted,
+} from "../../lib/harness-budget-enforce.js";
 import {
 	type DebateState,
 	getDebateState,
@@ -21,6 +25,7 @@ import {
 } from "./debate-bus-state.js";
 import {
 	type DebateProfile,
+	PLAN_BUDGET_FAST,
 	PLAN_BUDGET_LIGHT,
 	PLAN_BUDGET_STANDARD,
 } from "./plan-debate-eligibility.js";
@@ -75,7 +80,8 @@ const THRESHOLDS = {
 	architecture: 0.8,
 	test_integrity: 0.8,
 };
-const HARD_STOP_DEBATE_CAPS = process.env.HARNESS_DEBATE_HARD_STOP === "true";
+const HARD_STOP_DEBATE_CAPS =
+	process.env.HARNESS_DEBATE_HARD_STOP === "true" && isHarnessBudgetEnforceOn();
 
 const PLAN_BUDGET = PLAN_BUDGET_STANDARD;
 
@@ -108,15 +114,40 @@ export function capsForDebate(
 } {
 	if (isPlanDebateId(debateId)) {
 		const active = profile ?? getDebateState()?.debate_profile ?? "standard";
-		const budget = active === "light" ? PLAN_BUDGET_LIGHT : PLAN_BUDGET;
-		return { name: "plan", ...budget };
+		const budget =
+			active === "light"
+				? PLAN_BUDGET_LIGHT
+				: active === "fast"
+					? PLAN_BUDGET_FAST
+					: PLAN_BUDGET;
+		const caps = { name: "plan" as const, ...budget };
+		if (!isHarnessBudgetEnforceOn()) {
+			return {
+				...caps,
+				max_rounds: caps.max_rounds,
+				max_exchanges_per_round: Math.max(caps.max_exchanges_per_round, 2),
+				round_token_cap: caps.round_token_cap * 2,
+				debate_global_cap: caps.debate_global_cap * 2,
+			};
+		}
+		return caps;
 	}
-	return {
-		name: "aggressive",
+	const caps = {
+		name: "aggressive" as const,
 		min_focus_rounds: 1,
 		max_exchanges_per_round: 1,
 		...AGGRESSIVE_BUDGET,
 	};
+	if (!isHarnessBudgetEnforceOn()) {
+		return {
+			...caps,
+			max_rounds: caps.max_rounds,
+			max_exchanges_per_round: Math.max(caps.max_exchanges_per_round, 2),
+			round_token_cap: caps.round_token_cap * 2,
+			debate_global_cap: caps.debate_global_cap * 2,
+		};
+	}
+	return caps;
 }
 
 function participantAllowed(
@@ -280,7 +311,19 @@ async function emitBudgetExhausted(
 		},
 	};
 	hooks.appendEntry("harness-debate-envelope", envelope);
-	hooks.appendEntry("harness-budget-exhausted", envelope.payload);
+	if (shouldEmitBlockingBudgetExhausted()) {
+		hooks.appendEntry("harness-budget-exhausted", envelope.payload);
+	} else {
+		const telemetryPayload = {
+			...(envelope.payload as Record<string, unknown>),
+			telemetry_only: true,
+		};
+		hooks.appendEntry("harness-debate-budget-telemetry", telemetryPayload);
+		hooks.appendEntry("harness-budget-telemetry", {
+			...telemetryPayload,
+			source: "debate-bus",
+		});
+	}
 	await writeDebateEvent(state.debate_id, envelope);
 }