pi-harness-runtime 0.10.6 → 0.10.7

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

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

@@ -0,0 +1,88 @@
+/**
+ * Write-Review Loop Types
+ *
+ * State machine for two-agent write-review coordination.
+ */
+
+/**
+ * Review phases
+ */
+export type ReviewPhase =
+  | "idle"
+  | "writing"
+  | "pending_review"
+  | "reviewing"
+  | "approved"
+  | "blocked"
+  | "changes_requested";
+
+/**
+ * Review verdict
+ */
+export type Verdict = "approved" | "changes_requested" | "blocked";
+
+/**
+ * Blackboard status record
+ */
+export interface WriteReviewStatus {
+  projectPath: string;
+  phase: ReviewPhase;
+  writerDone: boolean;
+  writerMessage?: string;
+  iteration: number;
+  verdict?: Verdict;
+  verdictMessage?: string;
+  reviewerStarted?: string;  // ISO timestamp
+  codeFiles?: string[];     // Files written
+  changesRequested?: string[];  // Changes needed
+  approvedAt?: string;     // ISO timestamp
+  blockedAt?: string;      // ISO timestamp
+  updatedAt: string;
+  createdAt: string;
+}
+
+/**
+ * Review trigger context
+ */
+export interface ReviewTriggerContext {
+  projectPath: string;
+  promptFile: string;
+  promptContent: string;
+  triggerType: "wiki_read" | "manual" | "code_written";
+}
+
+/**
+ * Extension config
+ */
+export interface WriteReviewConfig {
+  debug?: boolean;
+  blackboardDir?: string;  // Default: "{project}/.write-review"
+  wikiDir?: string;        // Default: "{project}/wiki"
+  enabled?: boolean;
+}
+
+/**
+ * Agent roles
+ */
+export const AGENT_ROLES = {
+  WRITER: "writer",      // Minimax - reads wiki, writes code
+  REVIEWER: "reviewer",  // Uses pi-subagents review-loop
+  HELPER: "helper",     // worker - notes tasks to todo
+} as const;
+
+export type AgentRole = typeof AGENT_ROLES[keyof typeof AGENT_ROLES];
+
+/**
+ * State transition helpers
+ */
+export function isTerminalPhase(phase: ReviewPhase): boolean {
+  return phase === "approved" || phase === "blocked";
+}
+
+export function needsReview(phase: ReviewPhase): boolean {
+  return phase === "pending_review" || phase === "reviewing";
+}
+
+export function canWrite(phase: ReviewPhase): boolean {
+  return phase === "idle" || phase === "writing" || phase === "changes_requested";
+}