pi-harness-runtime 1.1.0 → 1.1.2

package/packages/write-review/src/blackboard.ts

@@ -0,0 +1,249 @@
+/**
+ * Write-Review Blackboard
+ *
+ * File-based coordination between writer and reviewer agents.
+ * Location: {project}/.write-review/status.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import type { WriteReviewStatus, ReviewPhase, Verdict } from "./types.js";
+
+const DEFAULT_DIR = ".write-review";
+const STATUS_FILE = "status.json";
+
+export class WriteReviewBlackboard {
+	private readonly projectPath: string;
+	private readonly dir: string;
+	private status: WriteReviewStatus | null = null;
+
+	constructor(projectPath: string, dir: string = DEFAULT_DIR) {
+		this.projectPath = projectPath;
+		this.dir = join(projectPath, dir);
+	}
+
+	/**
+	 * Initialize a new write-review session
+	 */
+	init(): void {
+		mkdirSync(this.dir, { recursive: true });
+		this.status = {
+			projectPath: this.projectPath,
+			phase: "idle",
+			writerDone: false,
+			iteration: 0,
+			createdAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+		};
+		this.save();
+	}
+
+	/**
+	 * Load status from disk
+	 */
+	load(): WriteReviewStatus | null {
+		const path = join(this.dir, STATUS_FILE);
+		if (!existsSync(path)) {
+			return null;
+		}
+		try {
+			this.status = JSON.parse(readFileSync(path, "utf-8"));
+			return this.status;
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Save status to disk
+	 */
+	save(): void {
+		if (!this.status) return;
+		this.status.updatedAt = new Date().toISOString();
+		mkdirSync(this.dir, { recursive: true });
+		const path = join(this.dir, STATUS_FILE);
+		writeFileSync(path, JSON.stringify(this.status, null, 2));
+	}
+
+	/**
+	 * Get current status
+	 */
+	getStatus(): WriteReviewStatus | null {
+		return this.status;
+	}
+
+	/**
+	 * Start a new write session
+	 */
+	startWriting(): void {
+		if (!this.status) this.init();
+		this.status!.phase = "writing";
+		this.status!.writerDone = false;
+		this.status!.iteration++;
+		this.save();
+	}
+
+	/**
+	 * Mark writer as done
+	 */
+	writerDone(message?: string): void {
+		if (!this.status) return;
+		this.status.writerDone = true;
+		this.status.writerMessage = message;
+		this.status.phase = "pending_review";
+		this.save();
+	}
+
+	/**
+	 * Start reviewing
+	 */
+	startReview(): void {
+		if (!this.status) return;
+		this.status.phase = "reviewing";
+		this.status.reviewerStarted = new Date().toISOString();
+		this.save();
+	}
+
+	/**
+	 * Record verdict
+	 */
+	setVerdict(verdict: Verdict, message?: string): void {
+		if (!this.status) return;
+		this.status.verdict = verdict;
+		this.status.verdictMessage = message;
+
+		switch (verdict) {
+			case "approved":
+				this.status.phase = "approved";
+				this.status.approvedAt = new Date().toISOString();
+				break;
+			case "blocked":
+				this.status.phase = "blocked";
+				this.status.blockedAt = new Date().toISOString();
+				break;
+			case "changes_requested":
+				this.status.phase = "changes_requested";
+				break;
+		}
+		this.save();
+	}
+
+	/**
+	 * Record code files written
+	 */
+	setCodeFiles(files: string[]): void {
+		if (!this.status) return;
+		this.status.codeFiles = files;
+		this.save();
+	}
+
+	/**
+	 * Record requested changes
+	 */
+	setChangesRequested(changes: string[]): void {
+		if (!this.status) return;
+		this.status.changesRequested = changes;
+		this.save();
+	}
+
+	/**
+	 * Get current phase
+	 */
+	getPhase(): ReviewPhase {
+		return this.status?.phase ?? "idle";
+	}
+
+	/**
+	 * Get iteration number
+	 */
+	getIteration(): number {
+		return this.status?.iteration ?? 0;
+	}
+
+	/**
+	 * Check if build is allowed
+	 */
+	canBuild(): boolean {
+		return this.status?.phase === "approved";
+	}
+
+	/**
+	 * Get blackboard directory path
+	 */
+	getPath(): string {
+		return this.dir;
+	}
+
+	/**
+	 * Reset to idle
+	 */
+	reset(): void {
+		if (!this.status) return;
+		this.status.phase = "idle";
+		this.status.writerDone = false;
+		this.status.verdict = undefined;
+		this.status.verdictMessage = undefined;
+		this.status.reviewerStarted = undefined;
+		this.status.approvedAt = undefined;
+		this.status.blockedAt = undefined;
+		this.status.codeFiles = undefined;
+		this.status.changesRequested = undefined;
+		this.save();
+	}
+
+	/**
+	 * Check if a review session exists for this project
+	 */
+	exists(): boolean {
+		const path = join(this.dir, STATUS_FILE);
+		return existsSync(path);
+	}
+
+	/**
+	 * Export status as markdown for display
+	 */
+	toMarkdown(): string {
+		if (!this.status) return "No active write-review session.";
+
+		const { phase, iteration, verdict, verdictMessage, codeFiles } =
+			this.status;
+		const lines = [
+			`## Write-Review Status`,
+			``,
+			`| Field | Value |`,
+			`|-------|-------|`,
+			`| Phase | ${phase} |`,
+			`| Iteration | ${iteration} |`,
+			`| Verdict | ${verdict ?? "pending"} |`,
+		];
+
+		if (verdictMessage) {
+			lines.push(`| Message | ${verdictMessage} |`);
+		}
+
+		if (codeFiles && codeFiles.length > 0) {
+			lines.push(``, `### Code Files`);
+			for (const file of codeFiles) {
+				lines.push(`- ${file}`);
+			}
+		}
+
+		return lines.join("\n");
+	}
+}
+
+/**
+ * Create or get blackboard for project
+ */
+export function createBlackboard(
+	projectPath: string,
+	dir?: string,
+): WriteReviewBlackboard {
+	const bb = new WriteReviewBlackboard(projectPath, dir);
+	if (!bb.exists()) {
+		bb.init();
+	} else {
+		bb.load();
+	}
+	return bb;
+}

package/packages/write-review/src/gate.ts

@@ -0,0 +1,169 @@
+/**
+ * No-Build Gate
+ *
+ * Blocks build commands until review is approved.
+ */
+
+import type { WriteReviewBlackboard } from "./blackboard.js";
+import type { WriteReviewStatus } from "./types.js";
+
+/**
+ * Commands that trigger build gate
+ */
+const BUILD_COMMANDS = [
+	"bench build",
+	"npm run build",
+	"yarn build",
+	"pnpm build",
+	"bun run build",
+	"npm run dev",
+	"yarn dev",
+	"pnpm dev",
+	"./build",
+	"make build",
+	"gradle build",
+	"mvn package",
+	"dotnet build",
+	"cargo build",
+	"go build",
+	"python manage.py migrate",
+	"bench migrate",
+	"bench --site",
+];
+
+/**
+ * Check if a command is a build command
+ */
+export function isBuildCommand(command: string): boolean {
+	const lower = command.toLowerCase().trim();
+	return BUILD_COMMANDS.some((cmd) => lower.includes(cmd.toLowerCase()));
+}
+
+/**
+ * Gate result
+ */
+export interface GateResult {
+	allowed: boolean;
+	reason?: string;
+	currentPhase?: string;
+	message?: string;
+}
+
+/**
+ * Check if build is allowed
+ */
+export function checkBuildGate(
+	command: string,
+	blackboard: WriteReviewBlackboard,
+): GateResult {
+	if (!isBuildCommand(command)) {
+		return { allowed: true };
+	}
+
+	const status = blackboard.load();
+	if (!status) {
+		// No review session - allow build
+		return { allowed: true };
+	}
+
+	if (status.phase === "approved") {
+		return {
+			allowed: true,
+			currentPhase: status.phase,
+			message: "Build allowed - review approved.",
+		};
+	}
+
+	return {
+		allowed: false,
+		reason: "REVIEW_NOT_APPROVED",
+		currentPhase: status.phase,
+		message: `Build blocked. Current review phase: ${status.phase}. Wait for "APPROVED" verdict.`,
+	};
+}
+
+/**
+ * Format gate rejection message
+ */
+export function formatGateRejection(result: GateResult): string {
+	if (result.allowed) {
+		return "";
+	}
+
+	const lines = [
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"⚠️  BUILD BLOCKED",
+		"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+		"",
+		`Current Phase: ${result.currentPhase}`,
+		"",
+		"The code is under review. Build is only allowed after APPROVED verdict.",
+		"",
+		"To check status:",
+		`  cat {project}/.write-review/status.json`,
+		"",
+		"To wait for approval, do nothing. The reviewer will post the verdict.",
+		"",
+	];
+
+	if (result.currentPhase === "changes_requested") {
+		lines.push(
+			"Reviewer requested changes. Writer agent should update the code.",
+		);
+	} else if (result.currentPhase === "reviewing") {
+		lines.push("Review is in progress. Please wait...");
+	} else if (result.currentPhase === "pending_review") {
+		lines.push("Review not started yet. Waiting for reviewer...");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Get phase emoji
+ */
+export function getPhaseEmoji(phase: string): string {
+	const emojis: Record<string, string> = {
+		idle: "💤",
+		writing: "✍️",
+		pending_review: "⏳",
+		reviewing: "🔍",
+		approved: "✅",
+		blocked: "🚫",
+		changes_requested: "🔄",
+	};
+	return emojis[phase] ?? "❓";
+}
+
+/**
+ * Format status for display
+ */
+export function formatStatusDisplay(status: WriteReviewStatus): string {
+	const emoji = getPhaseEmoji(status.phase);
+	const lines = [
+		`${emoji} Write-Review Status`,
+		"",
+		`Phase: ${status.phase}`,
+		`Iteration: ${status.iteration}`,
+	];
+
+	if (status.verdict) {
+		lines.push(`Verdict: ${status.verdict}`);
+	}
+
+	if (status.verdictMessage) {
+		lines.push("");
+		lines.push("Message:");
+		lines.push(status.verdictMessage);
+	}
+
+	if (status.codeFiles && status.codeFiles.length > 0) {
+		lines.push("");
+		lines.push("Code Files:");
+		for (const file of status.codeFiles) {
+			lines.push(`  - ${file}`);
+		}
+	}
+
+	return lines.join("\n");
+}

package/packages/write-review/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * write-review - Two-agent code writing with review loop
+ *
+ * Integrates with pi-harness-runtime via:
+ * - Smart trigger detection (prompt files in wiki/)
+ * - System prompt injection for writer agent
+ * - Subagent integration for reviewer agent
+ *
+ * Directory structure: {project}/.write-review/
+ */
+
+import { rmSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const MAX_AGE_DAYS = 3;
+
+/**
+ * Auto-cleanup old review history files older than MAX_AGE_DAYS
+ */
+export function cleanupOldReviews(projectPath: string): number {
+  // Resolve path to prevent traversal attacks
+  const basePath = resolve(projectPath);
+  const reviewDir = join(basePath, ".write-review");
+  
+  // Ensure reviewDir is within basePath (traversal guard)
+  if (!reviewDir.startsWith(basePath + '/')) {
+    return 0; // Invalid path, skip
+  }
+  
+  if (!existsSync(reviewDir)) {
+    return 0; // Directory doesn't exist
+  }
+  
+  let deleted = 0;
+  const files = readdirSync(reviewDir);
+  const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+  
+  for (const file of files) {
+    if (file === "status.json") continue; // Keep status file
+    // Sanitize filename to prevent path traversal
+    const sanitized = file.replace(/[^a-zA-Z0-9_.-]/g, '_');
+    if (sanitized !== file) continue; // Skip suspicious filenames
+    
+    const filePath = join(reviewDir, sanitized);
+    try {
+      const stats = statSync(filePath);
+      if (stats.mtimeMs < cutoff) {
+        rmSync(filePath, { force: true });
+        deleted++;
+      }
+    } catch {
+      // Ignore files that can't be read
+    }
+  }
+  
+  return deleted;
+}
+
+// Re-export all public APIs
+export * from "./types.js";
+export * from "./blackboard.js";
+export * from "./trigger.js";
+export * from "./injection.js";
+export * from "./gate.js";
+export * from "./review.js";

package/packages/write-review/src/injection.ts

@@ -0,0 +1,190 @@
+/**
+ * System Prompt Injection
+ *
+ * Adds write-review hints to the agent's system prompt.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Find the project root (directory containing .git)
+ */
+function findProjectRoot(startPath: string): string {
+  let dir = startPath;
+  // Limit traversal to prevent infinite loops
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(dir, ".git"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // Reached filesystem root
+    dir = parent;
+  }
+  return startPath; // Fallback to start path
+}
+
+/**
+ * Write-review hint for system prompt
+ */
+export const WRITE_REVIEW_HINT = `
+
+## Write-Review Loop
+
+When reading a prompt from {project}/wiki/*:
+
+1. You are the **WRITER** agent (Minimax). Read the wiki prompt and write code.
+2. After writing code, write "## WRITER_DONE" to signal completion.
+3. Do NOT build or commit until you receive "APPROVED" verdict.
+4. If you receive "CHANGES_REQUESTED", update the code accordingly.
+5. Acknowledge each verdict in your response.
+
+### Blackboard Path
+{p}/.write-review/status.json
+
+### Verdict Types
+- **APPROVED**: Code is ready. You may build/commit.
+- **CHANGES_REQUESTED**: Reviewer found issues. Update code.
+- **BLOCKED**: Critical issues. Human intervention needed.
+`;
+
+/**
+ * Helper agent hint (for worker agent)
+ */
+export const HELPER_HINT = `
+
+## Helper Agent Task
+
+The writer agent is busy or needs assistance. Your task:
+
+1. Note any pending tasks to the Todos list using the todo tool.
+2. Review the changes requested and prepare notes for the writer.
+3. Do NOT write code directly - that's the writer's job.
+4. Write a summary of pending tasks to the blackboard.
+`;
+
+/**
+ * Review reminder hint
+ */
+export const REVIEW_REMINDER_HINT = `
+
+## Review Reminder
+
+Before committing or building, ALWAYS check the write-review status:
+
+\`\`\`bash
+cat {project}/.write-review/status.json
+\`\`\`
+
+Only build/commit if the status shows "approved" or "phase": "approved".
+`;
+
+/**
+ * Format hint with project path
+ */
+export function formatWriteReviewHint(projectPath: string): string {
+	return WRITE_REVIEW_HINT.replace("{project}", projectPath).replace(
+		"{p}",
+		projectPath,
+	);
+}
+
+/**
+ * Format review reminder with project path
+ */
+export function formatReviewReminder(projectPath: string): string {
+	return REVIEW_REMINDER_HINT.replace("{project}", projectPath);
+}
+
+/**
+ * Get all hints to inject
+ */
+export function getWriteReviewHints(projectPath: string): {
+	writeHint: string;
+	reminderHint: string;
+} {
+	return {
+		writeHint: formatWriteReviewHint(projectPath),
+		reminderHint: formatReviewReminder(projectPath),
+	};
+}
+
+/**
+ * Register write-review extension with pi
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBlackboard } from "./blackboard.js";
+
+export function injectWriterInstructions(
+	pi: ExtensionAPI,
+	config?: { debug?: boolean },
+): void {
+	let currentProject: string | null = null;
+	let blackboard: ReturnType<typeof createBlackboard> | null = null;
+	let hintsInjected = false;
+
+	// System prompt injection
+	pi.on("before_agent_start", async (event) => {
+		const cwd = findProjectRoot(process.cwd?.() ?? "/");
+		if (cwd !== currentProject) {
+			currentProject = cwd;
+			blackboard = createBlackboard(cwd);
+			hintsInjected = false;
+		}
+
+		if (!hintsInjected && blackboard) {
+			const status = blackboard.load();
+			if (status && status.phase !== "idle") {
+				event.systemPrompt += formatWriteReviewHint(cwd);
+				if (status.phase !== "approved") {
+					event.systemPrompt += formatReviewReminder(cwd);
+				}
+				hintsInjected = true;
+				if (config?.debug) {
+					console.log(
+						`[write-review] Hints injected for ${cwd}, phase: ${status.phase}`,
+					);
+				}
+			}
+		}
+	});
+
+	// Build gate
+	pi.on("tool_execution_end", async (event) => {
+		const toolName = (event as { tool?: { name?: string } }).tool?.name ?? "";
+		if (toolName !== "bash") return;
+
+		const result = event as { result?: { content?: string } };
+		const content = result.result?.content ?? "";
+
+		// Check for build commands
+		const buildCommands = [
+			"bench build",
+			"npm run build",
+			"yarn build",
+			"pnpm build",
+			"bun run build",
+			"make build",
+			"gradle build",
+			"dotnet build",
+			"cargo build",
+		];
+		const isBuild = buildCommands.some((cmd) => content.includes(cmd));
+
+		if (isBuild && blackboard) {
+			const status = blackboard.load();
+			if (status && status.phase !== "approved") {
+				result.result!.content =
+					content +
+					"\n\n" +
+					"⚠️ BUILD BLOCKED - Review not approved yet.\n" +
+					`Current phase: ${status.phase}\n` +
+					"Wait for APPROVED verdict before building.";
+			}
+		}
+	});
+
+	if (config?.debug) {
+		console.log("[write-review] Extension registered");
+	}
+}