pi-harness-runtime 0.10.5 → 0.10.7

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

@@ -0,0 +1,167 @@
+/**
+ * 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,18 @@
+/**
+ * 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/
+ */
+
+// 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,157 @@
+/**
+ * System Prompt Injection
+ *
+ * Adds write-review hints to the agent's system prompt.
+ */
+
+/**
+ * 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 = 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");
+  }
+}

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

@@ -0,0 +1,201 @@
+/**
+ * Review Integration
+ *
+ * Uses pi-subagents review-loop for multi-round code review.
+ */
+
+import type { WriteReviewStatus } from "./types.js";
+
+/**
+ * Review round result
+ */
+export interface ReviewResult {
+  verdict: "approved" | "changes_requested" | "blocked";
+  iteration: number;
+  message: string;
+  changesNeeded?: string[];
+  issues?: ReviewIssue[];
+}
+
+/**
+ * Issue found during review
+ */
+export interface ReviewIssue {
+  severity: "blocker" | "major" | "minor" | "suggestion";
+  type: "correctness" | "security" | "performance" | "style" | "test" | "docs";
+  location: string;
+  description: string;
+  suggestion?: string;
+}
+
+/**
+ * Build review task for pi-subagents
+ */
+export function buildReviewTask(
+  status: WriteReviewStatus,
+  projectPath: string
+): string {
+  const codeFiles = status.codeFiles ?? [];
+  const iteration = status.iteration;
+
+  const task = `## Review Task - Iteration ${iteration}
+
+Review the code written in this iteration.
+
+### Code Files to Review:
+${codeFiles.map((f) => `- ${f}`).join("\n") || "No files recorded yet."}
+
+### Project Path: ${projectPath}
+
+### Review Instructions:
+1. Read the code files listed above.
+2. Run the review-loop workflow using pi-subagents.
+3. Focus on: correctness, security, performance, tests, and code style.
+4. Return a verdict: APPROVED, CHANGES_REQUESTED, or BLOCKED.
+
+### Verdict Format:
+\`\`\`
+## Verdict: [APPROVED|CHANGES_REQUESTED|BLOCKED]
+[Your detailed review message]
+\`\`\`
+
+For CHANGES_REQUESTED, list specific changes needed:
+\`\`\`
+## Changes Needed:
+1. [Issue description] - [File:Line]
+2. [Issue description] - [File:Line]
+\`\`\`
+`;
+
+  return task;
+}
+
+/**
+ * Parse verdict from review output
+ */
+export function parseVerdict(output: string): {
+  verdict: "approved" | "changes_requested" | "blocked";
+  message: string;
+  changes?: string[];
+} | null {
+  const lines = output.split("\n");
+  let verdict: "approved" | "changes_requested" | "blocked" | null = null;
+  let message = "";
+  const changes: string[] = [];
+  let inChanges = false;
+
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+
+    if (lower.includes("## verdict:")) {
+      if (lower.includes("approved")) {
+        verdict = "approved";
+      } else if (lower.includes("changes_requested") || lower.includes("changes requested")) {
+        verdict = "changes_requested";
+      } else if (lower.includes("blocked")) {
+        verdict = "blocked";
+      }
+      continue;
+    }
+
+    if (lower.includes("## changes needed:") || lower.includes("changes:")) {
+      inChanges = true;
+      continue;
+    }
+
+    if (inChanges && line.trim().match(/^\d+\./)) {
+      changes.push(line.trim());
+      continue;
+    }
+
+    if (verdict && line.trim()) {
+      message += line + "\n";
+    }
+  }
+
+  if (!verdict) return null;
+
+  return {
+    verdict,
+    message: message.trim(),
+    changes: changes.length > 0 ? changes : undefined,
+  };
+}
+
+/**
+ * Review angles for parallel review
+ */
+export const REVIEW_ANGLES = [
+  {
+    name: "correctness",
+    description: "Verify implementation matches requirements and handles edge cases",
+  },
+  {
+    name: "tests",
+    description: "Check test coverage and validity",
+  },
+  {
+    name: "complexity",
+    description: "Look for unnecessary complexity and opportunities to simplify",
+  },
+];
+
+/**
+ * Build parallel review prompt
+ */
+export function buildParallelReviewPrompt(
+  codeFiles: string[],
+  projectPath: string
+): string {
+  return `Run parallel reviewers on this code:
+
+1. **correctness** - Verify implementation matches requirements and handles edge cases
+2. **tests** - Check test coverage and validity
+3. **complexity** - Look for unnecessary complexity
+
+Files: ${codeFiles.join(", ")}
+Project: ${projectPath}
+
+Use pi-subagents to spawn 3 parallel reviewers. Wait for all results, then synthesize into a final verdict.`;
+}
+
+/**
+ * Format review summary for blackboard
+ */
+export function formatReviewSummary(result: ReviewResult): string {
+  const lines = [
+    `## Review Result - Iteration ${result.iteration}`,
+    "",
+    `**Verdict:** ${result.verdict.toUpperCase()}`,
+    "",
+  ];
+
+  if (result.message) {
+    lines.push("### Message");
+    lines.push(result.message);
+    lines.push("");
+  }
+
+  if (result.changesNeeded && result.changesNeeded.length > 0) {
+    lines.push("### Changes Needed");
+    for (const change of result.changesNeeded) {
+      lines.push(`- ${change}`);
+    }
+    lines.push("");
+  }
+
+  if (result.issues && result.issues.length > 0) {
+    lines.push("### Issues Found");
+    for (const issue of result.issues) {
+      lines.push(`- [${issue.severity}] ${issue.type}: ${issue.description}`);
+      if (issue.location) {
+        lines.push(`  Location: ${issue.location}`);
+      }
+      if (issue.suggestion) {
+        lines.push(`  Suggestion: ${issue.suggestion}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Wiki Prompt Trigger
+ *
+ * Detects when an agent reads a prompt from {project}/wiki/*
+ * This triggers the write-review loop.
+ */
+
+import { existsSync } from "fs";
+import { join, relative } from "path";
+import type { ReviewTriggerContext } from "./types.js";
+
+const DEFAULT_WIKI_DIR = "wiki";
+
+/**
+ * Detect if a file path is a wiki prompt
+ */
+export function isWikiPrompt(filePath: string, projectPath: string): boolean {
+  const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const normalizedWiki = wikiDir.replace(/\\/g, "/");
+
+  return (
+    normalizedPath.startsWith(normalizedWiki + "/") ||
+    normalizedPath.startsWith(normalizedWiki + "\\")
+  );
+}
+
+/**
+ * Extract prompt metadata from wiki path
+ */
+export function parseWikiPrompt(
+  filePath: string,
+  projectPath: string
+): { category: string; filename: string } | null {
+  const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+  const rel = relative(wikiDir, filePath).replace(/\\/g, "/");
+
+  if (!rel || rel.startsWith("..")) return null;
+
+  const parts = rel.split("/");
+  if (parts.length >= 2) {
+    return {
+      category: parts[0],
+      filename: parts.slice(1).join("/"),
+    };
+  }
+  return {
+    category: "root",
+    filename: parts[0],
+  };
+}
+
+/**
+ * Get all wiki prompt files in a project
+ */
+export function getWikiPrompts(
+  projectPath: string
+): { path: string; category: string; filename: string }[] {
+  const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+
+  if (!existsSync(wikiDir)) {
+    return [];
+  }
+
+  const prompts: { path: string; category: string; filename: string }[] = [];
+
+  function scanDir(dir: string): void {
+    const { readdirSync, statSync } = require("fs");
+    try {
+      for (const entry of readdirSync(dir)) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          scanDir(fullPath);
+        } else if (stat.isFile() && (entry.endsWith(".md") || entry.endsWith(".txt"))) {
+          const relPath = relative(wikiDir, fullPath).replace(/\\/g, "/");
+          const parts = relPath.split("/");
+          prompts.push({
+            path: fullPath,
+            category: parts[0],
+            filename: parts.slice(1).join("/"),
+          });
+        }
+      }
+    } catch {
+      // Ignore permission errors
+    }
+  }
+
+  scanDir(wikiDir);
+  return prompts;
+}
+
+/**
+ * Create trigger context from a wiki read event
+ */
+export function createTriggerContext(
+  filePath: string,
+  projectPath: string,
+  triggerType: ReviewTriggerContext["triggerType"] = "wiki_read"
+): ReviewTriggerContext | null {
+  if (!isWikiPrompt(filePath, projectPath)) {
+    return null;
+  }
+
+  const parsed = parseWikiPrompt(filePath, projectPath);
+  if (!parsed) return null;
+
+  return {
+    projectPath,
+    promptFile: filePath,
+    promptContent: "",  // Will be filled by caller
+    triggerType,
+  };
+}
+
+/**
+ * Check if current working directory has wiki prompts
+ */
+export function hasWikiPrompts(projectPath: string): boolean {
+  const wikiDir = join(projectPath, DEFAULT_WIKI_DIR);
+  return existsSync(wikiDir);
+}
+
+/**
+ * Get wiki directory path
+ */
+export function getWikiDir(projectPath: string): string {
+  return join(projectPath, DEFAULT_WIKI_DIR);
+}