ultimate-pi 0.18.1 → 0.19.1

package/.pi/{extensions/lib → lib}/harness-posthog.ts

@@ -24,6 +24,9 @@ export type HarnessPostHogEventName =
 	| "harness_eval_verdict"
 	| "harness_sentrux_signal"
 	| "harness_observation"
+	| "harness_lens_analysis_complete"
+	| "harness_lens_findings"
+	| "harness_lens_turn_findings"
 	| "harness_subagent_spawned"
 	| "harness_subagent_completed"
 	| "harness_subagent_result_wait"

package/.pi/lib/harness-run-context-responses.ts

@@ -0,0 +1,9 @@
+export function blockRunContextMessage(content: string) {
+	return {
+		message: {
+			customType: "harness-run-context-block",
+			display: true,
+			content,
+		},
+	};
+}

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

@@ -101,7 +101,6 @@ const HARNESS_COMMANDS = new Set([
 	"harness-drift-proceed",
 	"harness-policy-status",
 	"harness-trace-last",
-	"harness-router-tune",
 	"harness-budget-status",
 ]);
 
@@ -213,7 +212,6 @@ export const HARNESS_COMMAND_PHASE: Record<string, HarnessPhase> = {
 	"harness-run-status": "plan",
 	"harness-use-run": "plan",
 	"harness-policy-status": "merge",
-	"harness-router-tune": "plan",
 	"harness-budget-status": "plan",
 	"harness-setup": "execute",
 };

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

@@ -1,5 +1,6 @@
 /**
  * Subagent tool policy — block nested orchestration tools (defense in depth).
+ * Shared by AGT evaluation context and extensions (lives under .pi/lib, not extensions).
  */
 
 export const SUBAGENT_BLOCKED_TOOLS = new Set([

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

@@ -5,7 +5,7 @@
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
-import type { HarnessPhase } from "../../lib/harness-run-context.js";
+import type { HarnessPhase } from "./harness-run-context.js";
 
 export interface SpawnTopologyResult {
 	ok: boolean;

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

@@ -0,0 +1,81 @@
+/**
+ * Resolve concrete LLM credentials for harness subagent subprocesses.
+ *
+ * Harness subprocesses run with `--no-extensions`, so auth forwarding only uses
+ * concrete provider/model references from env, agent config, or parent session.
+ */
+
+import type { AgentConfig } from "../../vendor/pi-subagents/src/agents.js";
+
+const SENTINEL_API_KEYS = new Set(["<authenticated>"]);
+
+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 || provider === "router") return null;
+	return { provider, modelId };
+}
+
+export interface ConcreteSubagentModel {
+	modelRef: string;
+	provider: string;
+	modelId: string;
+}
+
+function toConcrete(ref: string): ConcreteSubagentModel | undefined {
+	const parsed = parseModelRef(ref);
+	if (!parsed) return undefined;
+	return { modelRef: ref, ...parsed };
+}
+
+const WEB_FAST_AGENT_IDS = new Set([
+	"harness/web-retrieval/web-query-expander-fast",
+	"harness/web-retrieval/web-summarizer",
+	"harness/web-retrieval/web-gap-analyzer",
+]);
+
+const WEB_QUALITY_AGENT_IDS = new Set([
+	"harness/web-retrieval/web-answerer",
+	"harness/web-retrieval/web-criteria-verifier",
+]);
+
+function envModelRef(varName: string): string | undefined {
+	const v = process.env[varName]?.trim();
+	return v && parseModelRef(v) ? v : undefined;
+}
+
+function modelFromEnv(agentName: string): ConcreteSubagentModel | undefined {
+	const fast = envModelRef("HARNESS_WEB_FAST_MODEL");
+	if (fast && WEB_FAST_AGENT_IDS.has(agentName)) return toConcrete(fast);
+	const expander = envModelRef("HARNESS_WEB_EXPANDER_MODEL");
+	if (expander && agentName === "harness/web-retrieval/web-query-expander") return toConcrete(expander);
+	const quality = envModelRef("HARNESS_WEB_QUALITY_MODEL");
+	if (quality && WEB_QUALITY_AGENT_IDS.has(agentName)) return toConcrete(quality);
+	return undefined;
+}
+
+export function resolveConcreteSubagentModel(
+	_parentCwd: string,
+	parentModel: { provider: string; id: string } | undefined,
+	agent: AgentConfig,
+	_taskSnippet?: string,
+): ConcreteSubagentModel | undefined {
+	const envOverride = modelFromEnv(agent.name);
+	if (envOverride) return envOverride;
+
+	if (agent.model) {
+		const concrete = toConcrete(agent.model);
+		if (concrete) return concrete;
+	}
+
+	if (!parentModel || parentModel.provider === "router") return undefined;
+	return toConcrete(`${parentModel.provider}/${parentModel.id}`);
+}

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

@@ -5,13 +5,11 @@
 import {
 	type AgentConfig,
 	agentAllowsMutatingTools,
-} from "../../../vendor/pi-subagents/src/agents.js";
-import {
-	type HarnessPhase,
-	inferHarnessPhase,
-} from "../../lib/harness-run-context.js";
+} from "../../vendor/pi-subagents/src/agents.js";
+import { getAgentKind } from "./agents-policy.mjs";
+import { getHarnessPackageRoot } from "./harness-paths.js";
+import { type HarnessPhase, inferHarnessPhase } from "./harness-run-context.js";
 import { validateHarnessSpawnTopology } from "./harness-spawn-topology.js";
-import { classifyHarnessAgent } from "./harness-subagent-policy.js";
 
 export interface SubagentTaskRef {
 	agent: string;
@@ -105,9 +103,14 @@ export async function precheckHarnessSubagentSpawn(
 		return topology;
 	}
 
+	const packageRoot = getHarnessPackageRoot(
+		// @ts-expect-error pi extensions run as ESM
+		import.meta.url,
+	);
+	const projectRoot = opts?.projectRoot ?? process.cwd();
 	for (const name of names) {
 		if (!name.startsWith("harness/")) continue;
-		classifyHarnessAgent(name);
+		getAgentKind(packageRoot, projectRoot, name);
 	}
 
 	return { ok: true };

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

@@ -4,13 +4,13 @@
 
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } 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 { validateAgainstHarnessSchema } from "./harness-schema-validate.js";
+import { resolveGuardedRunDir } from "./harness-subagent-submit-path.js";
 import {
 	resolveArtifactRelPath,
 	type SubmitToolSpec,
 } from "./harness-subagent-submit-registry.js";
+import { writeYamlFile } from "./harness-yaml.js";
 import {
 	type ApplyDebateLaneResult,
 	applyDebateLaneFromDoc,

package/.pi/lib/harness-subagent-submit-register.ts

@@ -0,0 +1,163 @@
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { allowsAgentTool } from "./agents-policy.mjs";
+import { resolveGuardedRunDir } from "./harness-subagent-submit-path.js";
+import {
+	executeSubmitPipeline,
+	loadSubmitDocument,
+} from "./harness-subagent-submit-pipeline.js";
+import { SUBMIT_TOOL_SPECS } from "./harness-subagent-submit-registry.js";
+
+const DocumentSchema = Type.Object(
+	{
+		document: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description:
+					"Artifact fields (deprecated when source_path is set; ADR 0043)",
+			}),
+		),
+		source_path: Type.Optional(
+			Type.String({
+				description:
+					"Relative path under run dir, e.g. artifacts/.draft/decomposition.yaml",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export function resolveHarnessSubmitRunContext(packageRoot: string): {
+	projectRoot: string;
+	specsDir: string;
+	runId: string;
+	runDirEnv?: string;
+	agentId: string;
+} {
+	const projectRoot = process.env.HARNESS_PKG_ROOT?.trim() || packageRoot;
+	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 };
+}
+
+export function isSubprocessHarnessSubmit(): boolean {
+	return (
+		process.env.PI_HARNESS_SUBPROCESS === "1" &&
+		Boolean(process.env.HARNESS_RUN_ID?.trim())
+	);
+}
+
+export function registerHarnessSubagentSubmitTools(
+	pi: ExtensionAPI,
+	packageRoot: string,
+): void {
+	for (const spec of SUBMIT_TOOL_SPECS) {
+		pi.registerTool({
+			name: spec.toolName,
+			label: spec.toolName.replace(/^submit_/, "Submit "),
+			description: `Terminal harness artifact submit (${spec.toolName}). Call once with the full schema document before ending the turn.`,
+			parameters: DocumentSchema,
+			async execute(_id, params, _signal, _onUpdate, _ctx) {
+				if (!isSubprocessHarnessSubmit()) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "submit tools require PI_HARNESS_SUBPROCESS and HARNESS_RUN_ID",
+							},
+						],
+						details: {},
+						isError: true,
+					};
+				}
+				const { projectRoot, specsDir, runId, runDirEnv, agentId } =
+					resolveHarnessSubmitRunContext(packageRoot);
+				if (
+					!allowsAgentTool({
+						packageRoot,
+						projectRoot,
+						agentId,
+						toolName: spec.toolName,
+						toolInput: params as Record<string, unknown>,
+						isSubprocess: true,
+					})
+				) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `${spec.toolName} is not allowed for agent ${agentId} (agents.policy.yaml)`,
+							},
+						],
+						details: { agentId, tool: spec.toolName },
+						isError: true,
+					};
+				}
+				const runResolved = await resolveGuardedRunDir({
+					projectRoot,
+					runId,
+					runDirEnv,
+				});
+				if (!runResolved.ok) {
+					return {
+						content: [{ type: "text", text: runResolved.error }],
+						details: {},
+						isError: true,
+					};
+				}
+				const loaded = await loadSubmitDocument({
+					projectRoot,
+					runDir: runResolved.runDir,
+					document: (params as { document?: Record<string, unknown> }).document,
+					source_path: (params as { source_path?: string }).source_path,
+				});
+				if (!loaded.ok) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Validation failed:\n${loaded.validation_errors.join("\n")}`,
+							},
+						],
+						isError: true,
+						details: loaded,
+					};
+				}
+				const result = await executeSubmitPipeline({
+					projectRoot,
+					specsDir,
+					spec,
+					agentId,
+					document: loaded.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,
+				};
+			},
+		});
+	}
+}

package/.pi/{extensions/lib → lib}/harness-subagent-submit-registry.ts

@@ -1,12 +1,11 @@
 /**
- * Registry: submit tool name → agent allowlist, schema, artifact path.
+ * Registry: submit tool name → schema, artifact path (allowlists live in agents.policy.yaml).
  */
 
 import type { DebateLaneKind } from "./plan-debate-lane.js";
 
 export interface SubmitToolSpec {
 	toolName: string;
-	agents: readonly string[];
 	schemaFile: string;
 	artifactPath: string | ((doc: Record<string, unknown>) => string);
 	debateLane?: DebateLaneKind;
@@ -24,126 +23,91 @@ function roundPath(prefix: string, doc: Record<string, unknown>): string {
 export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
 	{
 		toolName: "submit_planning_context",
-		agents: ["harness/planning/planning-context"],
 		schemaFile: "plan-planning-context.schema.json",
 		artifactPath: "artifacts/planning-context.yaml",
 	},
 	{
 		toolName: "submit_decomposition_brief",
-		agents: ["harness/planning/decompose", "harness/planning/plan-synthesizer"],
 		schemaFile: "plan-decomposition-brief.schema.json",
 		artifactPath: "artifacts/decomposition.yaml",
 	},
 	{
 		toolName: "submit_hypothesis_brief",
-		agents: [
-			"harness/planning/hypothesis",
-			"harness/planning/plan-synthesizer",
-		],
 		schemaFile: "plan-hypothesis-brief.schema.json",
 		artifactPath: "artifacts/hypothesis.yaml",
 	},
 	{
 		toolName: "submit_implementation_research",
-		agents: ["harness/planning/implementation-researcher"],
 		schemaFile: "plan-implementation-research-brief.schema.json",
 		artifactPath: "artifacts/implementation-research.yaml",
 	},
 	{
 		toolName: "submit_stack_brief",
-		agents: ["harness/planning/stack-researcher"],
 		schemaFile: "plan-stack-brief.schema.json",
 		artifactPath: "artifacts/stack.yaml",
 	},
 	{
 		toolName: "submit_execution_plan_brief",
-		agents: [
-			"harness/planning/execution-plan-author",
-			"harness/planning/plan-synthesizer",
-		],
 		schemaFile: "plan-execution-plan-brief.schema.json",
 		artifactPath: "artifacts/execution-plan-draft.yaml",
 	},
 	{
 		toolName: "submit_hypothesis_validation",
-		agents: ["harness/planning/hypothesis-validator"],
 		schemaFile: "plan-hypothesis-eval.schema.json",
 		artifactPath: (doc) => roundPath("hypothesis-validation", doc),
 		debateLane: "hypothesis-validation",
 	},
 	{
 		toolName: "submit_validation_turn",
-		agents: ["harness/planning/plan-evaluator"],
 		schemaFile: "plan-validation-turn.schema.json",
 		artifactPath: (doc) => roundPath("validation-turn", doc),
 		debateLane: "validation-turn",
 	},
 	{
 		toolName: "submit_adversary_brief",
-		agents: ["harness/planning/plan-adversary"],
 		schemaFile: "plan-adversary-brief.schema.json",
 		artifactPath: (doc) => roundPath("adversary-brief", doc),
 		debateLane: "adversary-brief",
 	},
 	{
 		toolName: "submit_sprint_audit",
-		agents: ["harness/planning/sprint-contract-auditor"],
 		schemaFile: "plan-sprint-audit-turn.schema.json",
 		artifactPath: (doc) => roundPath("sprint-audit", doc),
 		debateLane: "sprint-audit",
 	},
 	{
 		toolName: "submit_review_round_draft",
-		agents: ["harness/planning/review-integrator"],
 		schemaFile: "plan-review-round-draft.schema.json",
 		artifactPath: (doc) => roundPath("review-round-draft", doc),
 	},
 	{
 		toolName: "submit_executor_handoff",
-		agents: ["harness/running/executor"],
 		schemaFile: "harness-executor-handoff.schema.json",
 		artifactPath: "handoff/executor-summary.yaml",
 	},
 	{
 		toolName: "submit_eval_verdict",
-		agents: ["harness/reviewing/evaluator"],
 		schemaFile: "eval-verdict.schema.json",
 		artifactPath: "artifacts/eval-verdict.yaml",
 	},
 	{
 		toolName: "submit_adversary_report",
-		agents: ["harness/reviewing/adversary"],
 		schemaFile: "adversary-report.schema.json",
 		artifactPath: "artifacts/adversary-report.yaml",
 	},
 	{
 		toolName: "submit_human_required",
-		agents: ["harness/planning/decompose", "harness/planning/hypothesis"],
 		schemaFile: "harness-human-required.schema.json",
 		artifactPath: "artifacts/human-required.yaml",
 		humanRequired: true,
 	},
 	{
 		toolName: "submit_sentrux_manifest_proposal",
-		agents: ["harness/sentrux-steward"],
 		schemaFile: "sentrux-manifest-proposal.schema.json",
 		artifactPath: "artifacts/sentrux-manifest-proposal.yaml",
 	},
 ] as const;
 
-export const SUBMIT_TOOLS_BY_AGENT: Readonly<
-	Record<string, ReadonlySet<string>>
-> = (() => {
-	const map = new Map<string, Set<string>>();
-	for (const spec of SUBMIT_TOOL_SPECS) {
-		for (const agent of spec.agents) {
-			if (!map.has(agent)) map.set(agent, new Set());
-			map.get(agent)?.add(spec.toolName);
-		}
-	}
-	return Object.fromEntries(map.entries());
-})();
-
 export function specForSubmitTool(
 	toolName: string,
 ): SubmitToolSpec | undefined {

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

@@ -7,21 +7,26 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig } from "../../../vendor/pi-subagents/src/agents.js";
+import type { AgentConfig } from "../../vendor/pi-subagents/src/agents.js";
 import {
 	createSubagentsExtension,
 	type HarnessSubagentsOptions,
 	type SpawnAuthForward,
-} from "../../../vendor/pi-subagents/src/subagents.js";
+} from "../../vendor/pi-subagents/src/subagents.js";
+import { subagentGovernanceExtensionPath } from "../extensions/subagent-governance.js";
+import { getAgentKind } from "./agents-policy.mjs";
+import {
+	delegationEnvFromBundle,
+	mintSubagentDelegation,
+} from "./agt/delegation.js";
+import { spawnCircuitOpen } from "./agt/sre-hooks.js";
+import { refreshHarnessCocoindexIndex } from "./harness-cocoindex-refresh.js";
+import { captureHarnessEvent } from "./harness-posthog.js";
 import {
 	getLatestRunContext,
 	getRunIdFromSession,
 	type HarnessPhase,
-} from "../../lib/harness-run-context.js";
-import { parseSpawnContextFromTask } from "../../lib/harness-spawn-parse.js";
-import { harnessSubagentSubmitExtensionPath } from "../harness-subagent-submit.js";
-import { refreshHarnessCocoindexIndex } from "./harness-cocoindex-refresh.js";
-import { captureHarnessEvent } from "./harness-posthog.js";
+} from "./harness-run-context.js";
 import {
 	checkHarnessSpawnBudget,
 	countHarnessAgentsInRequest,
@@ -29,6 +34,11 @@ import {
 	recordSpawnEnd,
 	recordSpawnStart,
 } from "./harness-spawn-budget.js";
+import { parseSpawnContextFromTask } from "./harness-spawn-parse.js";
+import {
+	getRememberedSessionWebArtifactDir,
+	resolveWebArtifactScope,
+} from "./harness-web/artifacts.js";
 import {
 	isUsableApiKey,
 	resolveConcreteSubagentModel,
@@ -111,19 +121,69 @@ async function resolveHarnessSpawnAuth(
 export function createHarnessSubagentsExtension(
 	packageRoot: string,
 ): (pi: ExtensionAPI) => void {
-	const submitExtPath = harnessSubagentSubmitExtensionPath(packageRoot);
+	const governanceExtPath = subagentGovernanceExtensionPath(packageRoot);
 	const options: HarnessSubagentsOptions = {
 		packageRoot,
-		harnessSubprocessExtensionPath: submitExtPath,
+		subprocessGovernanceExtensionPath: governanceExtPath,
+		harnessSubprocessExtensionPath: governanceExtPath,
 		resolveSubprocessEnv: (task, agent) => {
-			if (!agent.name.startsWith("harness/")) return undefined;
+			const projectRoot = process.cwd();
+			const base: Record<string, string> = {
+				PI_HARNESS_SUBPROCESS: "1",
+				HARNESS_AGENT_ID: agent.name,
+				HARNESS_PKG_ROOT: packageRoot,
+				HARNESS_PROJECT_ROOT: projectRoot,
+			};
+			if (agent.name.startsWith("harness/web-retrieval/")) {
+				const ctx = parseSpawnContextFromTask(task);
+				const remembered = getRememberedSessionWebArtifactDir(lastSessionId);
+				if (remembered) {
+					base.HARNESS_WEB_ARTIFACT_DIR = remembered;
+				} else if (ctx?.run_id) {
+					base.HARNESS_WEB_ARTIFACT_DIR = resolveWebArtifactScope({
+						projectRoot,
+						explicitArtifactDir: `.web/runs/${ctx.run_id}`,
+					}).artifactDir;
+				} else {
+					base.HARNESS_WEB_ARTIFACT_DIR = resolveWebArtifactScope({
+						projectRoot,
+						piSessionId: lastSessionId,
+					}).artifactDir;
+				}
+			}
 			const ctx = parseSpawnContextFromTask(task);
-			if (!ctx?.run_id) return undefined;
+			if (!ctx?.run_id) return base;
+			if (spawnCircuitOpen(ctx.run_id)) {
+				return undefined;
+			}
+			const runDir =
+				ctx.run_dir ?? join(packageRoot, ".pi", "harness", "runs", ctx.run_id);
+			const kind = getAgentKind(packageRoot, projectRoot, agent.name);
+			let delegationEnv: Record<string, string> = {};
+			try {
+				const bundle = mintSubagentDelegation({
+					runId: ctx.run_id,
+					runDir,
+					agentId: agent.name,
+					agentKind: kind,
+				});
+				delegationEnv = delegationEnvFromBundle(bundle);
+			} catch {
+				/* identity mint best-effort */
+			}
 			return {
+				...base,
 				HARNESS_RUN_ID: ctx.run_id,
-				HARNESS_RUN_DIR:
-					ctx.run_dir ??
-					join(packageRoot, ".pi", "harness", "runs", ctx.run_id),
+				HARNESS_RUN_DIR: runDir,
+				HARNESS_SUBAGENT_PHASE_HINT:
+					kind === "executor"
+						? "execute"
+						: kind === "evaluator"
+							? "evaluate"
+							: kind === "adversary"
+								? "adversary"
+								: "plan",
+				...delegationEnv,
 			};
 		},
 		defaultAgentScope: "both",

package/.pi/{extensions/lib → lib}/harness-subprocess-bootstrap.ts

@@ -13,7 +13,7 @@ import {
 	loadRunContextForSubprocess,
 	nowIso,
 	policyBootstrapFromRunContext,
-} from "../../lib/harness-run-context.js";
+} from "./harness-run-context.js";
 
 type PolicyState = {
 	phase: "plan" | "execute" | "evaluate" | "adversary" | "merge";