ultimate-pi 0.18.0 → 0.19.0

package/.pi/lib/agt/delegation.ts

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getOrCreateParentIdentity } from "./identity-registry.js";
+
+const ROLE_CAPABILITIES: Record<string, string[]> = {
+	planner: ["harness.read", "harness.submit.plan"],
+	executor: ["harness.read", "harness.write", "harness.submit.run"],
+	evaluator: ["harness.read", "harness.submit.review"],
+	adversary: ["harness.read", "harness.submit.review"],
+	tie_breaker: ["harness.read", "harness.submit.review"],
+	meta: ["harness.read"],
+	trace: ["harness.read"],
+	incident: ["harness.read"],
+	other: ["harness.read"],
+};
+
+export function capabilitiesForHarnessAgent(
+	agentId: string,
+	kind: string,
+): string[] {
+	if (agentId.startsWith("harness/planning/")) {
+		return ROLE_CAPABILITIES.planner ?? ["harness.read"];
+	}
+	return ROLE_CAPABILITIES[kind] ?? ROLE_CAPABILITIES.other;
+}
+
+export interface DelegationBundle {
+	agentDid: string;
+	delegationCeiling: number;
+	identityPath: string;
+}
+
+export function mintSubagentDelegation(input: {
+	runId: string;
+	runDir: string;
+	agentId: string;
+	agentKind: string;
+	trustCeiling?: number;
+}): DelegationBundle {
+	const parent = getOrCreateParentIdentity(input.runId, input.runDir);
+	const caps = capabilitiesForHarnessAgent(input.agentId, input.agentKind);
+	const safeId = input.agentId.replace(/\//g, "_");
+	const agentDir = join(input.runDir, "agents", safeId);
+	mkdirSync(agentDir, { recursive: true });
+
+	const child = parent.delegate(`harness-${safeId}`, caps, {
+		description: `Harness subagent ${input.agentId}`,
+	});
+	writeFileSync(
+		join(agentDir, "identity.json"),
+		JSON.stringify(child.toJSON(), null, 2),
+	);
+
+	const ceiling = input.trustCeiling ?? 1;
+	return {
+		agentDid: child.did,
+		delegationCeiling: ceiling,
+		identityPath: join(agentDir, "identity.json"),
+	};
+}
+
+export function delegationEnvFromBundle(
+	bundle: DelegationBundle,
+): Record<string, string> {
+	return {
+		HARNESS_AGENT_DID: bundle.agentDid,
+		HARNESS_DELEGATION_CEILING: String(bundle.delegationCeiling),
+	};
+}

package/.pi/lib/agt/evaluate-policy.ts

@@ -0,0 +1,56 @@
+import type { PolicyDecisionResult } from "@microsoft/agent-governance-sdk";
+import type { BuildEvaluationContextInput } from "./build-evaluation-context.js";
+import { buildHarnessAgtEvaluationContext } from "./build-evaluation-context.js";
+import { isHarnessAgtPolicyEnabled } from "./config.js";
+import { evaluateLegacyHarnessToolPolicy } from "./legacy-evaluate.js";
+import { getAgtPolicyEngine } from "./policy-engine.js";
+
+export interface HarnessPolicyEvaluation {
+	allowed: boolean;
+	reason: string;
+	source: "agt" | "legacy";
+	agt?: PolicyDecisionResult;
+}
+
+export async function evaluateHarnessToolPolicy(
+	packageRoot: string,
+	input: BuildEvaluationContextInput,
+): Promise<HarnessPolicyEvaluation> {
+	if (!isHarnessAgtPolicyEnabled()) {
+		const legacy = await evaluateLegacyHarnessToolPolicy(input);
+		return {
+			allowed: legacy.allowed,
+			reason: legacy.reason,
+			source: "legacy",
+		};
+	}
+
+	try {
+		const context = await buildHarnessAgtEvaluationContext(input);
+		const engine = getAgtPolicyEngine(packageRoot, input.projectRoot);
+		const agentDid = String(context.agent_did ?? context.harness_agent_id);
+		const result = engine.evaluatePolicy(agentDid, context);
+		if (!result.allowed) {
+			return {
+				allowed: false,
+				reason:
+					result.reason ??
+					`agt-policy: denied by ${result.policyName ?? "policy"}/${result.matchedRule ?? "rule"}`,
+				source: "agt",
+				agt: result,
+			};
+		}
+		return {
+			allowed: true,
+			reason: result.reason ?? "allow",
+			source: "agt",
+			agt: result,
+		};
+	} catch (err) {
+		return {
+			allowed: false,
+			reason: `agt-policy: evaluation failed (fail-closed): ${String(err)}`,
+			source: "agt",
+		};
+	}
+}

package/.pi/lib/agt/identity-registry.ts

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AgentIdentity } from "@microsoft/agent-governance-sdk";
+
+const runRoots = new Map<string, AgentIdentity>();
+
+export function getOrCreateParentIdentity(
+	runId: string,
+	runDir: string,
+): AgentIdentity {
+	const cached = runRoots.get(runId);
+	if (cached) return cached;
+
+	const agentsDir = join(runDir, "agents", "_parent");
+	const identityPath = join(agentsDir, "identity.json");
+	mkdirSync(agentsDir, { recursive: true });
+
+	if (existsSync(identityPath)) {
+		const json = JSON.parse(readFileSync(identityPath, "utf-8"));
+		const restored = AgentIdentity.fromJSON(json);
+		runRoots.set(runId, restored);
+		return restored;
+	}
+
+	const identity = AgentIdentity.generate(`harness-parent-${runId}`, [
+		"harness.orchestrate",
+		"harness.delegate",
+		"harness.plan",
+		"harness.execute",
+	]);
+	writeFileSync(identityPath, JSON.stringify(identity.toJSON(), null, 2));
+	runRoots.set(runId, identity);
+	return identity;
+}
+
+export function loadChildIdentity(agentDir: string): AgentIdentity | null {
+	const identityPath = join(agentDir, "identity.json");
+	if (!existsSync(identityPath)) return null;
+	const json = JSON.parse(readFileSync(identityPath, "utf-8"));
+	return AgentIdentity.fromJSON(json);
+}

package/.pi/lib/agt/index.ts

@@ -0,0 +1,55 @@
+export {
+	appendPolicyAuditEvent,
+	verifyRunAuditChain,
+} from "./audit-run-sink.js";
+export type {
+	BuildEvaluationContextInput,
+	HarnessAgtContext,
+} from "./build-evaluation-context.js";
+export {
+	buildHarnessAgtEvaluationContext,
+	buildHarnessAgtEvaluationContextFromRun,
+} from "./build-evaluation-context.js";
+export {
+	isHarnessAgtPolicyEnabled,
+	resolveHarnessPackageRootFromEnv,
+	resolveHarnessPoliciesDir,
+} from "./config.js";
+export {
+	capabilitiesForHarnessAgent,
+	delegationEnvFromBundle,
+	mintSubagentDelegation,
+} from "./delegation.js";
+export type { HarnessPolicyEvaluation } from "./evaluate-policy.js";
+export { evaluateHarnessToolPolicy } from "./evaluate-policy.js";
+export {
+	getOrCreateParentIdentity,
+	loadChildIdentity,
+} from "./identity-registry.js";
+export { evaluateLegacyHarnessToolPolicy } from "./legacy-evaluate.js";
+export {
+	createAgtPolicyEngine,
+	createHarnessPolicyEngine,
+	doctorHarnessPolicies,
+	getAgtPolicyEngine,
+	getHarnessPolicyEngine,
+	HarnessPolicyLoadError,
+	resetHarnessPolicyEngineCache,
+} from "./policy-engine.js";
+export { createRingEnforcer, ringForHarnessAgentKind } from "./rings.js";
+export {
+	getHarnessGovernanceMetrics,
+	isSreEnforceEnabled,
+	recordSpawnAttempt,
+	spawnCircuitOpen,
+} from "./sre-hooks.js";
+export {
+	getTrustManagerForRun,
+	recordPolicyAllow,
+	recordPolicyDeny,
+	trustScoreForAgent,
+} from "./trust-run-store.js";
+export {
+	workflowBlocked,
+	workflowFlagsFromEntries,
+} from "./workflow-history.js";

package/.pi/lib/agt/kill-switch-state.ts

@@ -0,0 +1,11 @@
+const denyCounts = new Map<string, number>();
+
+export function recordHarnessPolicyDeny(sessionId: string): number {
+	const n = (denyCounts.get(sessionId) ?? 0) + 1;
+	denyCounts.set(sessionId, n);
+	return n;
+}
+
+export function resetHarnessPolicyDenyCount(sessionId: string): void {
+	denyCounts.delete(sessionId);
+}

package/.pi/lib/agt/legacy-evaluate.ts

@@ -0,0 +1,101 @@
+import { allowsAgentTool } from "../agents-policy.mjs";
+import { evaluateContextModeMutation } from "../harness-context-mode-policy.js";
+import {
+	extractWritePathFromToolInput,
+	getLatestRunContext,
+	isPlanPhaseAllowedMutation,
+} from "../harness-run-context.js";
+import { evaluateSubagentToolCall } from "../harness-spawn-policy.js";
+import type { BuildEvaluationContextInput } from "./build-evaluation-context.js";
+import {
+	buildHarnessAgtEvaluationContext,
+	type HarnessAgtContext,
+	harnessSessionToolDenyReason,
+} from "./build-evaluation-context.js";
+
+/** Combined legacy path for HARNESS_AGT_POLICY=0 parity tests. */
+export async function evaluateLegacyHarnessToolPolicy(
+	input: BuildEvaluationContextInput,
+): Promise<{ allowed: boolean; reason: string; context?: HarnessAgtContext }> {
+	const { toolName, toolInput, policyState, entries, projectRoot, sessionId } =
+		input;
+	const agentId =
+		process.env.PI_HARNESS_SUBPROCESS === "1"
+			? (process.env.HARNESS_AGENT_ID?.trim() ?? "harness/unknown")
+			: "parent-orchestrator";
+	const isSubprocess = process.env.PI_HARNESS_SUBPROCESS === "1";
+	const isParent = agentId === "parent-orchestrator";
+
+	const spawn = evaluateSubagentToolCall(toolName, agentId);
+	if (spawn.action === "block") {
+		return { allowed: false, reason: spawn.reason ?? "spawn policy" };
+	}
+
+	if (
+		!allowsAgentTool({
+			packageRoot: input.packageRoot,
+			projectRoot,
+			agentId,
+			toolName,
+			toolInput,
+			isSubprocess,
+			isParentOrchestrator: isParent,
+		})
+	) {
+		return {
+			allowed: false,
+			reason: `agents-policy: ${toolName} not allowed for ${agentId}`,
+		};
+	}
+
+	const runCtx = getLatestRunContext(entries);
+	const phase = policyState.phase;
+	const bashCommand =
+		toolName === "bash" ? String(toolInput.command ?? "") : "";
+
+	if (toolName === "write" || toolName === "edit") {
+		const planMutation = await isPlanPhaseAllowedMutation(
+			toolName,
+			toolInput,
+			phase,
+			runCtx,
+			projectRoot,
+			{
+				aborted: policyState.aborted,
+				entries,
+				ownerSessionId: runCtx?.owner_pi_session_id,
+				currentSessionId: sessionId,
+			},
+		);
+		if (!planMutation.allowed) {
+			return {
+				allowed: false,
+				reason: planMutation.reason ?? "plan phase mutation blocked",
+			};
+		}
+	}
+
+	const ctxMode = evaluateContextModeMutation(toolName, toolInput, phase, {
+		aborted: policyState.aborted,
+		budgetBypass: policyState.budgetBypass,
+		readOnlyAgent: false,
+	});
+	if (ctxMode.blocked) {
+		return { allowed: false, reason: ctxMode.reason };
+	}
+
+	const sessionDeny = harnessSessionToolDenyReason({
+		toolName,
+		toolInput,
+		phase,
+		agentId,
+		entries,
+		aborted: policyState.aborted,
+	});
+	if (sessionDeny) {
+		return { allowed: false, reason: sessionDeny };
+	}
+
+	const context = await buildHarnessAgtEvaluationContext(input);
+	return { allowed: true, reason: "legacy allow", context };
+}

package/.pi/lib/agt/policy-engine.ts

@@ -0,0 +1,154 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	ConflictResolutionStrategy,
+	PolicyEngine,
+} from "@microsoft/agent-governance-sdk";
+import {
+	resolveHarnessPoliciesDir,
+	resolveProjectPoliciesDir,
+} from "./config.js";
+
+const PACKAGE_POLICY_FILES = [
+	"defaults.yaml",
+	"phases.yaml",
+	"roles.yaml",
+	"orchestrator.yaml",
+	"bash-denylists.yaml",
+	"web-guard.yaml",
+	"workflow-sequences.yaml",
+] as const;
+
+let cachedEngine: PolicyEngine | null = null;
+let cachedKey: string | null = null;
+
+export class HarnessPolicyLoadError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "HarnessPolicyLoadError";
+	}
+}
+
+function loadYamlFile(engine: PolicyEngine, path: string): void {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch (err) {
+		throw new HarnessPolicyLoadError(
+			`Missing or unreadable policy file: ${path} (${String(err)})`,
+		);
+	}
+	engine.loadYaml(raw);
+}
+
+function loadProjectPolicyDir(
+	engine: PolicyEngine,
+	projectRoot: string,
+): string[] {
+	const dir = resolveProjectPoliciesDir(projectRoot);
+	const loaded: string[] = [];
+	if (!existsSync(dir)) return loaded;
+	const names = readdirSync(dir)
+		.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+		.sort();
+	for (const name of names) {
+		loadYamlFile(engine, join(dir, name));
+		loaded.push(name);
+	}
+	return loaded;
+}
+
+export interface CreateAgtPolicyEngineInput {
+	packageRoot: string;
+	projectRoot: string;
+}
+
+export function createAgtPolicyEngine(
+	input: CreateAgtPolicyEngineInput,
+): PolicyEngine {
+	const engine = new PolicyEngine([], ConflictResolutionStrategy.DenyOverrides);
+	const dir = resolveHarnessPoliciesDir(input.packageRoot);
+	for (const file of PACKAGE_POLICY_FILES) {
+		loadYamlFile(engine, join(dir, file));
+	}
+	loadProjectPolicyDir(engine, input.projectRoot);
+	return engine;
+}
+
+/** @deprecated Use createAgtPolicyEngine */
+export function createHarnessPolicyEngine(packageRoot: string): PolicyEngine {
+	return createAgtPolicyEngine({
+		packageRoot,
+		projectRoot: process.cwd(),
+	});
+}
+
+export function getAgtPolicyEngine(
+	packageRoot: string,
+	projectRoot: string,
+): PolicyEngine {
+	const key = `${packageRoot}\0${projectRoot}`;
+	if (cachedEngine && cachedKey === key) return cachedEngine;
+	cachedEngine = createAgtPolicyEngine({ packageRoot, projectRoot });
+	cachedKey = key;
+	return cachedEngine;
+}
+
+export function getHarnessPolicyEngine(packageRoot: string): PolicyEngine {
+	return getAgtPolicyEngine(packageRoot, process.cwd());
+}
+
+export function resetHarnessPolicyEngineCache(): void {
+	cachedEngine = null;
+	cachedKey = null;
+}
+
+/** Doctor: policies dir exists and all expected YAML files present. */
+export function doctorHarnessPolicies(
+	packageRoot: string,
+	projectRoot = process.cwd(),
+): {
+	ok: boolean;
+	errors: string[];
+	policyDir: string;
+	loaded: string[];
+	projectLoaded: string[];
+} {
+	const errors: string[] = [];
+	const policyDir = resolveHarnessPoliciesDir(packageRoot);
+	if (!existsSync(policyDir)) {
+		errors.push(`policy directory missing: ${policyDir}`);
+	}
+	const loaded: string[] = [];
+	for (const file of PACKAGE_POLICY_FILES) {
+		const path = join(policyDir, file);
+		if (!existsSync(path)) {
+			errors.push(`missing policy file: ${path}`);
+			continue;
+		}
+		loaded.push(file);
+	}
+	let projectLoaded: string[] = [];
+	try {
+		const names = readdirSync(policyDir).filter((f) => f.endsWith(".yaml"));
+		if (names.length === 0) {
+			errors.push(`no YAML policies in ${policyDir}`);
+		}
+	} catch (err) {
+		errors.push(`cannot read policy dir: ${String(err)}`);
+	}
+	if (errors.length === 0) {
+		try {
+			createAgtPolicyEngine({ packageRoot, projectRoot });
+			const projDir = resolveProjectPoliciesDir(projectRoot);
+			if (existsSync(projDir)) {
+				projectLoaded = readdirSync(projDir).filter(
+					(f) => f.endsWith(".yaml") || f.endsWith(".yml"),
+				);
+			}
+		} catch (err) {
+			errors.push(`PolicyEngine load failed: ${String(err)}`);
+		}
+	}
+	return { ok: errors.length === 0, errors, policyDir, loaded, projectLoaded };
+}

package/.pi/lib/agt/rings.ts

@@ -0,0 +1,21 @@
+import { ExecutionRing, RingEnforcer } from "@microsoft/agent-governance-sdk";
+
+const KIND_RING: Record<string, ExecutionRing> = {
+	planner: ExecutionRing.Ring0,
+	executor: ExecutionRing.Ring2,
+	evaluator: ExecutionRing.Ring0,
+	adversary: ExecutionRing.Ring3,
+	tie_breaker: ExecutionRing.Ring0,
+	meta: ExecutionRing.Ring0,
+	trace: ExecutionRing.Ring0,
+	incident: ExecutionRing.Ring0,
+	other: ExecutionRing.Ring3,
+};
+
+export function ringForHarnessAgentKind(kind: string): ExecutionRing {
+	return KIND_RING[kind] ?? ExecutionRing.Ring3;
+}
+
+export function createRingEnforcer(): RingEnforcer {
+	return new RingEnforcer();
+}

package/.pi/lib/agt/sre-hooks.ts

@@ -0,0 +1,45 @@
+import {
+	CircuitBreaker,
+	GovernanceMetrics,
+} from "@microsoft/agent-governance-sdk";
+
+let metrics: GovernanceMetrics | null = null;
+const breakers = new Map<string, CircuitBreaker>();
+
+export function getHarnessGovernanceMetrics(): GovernanceMetrics {
+	if (!metrics) {
+		metrics = new GovernanceMetrics();
+	}
+	return metrics;
+}
+
+export function getSpawnCircuitBreaker(runId: string): CircuitBreaker {
+	let cb = breakers.get(runId);
+	if (!cb) {
+		cb = new CircuitBreaker(5, 60_000);
+		breakers.set(runId, cb);
+	}
+	return cb;
+}
+
+export function isSreEnforceEnabled(): boolean {
+	return process.env.HARNESS_AGT_SRE_ENFORCE === "1";
+}
+
+export function recordSpawnAttempt(runId: string, ok: boolean): void {
+	const cb = getSpawnCircuitBreaker(runId);
+	if (ok) {
+		cb.onSuccess();
+	} else {
+		cb.onFailure();
+	}
+	getHarnessGovernanceMetrics().recordPolicyDecision(ok ? "allow" : "deny", 0, {
+		run_id: runId,
+		kind: "harness_spawn",
+	});
+}
+
+export function spawnCircuitOpen(runId: string): boolean {
+	if (!isSreEnforceEnabled()) return false;
+	return !getSpawnCircuitBreaker(runId).canExecute();
+}

package/.pi/lib/agt/trust-run-store.ts

@@ -0,0 +1,26 @@
+import { TrustManager } from "@microsoft/agent-governance-sdk";
+
+const stores = new Map<string, TrustManager>();
+
+export function getTrustManagerForRun(runId: string): TrustManager {
+	let tm = stores.get(runId);
+	if (!tm) {
+		tm = new TrustManager({ initialScore: 0.85, decayFactor: 0.98 });
+		stores.set(runId, tm);
+	}
+	return tm;
+}
+
+export function recordPolicyDeny(runId: string, agentDid: string): void {
+	const tm = getTrustManagerForRun(runId);
+	tm.recordFailure(agentDid, 0.08);
+}
+
+export function recordPolicyAllow(runId: string, agentDid: string): void {
+	const tm = getTrustManagerForRun(runId);
+	tm.recordSuccess(agentDid, 0.02);
+}
+
+export function trustScoreForAgent(runId: string, agentDid: string): number {
+	return getTrustManagerForRun(runId).getTrustScore(agentDid).overall;
+}

package/.pi/lib/agt/workflow-history.ts

@@ -0,0 +1,29 @@
+/** Lightweight workflow flags from session custom entries (observation-bus parity). */
+
+type EntryLike = {
+	type?: string;
+	customType?: string;
+	data?: { kind?: string; flags?: string[] };
+};
+
+export function workflowFlagsFromEntries(entries: unknown[]): Set<string> {
+	const flags = new Set<string>();
+	for (const raw of entries) {
+		const entry = raw as EntryLike;
+		if (entry.type !== "custom") continue;
+		if (entry.customType !== "harness-observation") continue;
+		const data = entry.data;
+		if (!data?.flags) continue;
+		for (const f of data.flags) {
+			if (typeof f === "string") flags.add(f);
+		}
+	}
+	return flags;
+}
+
+export function workflowBlocked(
+	flags: Set<string>,
+	requiredPrior: string,
+): boolean {
+	return !flags.has(requiredPrior);
+}

package/.pi/lib/agt-governance-active.ts

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { isAgtGovernanceActive as hasProjectAgtFiles } from "./agents-policy.mjs";
+import { isHarnessProjectEnabled } from "./harness-project-config.js";
+
+/** Subprocess AGT + merged policies when harness is on or project declares policy files. */
+export function isAgtGovernanceActive(projectRoot?: string): boolean {
+	const root = projectRoot ?? process.cwd();
+	if (isHarnessProjectEnabled(root)) return true;
+	return hasProjectAgtFiles(root);
+}
+
+export function projectHasPolicyDir(projectRoot: string): boolean {
+	return hasProjectAgtFiles(projectRoot);
+}