pi-harness-runtime 0.9.25 → 0.10.0

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;
+}

package/harness/notification-events.ts

@@ -73,7 +73,7 @@ export class HarnessNotificationEvents {
 		return this.center.listChannels();
 	}
 
-	// ─── Event Emitters ────────────────────────────────────────────────
+	// --- Event Emitters ------------------------------------------------
 
 	/**
 	 * Emit JobStarted event
@@ -173,7 +173,7 @@ export class HarnessNotificationEvents {
 		await this.emit("Error", { error });
 	}
 
-	// ─── State Machine Event Listeners ─────────────────────────────────
+	// --- State Machine Event Listeners ---------------------------------
 
 	/**
 	 * Wire up with JobStateMachine to emit events on transitions
@@ -207,7 +207,7 @@ export class HarnessNotificationEvents {
 		}
 	}
 
-	// ─── Private Methods ───────────────────────────────────────────────
+	// --- Private Methods -----------------------------------------------
 
 	private async emit(
 		event: NotificationEvent,

package/harness/output-limit-handler.ts

@@ -277,7 +277,7 @@ export class OutputLimitHandler {
 		return this.attempts >= this.maxAttempts;
 	}
 
-	// ─── Private Methods ────────────────────────────────────────────────
+	// --- Private Methods ------------------------------------------------
 
 	private ensureDir(): void {
 		if (!existsSync(this.rootDir)) {

package/harness/partial-recovery.ts

@@ -70,7 +70,7 @@ export class PartialRecovery {
 		this.loadExistingPartials();
 	}
 
-	// ─── Public API ───────────────────────────────────────────────────────────
+	// --- Public API -----------------------------------------------------------
 
 	/**
 	 * Save a partial response
@@ -285,7 +285,7 @@ export class PartialRecovery {
 		}
 	}
 
-	// ─── Private Methods ────────────────────────────────────────────────
+	// --- Private Methods ------------------------------------------------
 
 	private ensureDir(): void {
 		if (!existsSync(this.rootDir)) {
@@ -517,7 +517,7 @@ export class PartialRecovery {
 	}
 }
 
-// ─── Factory ────────────────────────────────────────────────────────────────
+// --- Factory ----------------------------------------------------------------
 
 /**
  * Create a PartialRecovery manager for a task

package/harness/session-memory.ts

@@ -11,7 +11,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CompactableMessage } from "../packages/types/src/runtime-types.js";
 
-// ─── Types ──────────────────────────────────────────────────────────────────
+// --- Types ------------------------------------------------------------------
 
 export interface SessionMemory {
 	jobId: string;
@@ -41,7 +41,7 @@ export interface TestResult {
 	timestamp: string;
 }
 
-// ─── Session Memory Manager ─────────────────────────────────────────────────
+// --- Session Memory Manager -------------------------------------------------
 
 export class SessionMemoryManager {
 	private memory: SessionMemory;
@@ -66,7 +66,7 @@ export class SessionMemoryManager {
 		};
 	}
 
-	// ─── Public API ───────────────────────────────────────────────────────────
+	// --- Public API -----------------------------------------------------------
 
 	/**
 	 * Extract key facts from recent messages
@@ -362,7 +362,7 @@ export class SessionMemoryManager {
 		this.save();
 	}
 
-	// ─── Private Methods ──────────────────────────────────────────────────
+	// --- Private Methods --------------------------------------------------
 
 	private load(): SessionMemory | null {
 		if (!existsSync(this.memoryPath)) {
@@ -388,7 +388,7 @@ export class SessionMemoryManager {
 	}
 }
 
-// ─── Factory ────────────────────────────────────────────────────────────────
+// --- Factory ----------------------------------------------------------------
 
 /**
  * Create a SessionMemoryManager for a job