ultimate-pi 0.18.1 → 0.19.0

package/.pi/harness/sentrux/architecture.manifest.json

@@ -16,9 +16,15 @@
 		},
 		{
 			"name": "contracts",
-			"paths": [".pi/harness/specs/*", ".pi/harness/docs/*"],
+			"paths": [
+				".pi/harness/specs/*",
+				".pi/harness/docs/*",
+				".pi/harness/policies/*",
+				".pi/harness/agents.policy.yaml",
+				".pi/harness/examples/*"
+			],
 			"order": 1,
-			"description": "Harness schemas, ADRs, and governance docs"
+			"description": "Harness schemas, ADRs, AGT policies, and agents.policy SSOT"
 		},
 		{
 			"name": "runtime",
@@ -39,9 +45,15 @@
 		},
 		{
 			"name": "tooling",
-			"paths": [".pi/scripts/*", "test/*"],
+			"paths": [".pi/scripts/*"],
 			"order": 4,
-			"description": "Harness CLI scripts and tests"
+			"description": "Harness CLI scripts"
+		},
+		{
+			"name": "foundation",
+			"paths": [".pi/lib/*"],
+			"order": 5,
+			"description": "Shared harness/AGT libraries (imported by extensions and scripts)"
 		}
 	],
 	"boundaries": [
@@ -65,6 +77,16 @@
 			"to": ".pi/extensions/*",
 			"reason": "Contracts are data-only JSON schemas; extensions implement behavior"
 		},
+		{
+			"from": ".pi/lib/*",
+			"to": ".pi/extensions/*",
+			"reason": "Foundation lib must not import extension modules"
+		},
+		{
+			"from": ".pi/harness/policies/*",
+			"to": ".pi/extensions/*",
+			"reason": "Declarative AGT YAML must not depend on extension implementation"
+		},
 		{
 			"from": ".pi/scripts/*",
 			"to": ".agents/skills/*",

package/.pi/harness/specs/observation.schema.json

@@ -37,7 +37,8 @@
 				"drift-monitor",
 				"sentrux",
 				"evaluator",
-				"harness-telemetry"
+				"harness-telemetry",
+				"agt-policy"
 			]
 		},
 		"kind": {

package/.pi/lib/agents-policy.d.mts

@@ -0,0 +1,70 @@
+export function packageAgentsPolicyPath(packageRoot: string): string;
+export function projectAgentsPolicyPath(projectRoot: string): string;
+export function projectPoliciesDir(projectRoot: string): string;
+
+export interface AgentPolicySpec {
+	kind: string;
+	effectiveTools: string[];
+	extensionsOff: boolean;
+	readOnly: boolean;
+	maxTurns?: number;
+	thinking?: string;
+	submitTool?: string;
+}
+
+export interface AllowsAgentToolInput {
+	packageRoot: string;
+	projectRoot: string;
+	agentId: string;
+	toolName: string;
+	toolInput?: Record<string, unknown>;
+	isSubprocess?: boolean;
+	isParentOrchestrator?: boolean;
+}
+
+export function loadAgentsPolicyMerged(
+	packageRoot: string,
+	projectRoot: string,
+): {
+	schemaVersion: string;
+	kinds: Map<string, unknown>;
+	agents: Map<string, unknown>;
+	defaults: unknown;
+};
+
+export function resolveEffectiveTools(
+	agentId: string,
+	merged: ReturnType<typeof loadAgentsPolicyMerged>,
+): AgentPolicySpec;
+
+export function getAgentPolicySpec(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): AgentPolicySpec | null;
+
+export function getAgentKind(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): string;
+
+export function isHarnessPlanningAgent(agentId: string): boolean;
+
+export function harnessSubagentPhaseHint(
+	packageRoot: string,
+	projectRoot: string,
+	agentId: string,
+): string | null;
+
+export function allowsAgentTool(input: AllowsAgentToolInput): boolean;
+
+export function applyAgentPolicyToConfig<T extends { name: string }>(
+	agent: T,
+	packageRoot: string,
+	projectRoot: string,
+): T;
+
+export function findProjectRootFromAgentsDir(projectAgentsDir: string): string;
+
+export function isAgtGovernanceActive(projectRoot: string): boolean;

package/.pi/lib/agents-policy.mjs

@@ -0,0 +1,325 @@
+/**
+ * agents.policy.yaml loader — package + project merge (SSOT for agent tools).
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+const BUILTIN_DENY_TOOLS = new Set([
+	"subagent",
+	"Agent",
+	"get_subagent_result",
+	"steer_subagent",
+	"blackboard",
+]);
+
+const PLANNING_BASH_DENY_PATTERNS = [
+	/\bgraphify\s+update\b/i,
+	/\bgraphify\s+extract\b/i,
+	/\bgraphify\s+install\b/i,
+	/\bccc\s+(index|init|reset|daemon)\b/i,
+	/\bccc\s+search\b.*--refresh/i,
+	/\bpip\s+install\b/i,
+	/\buv\s+tool\s+install\b/i,
+	/\bnpm\s+install\b/i,
+];
+
+const PLANNING_ARTIFACT_JSON_WRITE = /artifacts\/[^\s'"`;]+\.json\b/i;
+
+const MUTATING_TOOLS = new Set(["write", "edit"]);
+
+const cache = new Map();
+
+export function packageAgentsPolicyPath(packageRoot) {
+	return join(packageRoot, ".pi", "harness", "agents.policy.yaml");
+}
+
+export function projectAgentsPolicyPath(projectRoot) {
+	return join(projectRoot, ".pi", "agents.policy.yaml");
+}
+
+export function projectPoliciesDir(projectRoot) {
+	return join(projectRoot, ".pi", "policies");
+}
+
+function readYamlFile(path) {
+	if (!existsSync(path)) return null;
+	try {
+		return parseYaml(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function normalizeKindEntry(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const tools = Array.isArray(raw.tools) ? raw.tools.map(String) : [];
+	return {
+		tools,
+		extensions: raw.extensions === false ? false : Boolean(raw.extensions),
+		readOnly: raw.read_only === true,
+		maxTurns:
+			typeof raw.max_turns === "number" && raw.max_turns > 0
+				? raw.max_turns
+				: undefined,
+		thinking:
+			typeof raw.thinking === "string" && raw.thinking.trim()
+				? raw.thinking.trim()
+				: undefined,
+	};
+}
+
+function normalizeAgentEntry(raw) {
+	if (!raw || typeof raw !== "object") return {};
+	const toolsAdd = Array.isArray(raw.tools_add)
+		? raw.tools_add.map(String)
+		: Array.isArray(raw.tools)
+			? raw.tools.map(String)
+			: [];
+	return {
+		kind: typeof raw.kind === "string" ? raw.kind.trim() : undefined,
+		toolsAdd,
+		toolsDeny: Array.isArray(raw.tools_deny)
+			? raw.tools_deny.map(String)
+			: [],
+		submitTool:
+			typeof raw.submit_tool === "string" ? raw.submit_tool.trim() : undefined,
+		extensions:
+			raw.extensions === false
+				? false
+				: raw.extensions === true
+					? true
+					: undefined,
+		maxTurns:
+			typeof raw.max_turns === "number" && raw.max_turns > 0
+				? raw.max_turns
+				: undefined,
+		thinking:
+			typeof raw.thinking === "string" && raw.thinking.trim()
+				? raw.thinking.trim()
+				: undefined,
+	};
+}
+
+export function loadAgentsPolicyMerged(packageRoot, projectRoot) {
+	const key = `${packageRoot}\0${projectRoot}`;
+	if (cache.has(key)) return cache.get(key);
+
+	const pkgDoc = readYamlFile(packageAgentsPolicyPath(packageRoot)) ?? {};
+	const projDoc = readYamlFile(projectAgentsPolicyPath(projectRoot)) ?? {};
+
+	const kinds = new Map();
+	for (const [name, raw] of Object.entries(pkgDoc.kinds ?? {})) {
+		const k = normalizeKindEntry(raw);
+		if (k) kinds.set(name, k);
+	}
+	for (const [name, raw] of Object.entries(projDoc.kinds ?? {})) {
+		const k = normalizeKindEntry(raw);
+		if (k) kinds.set(name, k);
+	}
+
+	const agents = new Map();
+	for (const [id, raw] of Object.entries(pkgDoc.agents ?? {})) {
+		agents.set(id, normalizeAgentEntry(raw));
+	}
+	for (const [id, raw] of Object.entries(projDoc.agents ?? {})) {
+		const prev = agents.get(id) ?? {};
+		const next = normalizeAgentEntry(raw);
+		agents.set(id, {
+			...prev,
+			...next,
+			toolsAdd: [...new Set([...(prev.toolsAdd ?? []), ...(next.toolsAdd ?? [])])],
+			toolsDeny: [...new Set([...(prev.toolsDeny ?? []), ...(next.toolsDeny ?? [])])],
+		});
+	}
+
+	const merged = {
+		schemaVersion: String(pkgDoc.apiVersion ?? projDoc.apiVersion ?? "harness.toolkit/v1"),
+		kinds,
+		agents,
+		defaults: normalizeAgentEntry(projDoc.defaults ?? pkgDoc.defaults ?? {}),
+	};
+	cache.set(key, merged);
+	return merged;
+}
+
+export function resolveEffectiveTools(agentId, merged) {
+	const entry = merged.agents.get(agentId) ?? merged.defaults;
+	const kindName = entry.kind ?? "other";
+	const kind = merged.kinds.get(kindName) ?? merged.kinds.get("other") ?? {
+		tools: ["read", "grep", "find", "ls"],
+		extensions: false,
+		readOnly: true,
+	};
+
+	const base = new Set(kind.tools);
+	for (const t of entry.toolsAdd ?? []) base.add(t);
+	for (const t of entry.toolsDeny ?? []) base.delete(t);
+	for (const t of BUILTIN_DENY_TOOLS) base.delete(t);
+
+	return {
+		kind: kindName,
+		effectiveTools: [...base],
+		extensionsOff: entry.extensions === true ? false : entry.extensions === false ? true : !kind.extensions,
+		readOnly: kind.readOnly,
+		maxTurns: entry.maxTurns ?? kind.maxTurns,
+		thinking: entry.thinking ?? kind.thinking,
+		submitTool: entry.submitTool,
+	};
+}
+
+export function getAgentPolicySpec(packageRoot, projectRoot, agentId) {
+	const merged = loadAgentsPolicyMerged(packageRoot, projectRoot);
+	if (!merged.agents.has(agentId) && !merged.defaults?.kind) {
+		return null;
+	}
+	return resolveEffectiveTools(agentId, merged);
+}
+
+export function getAgentKind(packageRoot, projectRoot, agentId) {
+	const spec = getAgentPolicySpec(packageRoot, projectRoot, agentId);
+	if (spec) return spec.kind;
+	if (agentId.startsWith("harness/planning/")) return "planner";
+	if (agentId === "harness/running/executor") return "executor";
+	if (agentId === "harness/reviewing/evaluator") return "evaluator";
+	if (agentId === "harness/reviewing/adversary") return "adversary";
+	if (agentId === "harness/reviewing/tie-breaker") return "tie_breaker";
+	if (agentId === "harness/meta-optimizer") return "meta";
+	if (agentId === "harness/trace-librarian") return "trace";
+	if (agentId === "harness/incident-recorder") return "incident";
+	return "other";
+}
+
+export function isHarnessPlanningAgent(agentId) {
+	return agentId.startsWith("harness/planning/");
+}
+
+export function harnessSubagentPhaseHint(packageRoot, projectRoot, agentId) {
+	if (isHarnessPlanningAgent(agentId)) return "plan";
+	const kind = getAgentKind(packageRoot, projectRoot, agentId);
+	switch (kind) {
+		case "planner":
+			return "plan";
+		case "executor":
+			return "execute";
+		case "evaluator":
+			return "evaluate";
+		case "adversary":
+			return "adversary";
+		default:
+			return null;
+	}
+}
+
+function isMutatingBash(command) {
+	if (!command) return false;
+	return /\b(rm\s+-rf|git\s+(push|commit|reset|checkout|merge|rebase)|npm\s+run|make\b|docker\s+)/i.test(
+		command,
+	);
+}
+
+/**
+ * Manifest allowlist + subprocess constraints (replaces harness-subagent-policy.ts).
+ */
+export function allowsAgentTool(input) {
+	const {
+		packageRoot,
+		projectRoot,
+		agentId,
+		toolName,
+		toolInput = {},
+		isSubprocess = false,
+		isParentOrchestrator = false,
+	} = input;
+
+	if (isParentOrchestrator) {
+		if (toolName.startsWith("submit_")) return false;
+		return true;
+	}
+
+	const spec = getAgentPolicySpec(packageRoot, projectRoot, agentId);
+	if (!spec) return false;
+
+	if (!spec.effectiveTools.includes(toolName)) return false;
+
+	if (toolName.startsWith("submit_")) {
+		if (!isSubprocess) return false;
+		if (toolName === "submit_human_required" && agentId === "harness/running/executor") {
+			return false;
+		}
+	}
+
+	if (MUTATING_TOOLS.has(toolName) && spec.readOnly) return false;
+
+	if (toolName === "ctx_batch_execute" && spec.readOnly) {
+		const commands = toolInput.commands;
+		if (Array.isArray(commands)) {
+			for (const c of commands) {
+				const cmd =
+					typeof c === "string"
+						? c
+						: String(c?.command ?? c?.code ?? "");
+				if (cmd && isMutatingBash(cmd)) return false;
+			}
+		}
+	}
+
+	if (toolName === "ctx_execute" && spec.readOnly) {
+		const code = String(toolInput.code ?? toolInput.command ?? "");
+		if (code && isMutatingBash(code)) return false;
+	}
+
+	if (toolName === "bash" && spec.readOnly) {
+		const command = String(toolInput.command ?? "");
+		if (command && isMutatingBash(command)) return false;
+		if (
+			isHarnessPlanningAgent(agentId) &&
+			command &&
+			PLANNING_ARTIFACT_JSON_WRITE.test(command)
+		) {
+			return false;
+		}
+		if (
+			isHarnessPlanningAgent(agentId) &&
+			command &&
+			PLANNING_BASH_DENY_PATTERNS.some((p) => p.test(command))
+		) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export function applyAgentPolicyToConfig(agent, packageRoot, projectRoot) {
+	const spec = getAgentPolicySpec(packageRoot, projectRoot, agent.name);
+	if (!spec) return agent;
+	return {
+		...agent,
+		tools: spec.effectiveTools.length > 0 ? spec.effectiveTools : undefined,
+		extensionsOff: spec.extensionsOff,
+		maxTurns: spec.maxTurns ?? agent.maxTurns,
+		thinking: spec.thinking ?? agent.thinking,
+	};
+}
+
+export function findProjectRootFromAgentsDir(projectAgentsDir) {
+	if (!projectAgentsDir) return process.cwd();
+	const piDir = dirname(projectAgentsDir);
+	if (piDir.endsWith("/.pi") || piDir.endsWith("\\.pi")) {
+		return dirname(piDir);
+	}
+	return process.cwd();
+}
+
+export function isAgtGovernanceActive(projectRoot) {
+	if (existsSync(projectAgentsPolicyPath(projectRoot))) return true;
+	const polDir = projectPoliciesDir(projectRoot);
+	if (!existsSync(polDir)) return false;
+	try {
+		return readdirSync(polDir).some((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+	} catch {
+		return false;
+	}
+}

package/.pi/lib/agents-policy.ts

@@ -0,0 +1,19 @@
+/**
+ * agents.policy.yaml — TypeScript surface (implementation in agents-policy.mjs).
+ */
+
+export {
+	allowsAgentTool,
+	applyAgentPolicyToConfig,
+	findProjectRootFromAgentsDir,
+	getAgentKind,
+	getAgentPolicySpec,
+	harnessSubagentPhaseHint,
+	isAgtGovernanceActive,
+	isHarnessPlanningAgent,
+	loadAgentsPolicyMerged,
+	packageAgentsPolicyPath,
+	projectAgentsPolicyPath,
+	projectPoliciesDir,
+	resolveEffectiveTools,
+} from "./agents-policy.mjs";

package/.pi/lib/agt/audit-run-sink.ts

@@ -0,0 +1,52 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { AuditLogger } from "@microsoft/agent-governance-sdk";
+
+const loggers = new Map<string, AuditLogger>();
+
+export function getAuditLoggerForRun(runDir: string): AuditLogger {
+	const key = runDir;
+	let logger = loggers.get(key);
+	if (!logger) {
+		logger = new AuditLogger();
+		loggers.set(key, logger);
+	}
+	return logger;
+}
+
+export function appendPolicyAuditEvent(input: {
+	runDir: string;
+	runId: string;
+	toolName: string;
+	allowed: boolean;
+	reason: string;
+	agentDid: string;
+	phase: string;
+}): void {
+	const logger = getAuditLoggerForRun(input.runDir);
+	logger.log({
+		action: `tool.${input.toolName}:${input.phase}:${input.reason}`,
+		agentId: input.agentDid,
+		decision: input.allowed ? "allow" : "deny",
+	});
+	const auditPath = join(input.runDir, "agt-audit.jsonl");
+	mkdirSync(input.runDir, { recursive: true });
+	appendFileSync(
+		auditPath,
+		`${JSON.stringify({
+			ts: new Date().toISOString(),
+			run_id: input.runId,
+			tool: input.toolName,
+			allowed: input.allowed,
+			reason: input.reason,
+			agent_did: input.agentDid,
+			phase: input.phase,
+		})}\n`,
+	);
+}
+
+export function verifyRunAuditChain(runDir: string): boolean {
+	const logger = loggers.get(runDir);
+	if (!logger) return true;
+	return logger.verify();
+}