pi-harness-runtime 0.9.25 → 1.1.0

package/harness/loop-controller.ts

@@ -0,0 +1,201 @@
+/**
+ * Loop Controller — blackboard-coordinated write-review loops.
+ *
+ * Human types /review-loop <write_count> <review_count> --prompt="..."
+ * Controller creates blackboard, sets first nextAction, monitors progress.
+ */
+
+import { writeFileSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import {
+	createHerdrBus,
+	ensureHerdrWorkspace,
+	publishLoopStarted,
+	type LoopConfig,
+} from "../packages/event-bus/src/index.js";
+import { createBlackboard } from "./blackboard.js";
+import { buildLoopTaskGraph } from "./loop-types.js";
+import type { SharedBlackboard } from "./blackboard.js";
+
+function encodeNextAction(la: {
+	taskId: string;
+	agentType: string;
+	iteration: number;
+	prompt?: string;
+	codeFiles?: string[];
+}) {
+	return {
+		taskId: la.taskId,
+		instruction: "LOOP:" + JSON.stringify(la),
+		priority: "high" as const,
+		createdAt: new Date().toISOString(),
+	};
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((r) => setTimeout(r, ms));
+}
+
+// ─── Monitor ────────────────────────────────────────────────────────────────
+
+async function monitorLoop(
+	blackboard: SharedBlackboard,
+	loopId: string,
+): Promise<void> {
+	const paths = ensureHerdrWorkspace();
+
+	while (true) {
+		blackboard.load();
+		const record = blackboard.getRecord();
+		if (!record) {
+			await sleep(500);
+			continue;
+		}
+
+		// Check if report is done
+		const reportNode = record.tasks.nodes["report"];
+		if (reportNode?.status === "done") {
+			const reviews = Object.values(record.tasks.nodes).filter(
+				(n) => n.id.startsWith("review-") && n.status === "done",
+			);
+			const lastReview = reviews.sort((a, b) =>
+				(b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""),
+			)[0];
+			const verdict = (lastReview as { result?: string }).result ?? "unknown";
+			const summary =
+				verdict !== "unknown" ? `Verdict: ${verdict}` : "Loop completed";
+
+			const reportPath = join(
+				paths.reviews,
+				`loop-${loopId.slice(0, 8)}-final.md`,
+			);
+			writeFileSync(
+				reportPath,
+				`# Loop Result — ${loopId.slice(0, 8)}
+
+## Result
+${summary}
+
+## Verdict: **${verdict.toUpperCase()}**
+`,
+			);
+			console.log(`[controller] VERDICT: ${verdict.toUpperCase()}`);
+			console.log(`[controller] Report: ${reportPath}`);
+			return;
+		}
+
+		// Check for blocked
+		const blocked = Object.values(record.tasks.nodes).find(
+			(n) => n.status === "blocked",
+		);
+		if (blocked) {
+			const reportPath = join(
+				paths.reviews,
+				`loop-${loopId.slice(0, 8)}-final.md`,
+			);
+			writeFileSync(
+				reportPath,
+				`# Loop Result — ${loopId.slice(0, 8)}
+
+## Result
+Blocked at: ${blocked.id}
+
+## Verdict: **BLOCKED**
+`,
+			);
+			console.log(`[controller] VERDICT: BLOCKED (${blocked.id})`);
+			return;
+		}
+
+		await sleep(500);
+	}
+}
+
+// ─── Run ──────────────────────────────────────────────────────────────────
+
+async function runLoop(args: string[]): Promise<void> {
+	const writeCount = parseInt(args[0] ?? "3", 10);
+	const reviewCount = parseInt(args[1] ?? "2", 10);
+	const prompt =
+		(args.find((a) => a.startsWith("--prompt=")) ?? "")
+			.slice("--prompt=".length)
+			.replace(/^["']|["']$/g, "") || "No prompt";
+
+	if (isNaN(writeCount) || writeCount < 1 || writeCount > 20) {
+		console.error("write_count must be 1-20");
+		process.exit(1);
+	}
+	if (isNaN(reviewCount) || reviewCount < 0 || reviewCount > 20) {
+		console.error("review_count must be 0-20");
+		process.exit(1);
+	}
+
+	const loopId = randomUUID();
+	const paths = ensureHerdrWorkspace();
+	const taskGraph = buildLoopTaskGraph(writeCount, reviewCount, loopId);
+
+	console.log("=".repeat(60));
+	console.log(`LOOP STARTED — ${loopId.slice(0, 8)}`);
+	console.log(`  Writes: ${writeCount}  Reviews: ${reviewCount}`);
+	console.log(`  Prompt: ${prompt}`);
+	console.log("=".repeat(60));
+
+	// Create blackboard
+	const blackboard = createBlackboard(loopId, paths.root, taskGraph);
+	console.log(`[controller] Blackboard: ${blackboard.getPath()}`);
+
+	// Event bus for cross-process signaling
+	const bus = createHerdrBus(`ctrl-${loopId.slice(0, 8)}`);
+
+	// Save config
+	// Clean old loop configs
+	for (const f of (await import("fs")).readdirSync(paths.root)) {
+		if (f.startsWith("loop-") && f.endsWith(".config.json")) {
+			(await import("fs")).unlinkSync(join(paths.root, f));
+		}
+	}
+
+	const config: LoopConfig = {
+		loopId,
+		writeCount,
+		reviewCount,
+		prompt,
+		nextReviewAfter: Math.max(1, Math.floor(writeCount / (reviewCount || 1))),
+		createdAt: new Date().toISOString(),
+	};
+	writeFileSync(
+		join(paths.root, `loop-${loopId}.config.json`),
+		JSON.stringify(config, null, 2),
+	);
+	publishLoopStarted(bus, config);
+
+	// Set first action: code agent writes iteration 1
+	blackboard.setNextAction(
+		encodeNextAction({
+			taskId: "write-1",
+			agentType: "code",
+			iteration: 1,
+			prompt,
+		}),
+	);
+	console.log("[controller] nextAction: code write-1");
+
+	// Monitor until done
+	await monitorLoop(blackboard, loopId);
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+if (!args.length || args[0] === "--help" || args[0] === "-h") {
+	console.log(
+		'Usage: bun harness/loop-controller.ts <write_count> <review_count> --prompt="..."\nExample: bun harness/loop-controller.ts 3 2 --prompt="build REST API"',
+	);
+	process.exit(0);
+}
+
+runLoop(args).catch((err) => {
+	console.error("[controller] Fatal:", err);
+	process.exit(1);
+});

package/harness/loop-review-agent.ts

@@ -0,0 +1,295 @@
+/**
+ * Loop Review Agent (GPT) — coordinates via blackboard.
+ *
+ * Polls blackboard for nextAction where agentType="review".
+ * Reviews code, writes verdict, updates node status.
+ *
+ * Usage:  bun harness/loop-review-agent.ts
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import {
+	ensureHerdrWorkspace,
+	parseVerdict,
+} from "../packages/event-bus/src/herdr-bus.js";
+import { SharedBlackboard } from "./blackboard.js";
+import type {
+	LoopNextAction,
+	LoopAgentReport,
+	LoopVerdict,
+} from "./loop-types.js";
+
+const AGENT_ID = "review-agent";
+const AGENT_TYPE = "review";
+const POLL_MS = 1000;
+const REVIEW_TIMEOUT_MS = 5 * 60 * 1000;
+
+async function main(): Promise<void> {
+	console.log(`[${AGENT_ID}] Starting...`);
+	const paths = ensureHerdrWorkspace();
+
+	// Find active loop config
+	const loopId = await findActiveLoop(paths.root);
+	if (!loopId) console.log(`[${AGENT_ID}] No active loop found. Waiting...`);
+
+	const blackboard = new SharedBlackboard(loopId ?? "no-loop", paths.root);
+	blackboard.load();
+	blackboard.registerAgent(AGENT_ID, "Review Agent", "openai", "gpt-4o");
+	blackboard.updateAgentStatus(AGENT_ID, "idle");
+	console.log(`[${AGENT_ID}] Registered. Blackboard: ${blackboard.getPath()}`);
+
+	while (true) {
+		await sleep(POLL_MS);
+
+		blackboard.load();
+		const record = blackboard.getRecord();
+		if (!record) continue;
+		if (record.jobId !== loopId) continue;
+
+		// Check for early exit
+		const earlyExit = checkEarlyExit(record);
+		if (earlyExit) {
+			console.log(`[${AGENT_ID}] Loop ended: ${earlyExit}`);
+			break;
+		}
+
+		// Check nextAction for review agent
+		const action = parseNextAction(record.nextAction);
+		if (!action || action.agentType !== AGENT_TYPE) continue;
+
+		// Claim the task
+		const locked = blackboard.acquireLock(action.taskId, AGENT_ID);
+		if (!locked) continue;
+
+		blackboard.updateAgentStatus(AGENT_ID, "working", action.taskId);
+		console.log(`[${AGENT_ID}] Claimed: ${action.taskId}`);
+
+		// Handle report task
+		if (action.taskId === "report") {
+			await finishReport(blackboard, record);
+			break;
+		}
+
+		// Do the review
+		const verdict = await doReview(action, paths, record.jobId);
+
+		// Update task status
+		updateTaskStatus(blackboard, record, action.taskId, verdict);
+
+		// Release and report
+		blackboard.releaseLock(action.taskId, AGENT_ID);
+		blackboard.writeReport({
+			agentId: AGENT_ID,
+			taskId: action.taskId,
+			status: "success",
+			message: verdict,
+		} as unknown as Parameters<typeof blackboard.writeReport>[0]);
+		blackboard.updateAgentStatus(AGENT_ID, "idle");
+
+		// Decide next action based on verdict
+		if (verdict === "approved" || verdict === "blocked") {
+			// Early exit — go to report
+			blackboard.setNextAction(
+				encodeNextAction({
+					taskId: "report",
+					agentType: "review",
+					iteration: 0,
+				}),
+			);
+			console.log(
+				`[${AGENT_ID}] ${verdict.toUpperCase()} — nextAction: report`,
+			);
+		} else {
+			// Changes requested — continue to next write
+			const nextWrite = getNextWriteTask(record, action.iteration);
+			if (nextWrite) {
+				blackboard.setNextAction(
+					encodeNextAction({
+						taskId: nextWrite,
+						agentType: "code",
+						iteration: getWriteIteration(nextWrite),
+						prompt: action.prompt,
+					}),
+				);
+				console.log(`[${AGENT_ID}] CHANGES — nextAction: code ${nextWrite}`);
+			} else {
+				blackboard.setNextAction({
+					taskId: "report",
+					agentType: "review",
+					iteration: 0,
+				} as unknown as ReturnType<typeof encodeNextAction>);
+				console.log(`[${AGENT_ID}] CHANGES — nextAction: report`);
+			}
+		}
+	}
+}
+
+// ─── Review Logic ────────────────────────────────────────────────────────
+
+async function doReview(
+	action: LoopNextAction,
+	paths: { reviews: string },
+	loopId: string,
+): Promise<LoopVerdict> {
+	const reviewDir = join(paths.reviews, loopId);
+	mkdirSync(reviewDir, { recursive: true });
+
+	const reviewFile = join(reviewDir, `review-${action.iteration}.md`);
+
+	// Read code files
+	const codeBlocks = await Promise.all(
+		(action.codeFiles ?? []).map(async (file) => {
+			const content = existsSync(file)
+				? readFileSync(file, "utf-8").slice(0, 3000)
+				: `[Not found: ${file}]`;
+			return `## ${file}\n\n\`\`\`\n${content}\n\`\`\`\n`;
+		}),
+	);
+
+	// Write review stub
+	const review = `# Review — Iteration ${action.iteration}
+
+> GPT tab: Edit this file and add your verdict at the bottom.
+> Use: \`## Verdict: APPROVED\`, \`## Verdict: CHANGES_REQUESTED\`, or \`## Verdict: BLOCKED\`
+> GPT tab has ${REVIEW_TIMEOUT_MS / 1000 / 60} minutes to complete.
+
+${codeBlocks.join("\n")}
+`;
+	writeFileSync(reviewFile, review);
+	console.log(`[${AGENT_ID}] Review stub: ${reviewFile}`);
+	console.log(`[${AGENT_ID}] Waiting for GPT verdict...`);
+
+	// Poll for verdict
+	return await pollVerdict(reviewFile);
+}
+
+async function pollVerdict(reviewFile: string): Promise<LoopVerdict> {
+	const deadline = Date.now() + REVIEW_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		if (existsSync(reviewFile)) {
+			const content = readFileSync(reviewFile, "utf-8");
+			const verdict = parseVerdict(content);
+			if (verdict) return verdict;
+		}
+		await sleep(3000);
+	}
+	console.log(
+		`[${AGENT_ID}] Verdict timeout — defaulting to CHANGES_REQUESTED`,
+	);
+	return "changes_requested";
+}
+
+async function finishReport(
+	blackboard: SharedBlackboard,
+	record: { tasks: { nodes: Record<string, { status: string }> } },
+): Promise<void> {
+	const reportNode = record.tasks.nodes["report"] as { status: string };
+	reportNode.status = "done";
+	blackboard.save();
+	console.log(`[${AGENT_ID}] Report complete. Loop finished.`);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+async function findActiveLoop(rootDir: string): Promise<string | null> {
+	const { readdirSync } = await import("fs");
+	try {
+		const files = readdirSync(rootDir).filter(
+			(f) => f.startsWith("loop-") && f.endsWith(".config.json"),
+		);
+		if (files.length > 0) {
+			const config = JSON.parse(readFileSync(join(rootDir, files[0]), "utf-8"));
+			return config.loopId;
+		}
+	} catch {
+		// no loop yet
+	}
+	return null;
+}
+
+function checkEarlyExit(record: {
+	tasks: { nodes: Record<string, { status: string }> };
+	jobId: string;
+}): string | null {
+	const reportNode = record.tasks.nodes["report"];
+	if (
+		reportNode &&
+		(reportNode.status === "done" || reportNode.status === "blocked")
+	) {
+		return reportNode.status === "done" ? "finished" : "blocked";
+	}
+	return null;
+}
+
+function updateTaskStatus(
+	blackboard: SharedBlackboard,
+	record: {
+		tasks: { nodes: Record<string, { status: string; result?: string }> };
+	},
+	taskId: string,
+	verdict: LoopVerdict,
+): void {
+	const node = record.tasks.nodes[taskId] as
+		| { status: string; result?: string }
+		| undefined;
+	if (node) {
+		node.status = verdict === "blocked" ? "blocked" : "done";
+		node.result = verdict;
+		node.updatedAt = new Date().toISOString();
+		blackboard.save();
+	}
+}
+
+function encodeNextAction(action: Partial<LoopNextAction>) {
+	return {
+		taskId: action.taskId,
+		instruction: "LOOP:" + JSON.stringify(action),
+		priority: "high" as const,
+		createdAt: new Date().toISOString(),
+	};
+}
+
+function parseNextAction(nextAction: unknown): LoopNextAction | null {
+	if (!nextAction) return null;
+	const a = nextAction as Record<string, unknown>;
+	if (!a.taskId) return null;
+	if (typeof a.instruction === "string" && a.instruction.startsWith("LOOP:")) {
+		try {
+			return JSON.parse(a.instruction.slice(5)) as LoopNextAction;
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+
+function getNextWriteTask(
+	record: { tasks: { nodes: Record<string, { status: string }> } },
+	currentReviewIteration: number,
+): string | null {
+	const writeCount = Object.keys(record.tasks.nodes).filter((id) =>
+		id.startsWith("write-"),
+	).length;
+	// After review N, next write is N+1
+	const nextWrite = currentReviewIteration + 1;
+	const taskId = `write-${nextWrite}`;
+	if (
+		record.tasks.nodes[taskId] &&
+		record.tasks.nodes[taskId].status === "pending"
+	) {
+		return taskId;
+	}
+	return null;
+}
+
+function getWriteIteration(taskId: string): number {
+	const m = taskId.match(/^write-(\d+)$/);
+	return m ? parseInt(m[1], 10) : 0;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((r) => setTimeout(r, ms));
+}
+
+main().catch(console.error);

package/harness/loop-runtime.ts

@@ -46,12 +46,12 @@ import {
 	createForkedSummarizer,
 } from "./forked-summarizer.js";
 
-// ─── Constants ────────────────────────────────────────────────────────────────
+// --- Constants ----------------------------------------------------------------
 
 const DEFAULT_MAX_COMPACT_RETRIES = 3;
 const DEFAULT_MAX_OUTPUT_TOKENS = 4096;
 
-// ─── Lifecycle Callbacks ────────────────────────────────────────────────────
+// --- Lifecycle Callbacks ----------------------------------------------------
 
 export interface LoopCallbacks {
 	/** Fetch next task from queue */
@@ -97,7 +97,7 @@ export interface LoopCallbacks {
 	onCompaction?: (result: CompactResult) => void;
 }
 
-// ─── Loop Result ───────────────────────────────────────────────────────────
+// --- Loop Result -----------------------------------------------------------
 
 export interface LoopResult {
 	success: boolean;
@@ -109,7 +109,7 @@ export interface LoopResult {
 	totalCompactions?: number;
 }
 
-// ─── Loop Runtime ───────────────────────────────────────────────────────────
+// --- Loop Runtime -----------------------------------------------------------
 
 export class LoopRuntime {
 	private readonly config: Required<LoopConfig>;
@@ -221,12 +221,12 @@ export class LoopRuntime {
 		}
 	}
 
-	// ─── Public API ─────────────────────────────────────────────────────────
+	// --- Public API ---------------------------------------------------------
 
 	async run(): Promise<LoopResult> {
 		this.running = true;
 
-		// ─── Auto-resume from quota pause ──────────────────────────────────
+		// --- Auto-resume from quota pause ----------------------------------
 		const checkpoint = await this.callbacks.onGetCheckpoint?.();
 		if (checkpoint?.status === "paused_quota" && checkpoint.resumeAt) {
 			const resumeMs = new Date(checkpoint.resumeAt).getTime();
@@ -348,7 +348,7 @@ export class LoopRuntime {
 		return this.sessionMemory;
 	}
 
-	// ─── Task Execution with Compact ───────────────────────────────────────
+	// --- Task Execution with Compact ---------------------------------------
 
 	private async executeTaskWithCompact(task: RuntimeTask): Promise<void> {
 		// 1. Pick model
@@ -690,7 +690,7 @@ export class LoopRuntime {
 		return parts.join("\n");
 	}
 
-	// ─── Quota Handling ────────────────────────────────────────────────────
+	// --- Quota Handling ----------------------------------------------------
 
 	private async handleQuotaPause(): Promise<void> {
 		this.paused = true;
@@ -717,7 +717,7 @@ export class LoopRuntime {
 		await this.saveCheckpoint();
 	}
 
-	// ─── Persistence ────────────────────────────────────────────────────────
+	// --- Persistence --------------------------------------------------------
 
 	private async saveCheckpoint(): Promise<void> {
 		const now = new Date().toISOString();
@@ -736,7 +736,7 @@ export class LoopRuntime {
 		await this.callbacks.onCheckpoint?.(checkpoint);
 	}
 
-	// ─── Resume from Checkpoint ────────────────────────────────────────────
+	// --- Resume from Checkpoint --------------------------------------------
 
 	async resumeFromCheckpoint(
 		checkpoint: RuntimeCheckpoint,

package/harness/loop-types.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared types for loop coordination via blackboard.
+ */
+
+import type {
+	TaskGraph,
+	TaskNode,
+} from "../packages/types/src/runtime-types.ts";
+
+export type LoopVerdict = "approved" | "changes_requested" | "blocked";
+export type LoopNodeType = "write" | "review" | "decide" | "report";
+export type LoopNodeStatus = "pending" | "running" | "done" | "blocked";
+
+export interface LoopNextAction {
+	taskId: string;
+	agentType: "code" | "review";
+	iteration: number;
+	prompt?: string;
+	codeFiles?: string[];
+}
+
+export interface LoopAgentReport {
+	agentId: string;
+	taskId: string;
+	status: "running" | "done" | "failed";
+	message?: string;
+	files?: string[];
+	verdict?: LoopVerdict;
+}
+
+export interface LoopTaskGraph {
+	nodes: Record<string, TaskNode>;
+	topologicalOrder: string[];
+}
+
+export function buildLoopTaskGraph(
+	writeCount: number,
+	reviewCount: number,
+	loopId: string,
+): TaskGraph {
+	const now = new Date().toISOString();
+	const nodes: Record<string, TaskNode> = {};
+	const order: string[] = [];
+
+	// Write tasks
+	for (let i = 1; i <= writeCount; i++) {
+		const id = `write-${i}`;
+		nodes[id] = {
+			id,
+			title: `Code Write ${i}`,
+			description: `Write iteration ${i}`,
+			status: "pending",
+			dependencies: [],
+			dependents: [],
+			createdAt: now,
+			updatedAt: now,
+		};
+		order.push(id);
+	}
+
+	// Review tasks
+	const step = Math.max(1, Math.floor(writeCount / (reviewCount || 1)));
+	for (let i = 1; i <= reviewCount; i++) {
+		const id = `review-${i}`;
+		const writeIdx = i * step;
+		nodes[id] = {
+			id,
+			title: `Code Review ${i}`,
+			description: `Review iteration ${i}`,
+			status: "pending",
+			dependencies: writeIdx <= writeCount ? [`write-${writeIdx}`] : [],
+			dependents: [],
+			createdAt: now,
+			updatedAt: now,
+		};
+		// Wire dependencies
+		if (writeIdx <= writeCount) {
+			nodes[`write-${writeIdx}`].dependents.push(id);
+		}
+		order.push(id);
+	}
+
+	// Report task
+	const reportId = "report";
+	nodes[reportId] = {
+		id: reportId,
+		title: "Loop Report",
+		description: "Final summary",
+		status: "pending",
+		dependencies: [],
+		dependents: [],
+		createdAt: now,
+		updatedAt: now,
+	};
+	order.push(reportId);
+
+	return {
+		jobId: loopId,
+		nodes,
+		topologicalOrder: order,
+	};
+}
+
+export function getNodeStatus(
+	graph: TaskGraph,
+	nodeId: string,
+): LoopNodeStatus | undefined {
+	return graph.nodes[nodeId]?.status as LoopNodeStatus | undefined;
+}
+
+export function getReviewVerdict(
+	graph: TaskGraph,
+	reviewId: string,
+): LoopVerdict | undefined {
+	const node = graph.nodes[reviewId];
+	if (!node) return undefined;
+	return (node as unknown as { result?: LoopVerdict }).result;
+}