ultimate-pi 0.15.0 → 0.17.0

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

@@ -1,23 +1,32 @@
 /**
  * Resolve concrete LLM credentials for harness subagent subprocesses.
  *
- * Parent sessions often use `router/auto` (pi-model-router). Subagents run with
+ * Parent sessions often use `router/<profile>` (pi-model-router). Subagents run with
  * `--no-extensions`, so they cannot use the logical router provider — they need
  * a real provider/model plus that provider's API key.
+ *
+ * Session-locked routing: subprocess model is chosen once from agent system prompt
+ * complexity (same analysis as parent session lock), not from per-turn parent tier.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { resolveTierFromPrompt } from "../../../vendor/pi-model-router/extensions/routing.js";
+import type {
+	RouterProfile,
+	RouterTier,
+	RoutingRule,
+} from "../../../vendor/pi-model-router/extensions/types.js";
 import type { AgentConfig } from "../../../vendor/pi-subagents/src/agents.js";
 
 const ROUTER_SENTINEL_KEY = "pi-model-router";
 const SENTINEL_API_KEYS = new Set([ROUTER_SENTINEL_KEY, "<authenticated>"]);
 
-type RouterTier = "high" | "medium" | "low";
-
 interface ModelRouterJson {
 	defaultProfile?: string;
-	profiles?: Record<string, Partial<Record<RouterTier, { model?: string }>>>;
+	phaseBias?: number;
+	rules?: RoutingRule[];
+	profiles?: Record<string, RouterProfile>;
 }
 
 export function isUsableApiKey(key: string | undefined): key is string {
@@ -35,7 +44,33 @@ export function parseModelRef(
 	return { provider, modelId };
 }
 
-export function thinkingToRouterTier(thinking?: string): RouterTier {
+/** Planning subagents that should prefer low/medium router tier for latency. */
+const ROUTINE_PLANNING_AGENT_PATHS = new Set([
+	"harness/planning/plan-evaluator",
+	"harness/planning/plan-adversary",
+	"harness/planning/review-integrator",
+	"harness/planning/hypothesis-validator",
+	"harness/planning/sprint-contract-auditor",
+	"harness/planning/scout-structure",
+	"harness/planning/scout-semantic",
+	"harness/planning/decompose",
+	"harness/planning/hypothesis",
+	"harness/planning/stack-research",
+	"harness/planning/plan-validator",
+]);
+
+export function isRoutinePlanningAgent(agentName: string): boolean {
+	return ROUTINE_PLANNING_AGENT_PATHS.has(agentName);
+}
+
+export function thinkingToRouterTier(
+	thinking?: string,
+	agentName?: string,
+): RouterTier {
+	if (agentName && isRoutinePlanningAgent(agentName)) {
+		if (thinking === "high" || thinking === "xhigh") return "medium";
+		return "low";
+	}
 	if (thinking === "high" || thinking === "xhigh") return "high";
 	if (thinking === "off" || thinking === "minimal" || thinking === "low") {
 		return "low";
@@ -43,6 +78,64 @@ export function thinkingToRouterTier(thinking?: string): RouterTier {
 	return "medium";
 }
 
+function loadModelRouterConfig(cwd: string): ModelRouterJson | undefined {
+	const path = join(cwd, ".pi", "model-router.json");
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as ModelRouterJson;
+	} catch {
+		return undefined;
+	}
+}
+
+function resolveRouterProfileEntry(
+	config: ModelRouterJson,
+	profileId: string,
+): { profileId: string; profile: RouterProfile } | undefined {
+	const profiles = config.profiles;
+	if (!profiles) return undefined;
+	const candidates = [
+		profileId,
+		config.defaultProfile ?? "auto",
+		"auto",
+		"opencode-go",
+	];
+	const seen = new Set<string>();
+	for (const id of candidates) {
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const profile = profiles[id];
+		if (profile?.high?.model && profile.medium?.model && profile.low?.model) {
+			return { profileId: id, profile };
+		}
+	}
+	return undefined;
+}
+
+/** Tier from agent system prompt (+ optional task line) for session model lock. */
+export function resolveSubagentRouterTier(
+	cwd: string,
+	profileId: string,
+	agent: AgentConfig,
+	taskSnippet?: string,
+): RouterTier {
+	const config = loadModelRouterConfig(cwd);
+	if (config) {
+		const entry = resolveRouterProfileEntry(config, profileId);
+		if (entry) {
+			return resolveTierFromPrompt(
+				agent.systemPrompt ?? "",
+				taskSnippet?.trim() ?? "",
+				entry.profileId,
+				entry.profile,
+				config.rules,
+				config.phaseBias ?? 0.5,
+			);
+		}
+	}
+	return thinkingToRouterTier(agent.thinking, agent.name);
+}
+
 /** Map router profile tier → concrete `provider/model` from `.pi/model-router.json`. */
 export function resolveRouterConcreteModelRef(
 	cwd: string,
@@ -51,19 +144,10 @@ export function resolveRouterConcreteModelRef(
 ): string | undefined {
 	const path = join(cwd, ".pi", "model-router.json");
 	if (!existsSync(path)) return undefined;
-	let raw: ModelRouterJson;
-	try {
-		raw = JSON.parse(readFileSync(path, "utf8")) as ModelRouterJson;
-	} catch {
-		return undefined;
-	}
-	const profiles = raw.profiles;
-	if (!profiles) return undefined;
-	const profile =
-		profiles[profileId] ??
-		profiles[raw.defaultProfile ?? "auto"] ??
-		profiles.auto;
-	const model = profile?.[tier]?.model;
+	const raw = loadModelRouterConfig(cwd);
+	if (!raw) return undefined;
+	const entry = resolveRouterProfileEntry(raw, profileId);
+	const model = entry?.profile[tier]?.model;
 	return typeof model === "string" && model.includes("/") ? model : undefined;
 }
 
@@ -83,6 +167,7 @@ export function resolveConcreteSubagentModel(
 	cwd: string,
 	parentModel: { provider: string; id: string } | undefined,
 	agent: AgentConfig,
+	taskSnippet?: string,
 ): ConcreteSubagentModel | undefined {
 	if (agent.model && !agent.model.startsWith("router/")) {
 		const parsed = parseModelRef(agent.model);
@@ -109,7 +194,7 @@ export function resolveConcreteSubagentModel(
 		agentIsRouter && agent.model
 			? agent.model.slice("router/".length)
 			: (parentModel?.id ?? "auto");
-	const tier = thinkingToRouterTier(agent.thinking);
+	const tier = resolveSubagentRouterTier(cwd, profileId, agent, taskSnippet);
 	const concrete = resolveRouterConcreteModelRef(cwd, profileId, tier);
 	if (!concrete) return undefined;
 	const parsed = parseModelRef(concrete);

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,
@@ -20,6 +24,9 @@ export type HarnessAgentKind =
 
 const MUTATING_TOOLS = new Set(["write", "edit"]);
 
+/** Planning agents must use submit_* → canonical artifacts/*.yaml, not JSON dumps. */
+const PLANNING_ARTIFACT_JSON_WRITE = /artifacts\/[^\s'"`;]+\.json\b/i;
+
 const PLANNING_BASH_DENY_PATTERNS = [
 	/\bgraphify\s+update\b/i,
 	/\bgraphify\s+extract\b/i,
@@ -107,6 +114,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" };
 	}
 
@@ -131,6 +177,17 @@ export function evaluateHarnessSubagentToolCall(
 
 	if (toolName === "bash") {
 		const command = String(input?.command ?? "");
+		if (
+			kind === "planner" &&
+			command &&
+			PLANNING_ARTIFACT_JSON_WRITE.test(command)
+		) {
+			return {
+				action: "block",
+				reason:
+					"harness-subagent-policy: artifacts must be YAML only — use submit_* (e.g. submit_hypothesis_brief → artifacts/hypothesis.yaml), not bash writes to .json.",
+			};
+		}
 		if (command && isMutatingBash(command)) {
 			return {
 				action: "block",
@@ -153,6 +210,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,
+	};
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Registry: submit tool name → agent allowlist, schema, artifact path.
+ */
+
+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;
+	humanRequired?: boolean;
+}
+
+function roundPath(prefix: string, doc: Record<string, unknown>): string {
+	const r =
+		typeof doc.round_index === "number"
+			? doc.round_index
+			: Number(doc.round_index ?? 1);
+	return `artifacts/${prefix}-r${r}.yaml`;
+}
+
+export const SUBMIT_TOOL_SPECS: readonly SubmitToolSpec[] = [
+	{
+		toolName: "submit_scout_findings",
+		agents: [
+			"harness/planning/scout-graphify",
+			"harness/planning/scout-structure",
+			"harness/planning/scout-semantic",
+		],
+		schemaFile: "plan-scout-findings.schema.json",
+		artifactPath: (doc) => {
+			const lane =
+				typeof doc.lane === "string"
+					? doc.lane
+					: typeof doc.scout_lane === "string"
+						? doc.scout_lane
+						: "graphify";
+			return `artifacts/scout-${lane}.yaml`;
+		},
+	},
+	{
+		toolName: "submit_decomposition_brief",
+		agents: ["harness/planning/decompose"],
+		schemaFile: "plan-decomposition-brief.schema.json",
+		artifactPath: "artifacts/decomposition.yaml",
+	},
+	{
+		toolName: "submit_hypothesis_brief",
+		agents: ["harness/planning/hypothesis"],
+		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"],
+		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/executor"],
+		schemaFile: "harness-executor-handoff.schema.json",
+		artifactPath: "handoff/executor-summary.yaml",
+	},
+	{
+		toolName: "submit_eval_verdict",
+		agents: ["harness/evaluator"],
+		schemaFile: "eval-verdict.schema.json",
+		artifactPath: "artifacts/eval-verdict.yaml",
+	},
+	{
+		toolName: "submit_adversary_report",
+		agents: ["harness/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,
+	},
+] 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 {
+	return SUBMIT_TOOL_SPECS.find((s) => s.toolName === toolName);
+}
+
+export function resolveArtifactRelPath(
+	spec: SubmitToolSpec,
+	doc: Record<string, unknown>,
+): string {
+	if (typeof spec.artifactPath === "function") {
+		return spec.artifactPath(doc);
+	}
+	return spec.artifactPath;
+}
+
+export function isSubmitToolName(toolName: string): boolean {
+	return toolName.startsWith("submit_");
+}
+
+export const DEBATE_AGENT_SUBMIT_TOOL: Readonly<Record<string, string>> = {
+	"harness/planning/hypothesis-validator": "submit_hypothesis_validation",
+	"harness/planning/plan-evaluator": "submit_validation_turn",
+	"harness/planning/plan-adversary": "submit_adversary_brief",
+	"harness/planning/sprint-contract-auditor": "submit_sprint_audit",
+};