ultimate-pi 0.15.0 → 0.16.0

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;
@@ -1030,6 +1065,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,195 @@
+/**
+ * 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: "Full artifact document matching the harness JSON schema",
+		}),
+	},
+	{ 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();
+		// #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",
+				hypothesisId: "H2",
+				location: "harness-subagent-submit.ts:tool_call",
+				message: "submit tool_call gate",
+				data: {
+					toolName: event.toolName,
+					PI_HARNESS_SUBPROCESS: process.env.PI_HARNESS_SUBPROCESS,
+					HARNESS_RUN_ID: process.env.HARNESS_RUN_ID ?? null,
+					HARNESS_RUN_DIR: process.env.HARNESS_RUN_DIR ?? null,
+					HARNESS_AGENT_ID: process.env.HARNESS_AGENT_ID ?? null,
+					subprocessOk,
+				},
+				timestamp: Date.now(),
+			}),
+		}).catch(() => {});
+		// #endregion
+		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/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,
@@ -75,7 +79,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;
 
@@ -109,14 +114,34 @@ 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 caps = { name: "plan" as const, ...budget };
+		if (!isHarnessBudgetEnforceOn()) {
+			return {
+				...caps,
+				max_rounds: 999,
+				max_exchanges_per_round: 99,
+				round_token_cap: caps.round_token_cap * 100,
+				debate_global_cap: caps.debate_global_cap * 100,
+			};
+		}
+		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: 999,
+			max_exchanges_per_round: 99,
+			round_token_cap: caps.round_token_cap * 100,
+			debate_global_cap: caps.debate_global_cap * 100,
+		};
+	}
+	return caps;
 }
 
 function participantAllowed(
@@ -280,7 +305,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);
 }
 

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

@@ -2,6 +2,10 @@
  * Per-agent tool policy for harness/* subagents (defense in depth with frontmatter).
  */
 
+import {
+	isSubmitToolName,
+	SUBMIT_TOOLS_BY_AGENT,
+} from "./harness-subagent-submit-registry.js";
 import {
 	evaluateSubagentToolCall,
 	type ToolCallDecision,
@@ -107,6 +111,45 @@ export function evaluateHarnessSubagentToolCall(
 	}
 
 	if (!isHarnessPackageAgent(agentType)) {
+		if (
+			isSubmitToolName(toolName) &&
+			process.env.PI_HARNESS_SUBPROCESS !== "1"
+		) {
+			return {
+				action: "block",
+				reason:
+					"harness-subagent-policy: submit_* tools are subprocess-only; parent orchestrator must use harness_artifact_ready and write_harness_yaml for merges.",
+			};
+		}
+		return { action: "allow" };
+	}
+
+	if (isSubmitToolName(toolName)) {
+		if (process.env.PI_HARNESS_SUBPROCESS !== "1") {
+			return {
+				action: "block",
+				reason:
+					"harness-subagent-policy: submit_* tools are not available in the parent harness session.",
+			};
+		}
+		if (toolName === "submit_human_required") {
+			const kind = classifyHarnessAgent(agentType);
+			if (kind === "executor") {
+				return {
+					action: "block",
+					reason:
+						"submit_human_required is not available for harness/executor.",
+				};
+			}
+			return { action: "allow" };
+		}
+		const allowed = SUBMIT_TOOLS_BY_AGENT[agentType];
+		if (!allowed?.has(toolName)) {
+			return {
+				action: "block",
+				reason: `harness-subagent-policy: ${toolName} is not allowed for ${agentType}.`,
+			};
+		}
 		return { action: "allow" };
 	}
 
@@ -153,6 +196,8 @@ export function evaluateHarnessSubagentToolCall(
 	return { action: "allow" };
 }
 
+export { isSubmitToolName } from "./harness-subagent-submit-registry.js";
+
 export function harnessSubagentPhaseHint(agentType: string): string | null {
 	if (isHarnessPlanningAgent(agentType)) {
 		return "plan";

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

@@ -0,0 +1,82 @@
+/**
+ * Shared write pipeline for harness subagent submit tools.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { validateAgainstHarnessSchema } from "../../lib/harness-schema-validate.js";
+import { resolveGuardedRunDir } from "../../lib/harness-subagent-submit-path.js";
+import { writeYamlFile } from "../../lib/harness-yaml.js";
+import {
+	resolveArtifactRelPath,
+	type SubmitToolSpec,
+} from "./harness-subagent-submit-registry.js";
+import {
+	type ApplyDebateLaneResult,
+	applyDebateLaneFromDoc,
+} from "./plan-debate-lane.js";
+
+export interface SubmitPipelineResult {
+	ok: boolean;
+	artifact_path?: string;
+	validation_errors?: string[];
+	lane_result?: ApplyDebateLaneResult;
+	human_required?: boolean;
+}
+
+export async function executeSubmitPipeline(opts: {
+	projectRoot: string;
+	specsDir: string;
+	spec: SubmitToolSpec;
+	agentId: string;
+	document: Record<string, unknown>;
+	runId: string;
+	runDirEnv?: string;
+}): Promise<SubmitPipelineResult> {
+	const runResolved = await resolveGuardedRunDir({
+		projectRoot: opts.projectRoot,
+		runId: opts.runId,
+		runDirEnv: opts.runDirEnv,
+	});
+	if (!runResolved.ok) {
+		return { ok: false, validation_errors: [runResolved.error] };
+	}
+
+	const validation = await validateAgainstHarnessSchema(
+		opts.specsDir,
+		opts.spec.schemaFile,
+		opts.document,
+	);
+	if (!validation.ok) {
+		return { ok: false, validation_errors: validation.errors };
+	}
+
+	const relPath = resolveArtifactRelPath(opts.spec, opts.document);
+	const absPath = join(runResolved.runDir, relPath);
+	await mkdir(dirname(absPath), { recursive: true });
+	await writeYamlFile(absPath, opts.document);
+
+	let laneResult: ApplyDebateLaneResult | undefined;
+	if (opts.spec.debateLane) {
+		laneResult = await applyDebateLaneFromDoc({
+			runDir: runResolved.runDir,
+			lane: opts.spec.debateLane,
+			doc: opts.document,
+		});
+		if (!laneResult.ok) {
+			return {
+				ok: false,
+				artifact_path: relPath,
+				validation_errors: laneResult.errors,
+				lane_result: laneResult,
+			};
+		}
+	}
+
+	return {
+		ok: true,
+		artifact_path: relPath,
+		lane_result: laneResult,
+		human_required: opts.spec.humanRequired === true,
+	};
+}