pi-harness-runtime 1.1.95 → 1.1.97

package/packages/trajectory/src/write-approval.ts

@@ -0,0 +1,372 @@
+/**
+ * Write Approval Gate
+ * 
+ * Stage writes (memory, skills) for human review before they land.
+ * Based on Hermes Agent's consent-aware learning loop.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Pending write types
+ */
+export type PendingWriteType = 
+  | "memory_add"
+  | "memory_replace"
+  | "memory_remove"
+  | "skill_create"
+  | "skill_patch"
+  | "skill_delete"
+  | "skill_file_write"
+  | "skill_file_remove"
+  | "user_profile_add";
+
+/**
+ * Pending write action
+ */
+export interface PendingWriteAction {
+  type: PendingWriteType;
+  target: string; // memory entry id, skill id, etc.
+  content?: string; // new content for add/replace
+  oldContent?: string; // old content for replace/remove
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Pending write record
+ */
+export interface PendingWrite {
+  id: string;
+  action: PendingWriteAction;
+  author: "agent" | "user" | "curator";
+  timestamp: number;
+  summary: string; // One-line summary for display
+  details?: string; // Full diff or content for review
+}
+
+/**
+ * Write approval configuration
+ */
+export interface WriteApprovalConfig {
+  /** Enable write approval */
+  enabled: boolean;
+  /** Directory to store pending writes */
+  pendingDir: string;
+  /** Max pending writes before warning */
+  maxPending: number;
+}
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_APPROVAL_CONFIG: WriteApprovalConfig = {
+  enabled: false,
+  pendingDir: "~/.pi-harness/pending",
+  maxPending: 50,
+};
+
+/**
+ * Expand path with ~
+ */
+function expandPath(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/**
+ * Write Approval Gate
+ */
+export class WriteApprovalGate {
+  private config: WriteApprovalConfig;
+  private pending: PendingWrite[] = [];
+
+  constructor(config?: Partial<WriteApprovalConfig>) {
+    this.config = { ...DEFAULT_APPROVAL_CONFIG, ...config };
+    this.config.pendingDir = expandPath(this.config.pendingDir);
+    this.load();
+  }
+
+  /**
+   * Load pending writes from disk
+   */
+  private load(): void {
+    const pendingFile = join(this.config.pendingDir, "writes.json");
+    
+    if (!existsSync(pendingFile)) {
+      this.pending = [];
+      return;
+    }
+
+    try {
+      const content = readFileSync(pendingFile, "utf-8");
+      this.pending = JSON.parse(content);
+    } catch (err) {
+      console.error("[WriteApprovalGate] Failed to load:", err);
+      this.pending = [];
+    }
+  }
+
+  /**
+   * Save pending writes to disk
+   */
+  private save(): void {
+    mkdirSync(this.config.pendingDir, { recursive: true });
+    const pendingFile = join(this.config.pendingDir, "writes.json");
+    writeFileSync(pendingFile, JSON.stringify(this.pending, null, 2), "utf-8");
+  }
+
+  /**
+   * Stage a write for approval
+   */
+  stage(action: PendingWriteAction, author: "agent" | "user" | "curator"): PendingWrite {
+    // Generate ID
+    const id = `pw_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    // Generate summary
+    const summary = this.generateSummary(action);
+
+    // Generate details (diff)
+    const details = this.generateDetails(action);
+
+    const pending: PendingWrite = {
+      id,
+      action,
+      author,
+      timestamp: Date.now(),
+      summary,
+      details,
+    };
+
+    this.pending.push(pending);
+    this.save();
+
+    return pending;
+  }
+
+  /**
+   * Generate one-line summary for action
+   */
+  private generateSummary(action: PendingWriteAction): string {
+    switch (action.type) {
+      case "memory_add":
+        return `Add memory: "${action.content?.slice(0, 50)}..."`;
+      case "memory_replace":
+        return `Replace memory`;
+      case "memory_remove":
+        return `Remove memory`;
+      case "skill_create":
+        return `Create skill: ${action.target}`;
+      case "skill_patch":
+        return `Patch skill: ${action.target}`;
+      case "skill_delete":
+        return `Delete skill: ${action.target}`;
+      case "skill_file_write":
+        return `Write file to skill ${action.target}: ${action.metadata?.file}`;
+      case "skill_file_remove":
+        return `Remove file from skill ${action.target}: ${action.metadata?.file}`;
+      case "user_profile_add":
+        return `Add user preference: "${action.content?.slice(0, 50)}..."`;
+      default:
+        return `Unknown action: ${action.type}`;
+    }
+  }
+
+  /**
+   * Generate details (diff) for action
+   */
+  private generateDetails(action: PendingWriteAction): string | undefined {
+    switch (action.type) {
+      case "memory_add":
+      case "user_profile_add":
+        return action.content;
+      case "memory_replace":
+        return `OLD:\n${action.oldContent}\n\nNEW:\n${action.content}`;
+      case "skill_create":
+      case "skill_patch":
+        return action.content;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Approve a pending write
+   */
+  approve(writeId: string): PendingWrite | null {
+    const index = this.pending.findIndex((w) => w.id === writeId);
+    if (index < 0) return null;
+
+    const write = this.pending[index];
+    this.pending.splice(index, 1);
+    this.save();
+
+    return write;
+  }
+
+  /**
+   * Approve all pending writes
+   */
+  approveAll(): PendingWrite[] {
+    const approved = [...this.pending];
+    this.pending = [];
+    this.save();
+    return approved;
+  }
+
+  /**
+   * Reject a pending write
+   */
+  reject(writeId: string): PendingWrite | null {
+    const index = this.pending.findIndex((w) => w.id === writeId);
+    if (index < 0) return null;
+
+    const write = this.pending[index];
+    this.pending.splice(index, 1);
+    this.save();
+
+    return write;
+  }
+
+  /**
+   * Reject all pending writes
+   */
+  rejectAll(): PendingWrite[] {
+    const rejected = [...this.pending];
+    this.pending = [];
+    this.save();
+    return rejected;
+  }
+
+  /**
+   * Get all pending writes
+   */
+  list(): PendingWrite[] {
+    return [...this.pending];
+  }
+
+  /**
+   * Get pending writes by type
+   */
+  listByType(type: PendingWriteType): PendingWrite[] {
+    return this.pending.filter((w) => w.action.type === type);
+  }
+
+  /**
+   * Get pending writes by author
+   */
+  listByAuthor(author: "agent" | "user" | "curator"): PendingWrite[] {
+    return this.pending.filter((w) => w.author === author);
+  }
+
+  /**
+   * Get pending count
+   */
+  count(): number {
+    return this.pending.length;
+  }
+
+  /**
+   * Check if approval is required
+   */
+  requiresApproval(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<WriteApprovalConfig>): void {
+    this.config = { ...this.config, ...config };
+    if (config.pendingDir) {
+      this.config.pendingDir = expandPath(config.pendingDir);
+    }
+  }
+
+  /**
+   * Get configuration
+   */
+  getConfig(): WriteApprovalConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Format pending writes for display
+   */
+  formatList(): string {
+    if (this.pending.length === 0) {
+      return "No pending writes.";
+    }
+
+    const lines: string[] = [];
+    for (const write of this.pending) {
+      const age = this.getAgeString(write.timestamp);
+      lines.push(`[${write.id}] ${age} ${write.author}: ${write.summary}`);
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Get age string for timestamp
+   */
+  private getAgeString(timestamp: number): string {
+    const age = Date.now() - timestamp;
+    const minutes = Math.floor(age / 60000);
+    
+    if (minutes < 1) return "<1m";
+    if (minutes < 60) return `${minutes}m`;
+    
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours}h`;
+    
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+  }
+}
+
+// Global instance
+let globalGate: WriteApprovalGate | null = null;
+
+export function getGlobalApprovalGate(): WriteApprovalGate {
+  if (!globalGate) {
+    globalGate = new WriteApprovalGate();
+  }
+  return globalGate;
+}
+
+export function createApprovalGate(config?: Partial<WriteApprovalConfig>): WriteApprovalGate {
+  return new WriteApprovalGate(config);
+}
+
+/**
+ * Helper to stage write with auto-approval if disabled
+ */
+export function stageWrite(
+  action: PendingWriteAction,
+  author: "agent" | "user" | "curator",
+  autoApprove: boolean = false
+): { staged: boolean; write?: PendingWrite } {
+  const gate = getGlobalApprovalGate();
+
+  if (!gate.requiresApproval() || autoApprove) {
+    // Return action directly for execution
+    return {
+      staged: false,
+      write: {
+        id: "auto",
+        action,
+        author,
+        timestamp: Date.now(),
+        summary: `Auto-approved: ${action.type}`,
+      },
+    };
+  }
+
+  // Stage for approval
+  const write = gate.stage(action, author);
+  return { staged: true, write };
+}

package/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tui",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "description": "pi-harness-runtime — tui",
   "type": "module",
   "main": "./dist/index.js",

package/packages/types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/types",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "description": "Shared TypeScript types for pi-harness-runtime packages",
   "type": "module",
   "main": "./src/index.js",

package/packages/workflow-events/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/workflow-events",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/workspace-scanner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/workspace-scanner",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/worktree/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/worktree",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "description": "pi-harness-runtime — worktree",
   "type": "module",
   "main": "./dist/index.js",

package/packages/write-review/dist/blackboard.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Write-Review Blackboard
+ *
+ * File-based coordination between writer and reviewer agents.
+ * Location: {project}/.write-review/status.json
+ */
+import type { WriteReviewStatus, ReviewPhase, Verdict, PingPongDecisionSnapshot } from "./types.js";
+export declare class WriteReviewBlackboard {
+    private readonly projectPath;
+    private readonly dir;
+    private status;
+    constructor(projectPath: string, dir?: string);
+    /**
+     * Initialize a new write-review session
+     */
+    init(): void;
+    /**
+     * Load status from disk
+     */
+    load(): WriteReviewStatus | null;
+    /**
+     * Save status to disk
+     */
+    save(): void;
+    /**
+     * Get current status
+     */
+    getStatus(): WriteReviewStatus | null;
+    /**
+     * Record the automatic decision that selected or skipped PING-PONG.
+     * This is the durable middleware state shared by separate agent terminals.
+     */
+    recordPingPongDecision(snapshot: PingPongDecisionSnapshot): void;
+    /**
+     * Start a new write session
+     */
+    startWriting(): void;
+    /**
+     * Mark writer as done
+     */
+    writerDone(message?: string): void;
+    /**
+     * Start reviewing
+     */
+    startReview(): void;
+    /**
+     * Record verdict
+     */
+    setVerdict(verdict: Verdict, message?: string): void;
+    /**
+     * Record code files written
+     */
+    setCodeFiles(files: string[]): void;
+    /**
+     * Record requested changes
+     */
+    setChangesRequested(changes: string[]): void;
+    /**
+     * Get current phase
+     */
+    getPhase(): ReviewPhase;
+    /**
+     * Get iteration number
+     */
+    getIteration(): number;
+    /**
+     * Check if build is allowed
+     */
+    canBuild(): boolean;
+    /**
+     * Get blackboard directory path
+     */
+    getPath(): string;
+    /**
+     * Reset to idle
+     */
+    reset(): void;
+    /**
+     * Check if a review session exists for this project
+     */
+    exists(): boolean;
+    /**
+     * Export status as markdown for display.
+     * Injected into every agent prompt so each agent sees the shared scoreboard.
+     * Matches the pi-lens pattern: persistent artifact encountered naturally.
+     */
+    toMarkdown(): string;
+    /**
+     * Extract file paths from a fenced code block string.
+     * Looks for common patterns: ```path/to/file
+     */
+    extractFilePaths(code: string): string[];
+}
+/**
+ * Create or get blackboard for project
+ */
+export declare function createBlackboard(projectPath: string, dir?: string): WriteReviewBlackboard;
+//# sourceMappingURL=blackboard.d.ts.map

package/packages/write-review/dist/blackboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blackboard.d.ts","sourceRoot":"","sources":["../src/blackboard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACX,iBAAiB,EACjB,WAAW,EACX,OAAO,EACP,wBAAwB,EACxB,MAAM,YAAY,CAAC;AAKpB,qBAAa,qBAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAkC;IAEhD,YAAY,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB,EAGzD;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAWX;IAED;;OAEG;IACH,IAAI,IAAI,iBAAiB,GAAG,IAAI,CAW/B;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAMX;IAED;;OAEG;IACH,SAAS,IAAI,iBAAiB,GAAG,IAAI,CAEpC;IAED;;;OAGG;IACH,sBAAsB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAY/D;IAED;;OAEG;IACH,YAAY,IAAI,IAAI,CAMnB;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAMjC;IAED;;OAEG;IACH,WAAW,IAAI,IAAI,CAKlB;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAmBnD;IAED;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAIlC;IAED;;OAEG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAI3C;IAED;;OAEG;IACH,QAAQ,IAAI,WAAW,CAEtB;IAED;;OAEG;IACH,YAAY,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,QAAQ,IAAI,OAAO,CAElB;IAED;;OAEG;IACH,OAAO,IAAI,MAAM,CAEhB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAYZ;IAED;;OAEG;IACH,MAAM,IAAI,OAAO,CAGhB;IAED;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAkDnB;IAED;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBvC;CACD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,MAAM,GACV,qBAAqB,CAQvB"}