ultimate-pi 0.3.1 → 0.4.0

package/.pi/extensions/lib/harness-subagents/agent-loader.ts

@@ -0,0 +1,126 @@
+/**
+ * Recursive discovery: $UP_PKG/.pi/agents/** + project .pi/agents/** overrides.
+ */
+
+import { createHash } from "node:crypto";
+import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { parseAgentMarkdown } from "./agent-parser.js";
+import type { AgentConfig } from "./vendored/types.js";
+
+export type AgentSource = "package" | "project" | "global";
+
+export interface DiscoveredAgentFile {
+	id: string;
+	path: string;
+	source: AgentSource;
+	content: string;
+}
+
+/** Reject path traversal and unsafe ids. */
+export function isSafeAgentId(id: string): boolean {
+	if (!id || id.includes("..") || id.startsWith("/") || id.includes("\\")) {
+		return false;
+	}
+	return /^[a-zA-Z0-9][a-zA-Z0-9/_-]*$/.test(id);
+}
+
+function walkAgentsDir(
+	rootDir: string,
+	source: AgentSource,
+	out: Map<string, DiscoveredAgentFile>,
+): void {
+	if (!existsSync(rootDir)) return;
+
+	const stack: string[] = [rootDir];
+	while (stack.length > 0) {
+		const dir = stack.pop()!;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+				continue;
+			}
+			if (!entry.name.endsWith(".md")) continue;
+
+			const rel = relative(rootDir, full).replace(/\\/g, "/");
+			const id = rel.replace(/\.md$/i, "");
+			if (!isSafeAgentId(id)) continue;
+
+			let content: string;
+			try {
+				content = readFileSync(full, "utf-8");
+			} catch {
+				continue;
+			}
+
+			out.set(id, { id, path: full, source, content });
+		}
+	}
+}
+
+/**
+ * Discover agent files from package, global, and project (low → high priority).
+ */
+export function discoverAgentFiles(
+	cwd: string,
+	packageRoot: string,
+): Map<string, DiscoveredAgentFile> {
+	const files = new Map<string, DiscoveredAgentFile>();
+
+	const packageAgents = join(packageRoot, ".pi", "agents");
+	const globalDir = join(getAgentDir(), "agents");
+	const projectDir = join(cwd, ".pi", "agents");
+
+	walkAgentsDir(packageAgents, "package", files);
+	walkAgentsDir(globalDir, "global", files);
+	walkAgentsDir(projectDir, "project", files);
+
+	return files;
+}
+
+/** Load merged AgentConfig map (project overrides package for same id). */
+export function loadHarnessAgents(
+	cwd: string,
+	packageRoot: string,
+): Map<string, AgentConfig> {
+	const agents = new Map<string, AgentConfig>();
+	for (const file of discoverAgentFiles(cwd, packageRoot).values()) {
+		agents.set(file.id, parseAgentMarkdown(file.id, file.content, file.source));
+	}
+	return agents;
+}
+
+export function sha256Content(content: string): string {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+/** Package-only manifest entries (path → hash). */
+export function loadPackageAgentHashes(
+	packageRoot: string,
+): Map<string, { path: string; sha256: string }> {
+	const packageAgents = join(packageRoot, ".pi", "agents");
+	const out = new Map<string, { path: string; sha256: string }>();
+	const files = new Map<string, DiscoveredAgentFile>();
+	walkAgentsDir(packageAgents, "package", files);
+	for (const f of files.values()) {
+		out.set(f.id, { path: f.path, sha256: sha256Content(f.content) });
+	}
+	return out;
+}
+
+/** Legacy hook used by pi-subagents custom-agents.ts replacement. */
+export function loadCustomAgents(
+	cwd: string,
+	packageRoot: string,
+): Map<string, AgentConfig> {
+	return loadHarnessAgents(cwd, packageRoot);
+}

package/.pi/extensions/lib/harness-subagents/agent-manifest.ts

@@ -0,0 +1,119 @@
+/**
+ * agents.manifest.json drift detection (package agents vs installed hashes).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	type DiscoveredAgentFile,
+	loadPackageAgentHashes,
+	sha256Content,
+} from "./agent-loader.js";
+
+export interface ManifestEntry {
+	path: string;
+	sha256: string;
+}
+
+export interface AgentsManifest {
+	schema_version: string;
+	package: string;
+	package_version: string;
+	generated_at: string;
+	agents: Record<string, ManifestEntry>;
+}
+
+export interface DriftItem {
+	id: string;
+	kind: "missing_in_manifest" | "hash_mismatch" | "missing_on_disk";
+	expected?: string;
+	actual?: string;
+}
+
+export interface DriftReport {
+	ok: boolean;
+	packageVersion: string;
+	items: DriftItem[];
+}
+
+function readPackageVersion(packageRoot: string): string {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(join(packageRoot, "package.json"), "utf-8"),
+		) as { version?: string };
+		return pkg.version ?? "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+
+export function readAgentsManifest(packageRoot: string): AgentsManifest | null {
+	const path = join(packageRoot, ".pi", "harness", "agents.manifest.json");
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as AgentsManifest;
+	} catch {
+		return null;
+	}
+}
+
+export function getDriftReport(packageRoot: string): DriftReport {
+	const manifest = readAgentsManifest(packageRoot);
+	const onDisk = loadPackageAgentHashes(packageRoot);
+	const packageVersion = readPackageVersion(packageRoot);
+	const items: DriftItem[] = [];
+
+	if (!manifest) {
+		return {
+			ok: false,
+			packageVersion,
+			items: [{ id: "*", kind: "missing_on_disk" }],
+		};
+	}
+
+	for (const [id, entry] of onDisk) {
+		const expected = manifest.agents[id];
+		if (!expected) {
+			items.push({ id, kind: "missing_in_manifest" });
+			continue;
+		}
+		if (expected.sha256 !== entry.sha256) {
+			items.push({
+				id,
+				kind: "hash_mismatch",
+				expected: expected.sha256,
+				actual: entry.sha256,
+			});
+		}
+	}
+
+	for (const id of Object.keys(manifest.agents)) {
+		if (!onDisk.has(id)) {
+			items.push({ id, kind: "missing_on_disk" });
+		}
+	}
+
+	return { ok: items.length === 0, packageVersion, items };
+}
+
+export function buildManifestFromFiles(
+	files: Iterable<DiscoveredAgentFile>,
+	packageName: string,
+	packageVersion: string,
+): AgentsManifest {
+	const agents: Record<string, ManifestEntry> = {};
+	for (const f of files) {
+		if (f.source !== "package") continue;
+		const relPath = `.pi/agents/${f.id}.md`;
+		agents[f.id] = {
+			path: relPath,
+			sha256: sha256Content(f.content),
+		};
+	}
+	return {
+		schema_version: "1.0.0",
+		package: packageName,
+		package_version: packageVersion,
+		generated_at: new Date().toISOString(),
+		agents,
+	};
+}

package/.pi/extensions/lib/harness-subagents/agent-parser.ts

@@ -0,0 +1,87 @@
+/**
+ * Parse harness agent .md files into AgentConfig (path id = posix relative path).
+ */
+
+import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "./vendored/agent-types.js";
+import type {
+	AgentConfig,
+	MemoryScope,
+	ThinkingLevel,
+} from "./vendored/types.js";
+
+function str(val: unknown): string | undefined {
+	return typeof val === "string" ? val : undefined;
+}
+
+function nonNegativeInt(val: unknown): number | undefined {
+	return typeof val === "number" && val >= 0 ? val : undefined;
+}
+
+function parseCsvField(val: unknown): string[] | undefined {
+	if (val === undefined || val === null) return undefined;
+	const s = String(val).trim();
+	if (!s || s === "none") return undefined;
+	const items = s
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+	return items.length > 0 ? items : undefined;
+}
+
+function csvList(val: unknown, defaults: string[]): string[] {
+	if (val === undefined || val === null) return defaults;
+	return parseCsvField(val) ?? [];
+}
+
+function csvListOptional(val: unknown): string[] | undefined {
+	return parseCsvField(val);
+}
+
+function parseMemory(val: unknown): MemoryScope | undefined {
+	if (val === "user" || val === "project" || val === "local") return val;
+	return undefined;
+}
+
+function inheritField(val: unknown): true | string[] | false {
+	if (val === undefined || val === null || val === true) return true;
+	if (val === false || val === "none") return false;
+	const items = csvList(val, []);
+	return items.length > 0 ? items : false;
+}
+
+export function parseAgentMarkdown(
+	agentId: string,
+	content: string,
+	source: "package" | "project" | "global",
+): AgentConfig {
+	const { frontmatter: fm, body } =
+		parseFrontmatter<Record<string, unknown>>(content);
+
+	const yamlName = str(fm.name);
+	const displayName = str(fm.display_name) ?? yamlName;
+
+	return {
+		name: agentId,
+		displayName,
+		description: str(fm.description) ?? agentId,
+		builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+		disallowedTools: csvListOptional(fm.disallowed_tools),
+		extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+		skills: inheritField(fm.skills ?? fm.inherit_skills),
+		model: str(fm.model),
+		thinking: str(fm.thinking) as ThinkingLevel | undefined,
+		maxTurns: nonNegativeInt(fm.max_turns),
+		systemPrompt: body.trim(),
+		promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+		inheritContext:
+			fm.inherit_context != null ? fm.inherit_context === true : undefined,
+		runInBackground:
+			fm.run_in_background != null ? fm.run_in_background === true : undefined,
+		isolated: fm.isolated != null ? fm.isolated === true : undefined,
+		memory: parseMemory(fm.memory),
+		isolation: fm.isolation === "worktree" ? "worktree" : undefined,
+		enabled: fm.enabled !== false,
+		source: source === "package" ? "global" : source,
+	};
+}

package/.pi/extensions/lib/harness-subagents/blackboard-tool.ts

@@ -0,0 +1,118 @@
+/**
+ * Orchestrator blackboard tool (list/read/query/wait/delete).
+ */
+
+import { defineTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { Blackboard } from "./blackboard.js";
+import type { BlackboardQuery } from "./types-blackboard.js";
+
+function textResult(text: string) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details: {},
+	};
+}
+
+export function registerBlackboardTool(
+	pi: ExtensionAPI,
+	blackboard: Blackboard,
+): void {
+	pi.registerTool(
+		defineTool({
+			name: "blackboard",
+			label: "Blackboard",
+			description:
+				"Shared knowledge store for harness orchestration. Actions: list, read, query, wait, delete. " +
+				"Use namespaced keys (e.g. scout:findings). Spawn context injection is capped at ~8k chars.",
+			parameters: Type.Object({
+				action: Type.Union([
+					Type.Literal("list"),
+					Type.Literal("read"),
+					Type.Literal("query"),
+					Type.Literal("wait"),
+					Type.Literal("delete"),
+				]),
+				key: Type.Optional(Type.String()),
+				pattern: Type.Optional(Type.String()),
+				agent_id: Type.Optional(Type.String()),
+				agent_name: Type.Optional(Type.String()),
+				category: Type.Optional(Type.String()),
+				timeout_ms: Type.Optional(
+					Type.Number({ description: "For wait action (default 30000)." }),
+				),
+			}),
+			execute: async (_id, params) => {
+				const action = params.action as string;
+
+				if (action === "list") {
+					return textResult(blackboard.serialize());
+				}
+
+				if (action === "read") {
+					const key = params.key as string | undefined;
+					if (!key) return textResult("read requires key.");
+					const entry = blackboard.get(key);
+					if (!entry) {
+						return textResult(`No entry for key "${key}".`);
+					}
+					return textResult(JSON.stringify(entry, null, 2));
+				}
+
+				if (action === "query") {
+					const q: BlackboardQuery = {};
+					if (params.pattern) q.pattern = params.pattern as string;
+					if (params.agent_id) q.agentId = params.agent_id as string;
+					if (params.agent_name) q.agentName = params.agent_name as string;
+					if (params.category) q.category = params.category as string;
+					if (params.key) q.keys = [params.key as string];
+					return textResult(JSON.stringify(blackboard.toJSON(q), null, 2));
+				}
+
+				if (action === "delete") {
+					const key = params.key as string | undefined;
+					if (!key) return textResult("delete requires key.");
+					const removed = blackboard.delete(key);
+					return textResult(
+						removed ? `Deleted "${key}".` : `Key "${key}" not found.`,
+					);
+				}
+
+				if (action === "wait") {
+					const pattern = (params.pattern ?? params.key) as string | undefined;
+					if (!pattern) {
+						return textResult("wait requires pattern or key.");
+					}
+					const timeoutMs = (params.timeout_ms as number) ?? 30_000;
+					const start = Date.now();
+					while (Date.now() - start < timeoutMs) {
+						const matches = blackboard.query({ pattern });
+						if (matches.length > 0) {
+							return textResult(
+								JSON.stringify(blackboard.toJSON({ pattern }), null, 2),
+							);
+						}
+						await new Promise((r) => setTimeout(r, 200));
+					}
+					return textResult(`Timeout waiting for pattern "${pattern}".`);
+				}
+
+				return textResult("Unknown action.");
+			},
+		}),
+	);
+}
+
+export function buildBlackboardContextInjection(
+	blackboard: Blackboard,
+	spec?: { agentId?: string; keys?: string[]; agentName?: string },
+): string | undefined {
+	if (!spec) return undefined;
+	const q: BlackboardQuery = {};
+	if (spec.agentId) q.agentId = spec.agentId;
+	if (spec.agentName) q.agentName = spec.agentName;
+	if (spec.keys?.length) q.keys = spec.keys;
+	const serialized = blackboard.serialize(q);
+	if (serialized === "(blackboard is empty)") return undefined;
+	return serialized;
+}

package/.pi/extensions/lib/harness-subagents/blackboard.ts

@@ -0,0 +1,175 @@
+/**
+ * Shared blackboard for orchestrator ↔ subagent handoffs (~8k injection cap).
+ */
+
+import type {
+	BlackboardEntry,
+	BlackboardQuery,
+	PostMetadata,
+} from "./types-blackboard.js";
+
+const MAX_VALUE_DISPLAY_CHARS = 500;
+export const MAX_SERIALIZE_TOTAL_CHARS = 8_000;
+
+function truncateForDisplay(value: unknown): string {
+	const str =
+		typeof value === "string" ? value : JSON.stringify(value, null, 2);
+	if (str.length <= MAX_VALUE_DISPLAY_CHARS) return str;
+	return `${str.slice(0, MAX_VALUE_DISPLAY_CHARS)}...(truncated)`;
+}
+
+type PostHandler = (key: string, entry: BlackboardEntry) => void;
+
+export class Blackboard {
+	private entries = new Map<string, BlackboardEntry>();
+	private postHandlers: PostHandler[] = [];
+
+	post(
+		namespacedKey: string,
+		value: unknown,
+		agentId: string,
+		agentName: string,
+		metadata?: PostMetadata,
+	): void {
+		if (metadata?.supersedes) {
+			this.entries.delete(metadata.supersedes);
+		}
+
+		const entry: BlackboardEntry = {
+			key: namespacedKey,
+			value,
+			agentId,
+			agentName,
+			timestamp: Date.now(),
+			metadata,
+		};
+
+		this.entries.set(namespacedKey, entry);
+
+		for (const handler of this.postHandlers) {
+			try {
+				handler(namespacedKey, entry);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+
+	get(key: string): BlackboardEntry | undefined {
+		return this.entries.get(key);
+	}
+
+	getAll(): Map<string, BlackboardEntry> {
+		return new Map(this.entries);
+	}
+
+	query(query: BlackboardQuery): BlackboardEntry[] {
+		let results = [...this.entries.values()];
+
+		if (query.keys?.length) {
+			results = results.filter((e) => query.keys?.includes(e.key));
+		}
+
+		if (query.pattern) {
+			const pat = query.pattern;
+			if (pat instanceof RegExp) {
+				results = results.filter((e) => pat.test(e.key));
+			} else {
+				const escaped = pat.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+				const re = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+				results = results.filter((e) => re.test(e.key) || e.key.includes(pat));
+			}
+		}
+
+		if (query.agentId) {
+			results = results.filter((e) => e.agentId === query.agentId);
+		}
+		if (query.agentName) {
+			results = results.filter((e) => e.agentName === query.agentName);
+		}
+		if (query.category) {
+			results = results.filter((e) => e.metadata?.category === query.category);
+		}
+		if (query.after !== undefined) {
+			results = results.filter((e) => e.timestamp > query.after!);
+		}
+
+		return results;
+	}
+
+	serialize(query?: BlackboardQuery): string {
+		const entries = query ? this.query(query) : [...this.entries.values()];
+
+		if (entries.length === 0) return "(blackboard is empty)";
+
+		const lines: string[] = [`Blackboard (${entries.length} entries):`];
+		let totalChars = lines[0].length;
+
+		for (const entry of entries) {
+			const summary = entry.metadata?.summary
+				? entry.metadata.summary
+				: truncateForDisplay(entry.value);
+			const category = entry.metadata?.category
+				? ` [${entry.metadata.category}]`
+				: "";
+			const ts = new Date(entry.timestamp).toISOString().slice(11, 19);
+			const keyLine = `  ${entry.key}${category} (${entry.agentName} @ ${ts})`;
+			const valLine = `    ${summary}`;
+			const entryChars = keyLine.length + valLine.length + 2;
+
+			if (totalChars + entryChars > MAX_SERIALIZE_TOTAL_CHARS) {
+				lines.push(
+					"  ... (more entries truncated — use blackboard query with specific keys)",
+				);
+				break;
+			}
+			lines.push(keyLine, valLine);
+			totalChars += entryChars;
+		}
+
+		return lines.join("\n");
+	}
+
+	toJSON(query?: BlackboardQuery): object {
+		const entries = query ? this.query(query) : [...this.entries.values()];
+		return {
+			count: entries.length,
+			entries: entries.map((e) => ({
+				key: e.key,
+				agentId: e.agentId,
+				agentName: e.agentName,
+				timestamp: e.timestamp,
+				summary: e.metadata?.summary ?? null,
+				category: e.metadata?.category ?? null,
+				value: e.value,
+			})),
+		};
+	}
+
+	clear(): void {
+		this.entries.clear();
+	}
+
+	restore(data: {
+		key: string;
+		value: unknown;
+		agentId: string;
+		agentName: string;
+		timestamp: number;
+		metadata?: PostMetadata;
+	}): void {
+		this.entries.set(data.key, { ...data });
+	}
+
+	delete(key: string): boolean {
+		return this.entries.delete(key);
+	}
+
+	get size(): number {
+		return this.entries.size;
+	}
+
+	on(event: "post", handler: PostHandler): void {
+		if (event === "post") this.postHandlers.push(handler);
+	}
+}

package/.pi/extensions/lib/harness-subagents/spawn-policy.ts

@@ -0,0 +1,27 @@
+/**
+ * Subagent tool policy — block nested orchestration tools (defense in depth).
+ */
+
+export const SUBAGENT_BLOCKED_TOOLS = new Set([
+	"Agent",
+	"get_subagent_result",
+	"steer_subagent",
+	"blackboard",
+	"ask_user",
+]);
+
+export interface ToolCallDecision {
+	action: "allow" | "block" | "modify";
+	reason?: string;
+	newArgs?: Record<string, unknown>;
+}
+
+export function evaluateSubagentToolCall(toolName: string): ToolCallDecision {
+	if (SUBAGENT_BLOCKED_TOOLS.has(toolName)) {
+		return {
+			action: "block",
+			reason: `Tool "${toolName}" is not available in subagent sessions (single spawn depth).`,
+		};
+	}
+	return { action: "allow" };
+}

package/.pi/extensions/lib/harness-subagents/types-blackboard.ts

@@ -0,0 +1,27 @@
+/**
+ * Blackboard types (ported from subagent-v2 reference; MIT design reference).
+ */
+
+export interface PostMetadata {
+	summary?: string;
+	category?: string;
+	supersedes?: string;
+}
+
+export interface BlackboardEntry {
+	key: string;
+	value: unknown;
+	agentId: string;
+	agentName: string;
+	timestamp: number;
+	metadata?: PostMetadata;
+}
+
+export interface BlackboardQuery {
+	keys?: string[];
+	pattern?: string | RegExp;
+	agentId?: string;
+	agentName?: string;
+	category?: string;
+	after?: number;
+}