@vibecheckai/cli 3.4.0 → 3.5.0

package/bin/runners/lib/conductor/index.js

@@ -0,0 +1,671 @@
+/**
+ * Conductor - Multi-Agent Coordination System
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ENTERPRISE EDITION - Agent Orchestration
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Manages multiple AI agents working on the same codebase:
+ * - Agent registration and heartbeat tracking
+ * - File locking to prevent concurrent edits
+ * - Change proposals with conflict detection
+ * - Coordination history for auditing
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const STATE_DIR = ".vibecheck";
+const STATE_FILE = "conductor-state.json";
+const LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes - stale lock threshold
+const AGENT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes - agent considered inactive
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UUID GENERATION (no external dependency)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function generateUUID() {
+  // RFC 4122 v4 UUID
+  const bytes = crypto.randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10xx
+  
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join("-");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FILE UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function readJSON(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function writeJSON(filePath, data) {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONDUCTOR CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+class Conductor {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.stateFile = path.join(projectRoot, STATE_DIR, STATE_FILE);
+    this.state = null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // STATE MANAGEMENT
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Load state from disk (or initialize fresh)
+   */
+  async load() {
+    const existing = readJSON(this.stateFile);
+    
+    if (existing) {
+      this.state = existing;
+    } else {
+      this.state = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        agents: {},
+        locks: {},
+        proposals: [],
+        history: []
+      };
+    }
+    
+    return this.state;
+  }
+
+  /**
+   * Persist state to disk
+   */
+  async save() {
+    this.state.updatedAt = new Date().toISOString();
+    writeJSON(this.stateFile, this.state);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // AGENT MANAGEMENT
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Register a new agent
+   * @param {Object} agentInfo - Agent metadata (name, type, capabilities)
+   * @returns {string} - Unique agent ID
+   */
+  async registerAgent(agentInfo) {
+    const agentId = generateUUID();
+    const now = new Date().toISOString();
+    
+    this.state.agents[agentId] = {
+      id: agentId,
+      name: agentInfo.name || "unnamed-agent",
+      type: agentInfo.type || "unknown",
+      capabilities: agentInfo.capabilities || [],
+      metadata: agentInfo.metadata || {},
+      registeredAt: now,
+      lastSeen: now,
+      status: "active"
+    };
+    
+    // Record in history
+    this._recordEvent("agent_registered", {
+      agentId,
+      agentName: agentInfo.name,
+      agentType: agentInfo.type
+    });
+    
+    await this.save();
+    return agentId;
+  }
+
+  /**
+   * Update agent's last seen timestamp
+   * @param {string} agentId 
+   */
+  async heartbeat(agentId) {
+    const agent = this.state.agents[agentId];
+    
+    if (!agent) {
+      return { success: false, reason: "agent-not-found" };
+    }
+    
+    agent.lastSeen = new Date().toISOString();
+    agent.status = "active";
+    await this.save();
+    
+    return { success: true, lastSeen: agent.lastSeen };
+  }
+
+  /**
+   * Unregister an agent (and release its locks)
+   * @param {string} agentId 
+   */
+  async unregisterAgent(agentId) {
+    const agent = this.state.agents[agentId];
+    
+    if (!agent) {
+      return { success: false, reason: "agent-not-found" };
+    }
+    
+    // Release all locks held by this agent
+    const releasedLocks = [];
+    for (const [filePath, lock] of Object.entries(this.state.locks)) {
+      if (lock.agentId === agentId) {
+        delete this.state.locks[filePath];
+        releasedLocks.push(filePath);
+      }
+    }
+    
+    // Mark agent as inactive (preserve for history)
+    agent.status = "unregistered";
+    agent.unregisteredAt = new Date().toISOString();
+    
+    this._recordEvent("agent_unregistered", {
+      agentId,
+      releasedLocks
+    });
+    
+    await this.save();
+    
+    return { success: true, releasedLocks };
+  }
+
+  /**
+   * Get agent info by ID
+   */
+  getAgent(agentId) {
+    return this.state.agents[agentId] || null;
+  }
+
+  /**
+   * List all agents (optionally filter active only)
+   */
+  listAgents(activeOnly = false) {
+    const now = Date.now();
+    const agents = Object.values(this.state.agents);
+    
+    if (!activeOnly) {
+      return agents;
+    }
+    
+    return agents.filter(agent => {
+      if (agent.status !== "active") return false;
+      const lastSeen = new Date(agent.lastSeen).getTime();
+      return now - lastSeen < AGENT_TIMEOUT_MS;
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // FILE LOCKING
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Acquire a lock on a file
+   * @param {string} agentId - Agent requesting the lock
+   * @param {string} filePath - File to lock (relative to project root)
+   * @param {string} reason - Why the lock is needed
+   * @returns {Object} - { success, lockId } or { success: false, reason, holder }
+   */
+  async acquireLock(agentId, filePath, reason = "") {
+    // Normalize file path
+    const normalizedPath = this._normalizePath(filePath);
+    const existing = this.state.locks[normalizedPath];
+    const now = Date.now();
+    
+    // Check if already locked by another agent
+    if (existing && existing.agentId !== agentId) {
+      const lockAge = now - new Date(existing.acquiredAt).getTime();
+      
+      // Check if lock is stale (> 5 min)
+      if (lockAge < LOCK_TIMEOUT_MS) {
+        return {
+          success: false,
+          reason: "locked",
+          holder: existing.agentId,
+          holderName: this.state.agents[existing.agentId]?.name || "unknown",
+          holderReason: existing.reason,
+          lockAge: lockAge,
+          expiresIn: LOCK_TIMEOUT_MS - lockAge
+        };
+      }
+      
+      // Stale lock - record takeover in history
+      this._recordEvent("lock_expired", {
+        filePath: normalizedPath,
+        previousHolder: existing.agentId,
+        newHolder: agentId
+      });
+    }
+    
+    // Grant the lock
+    this.state.locks[normalizedPath] = {
+      agentId,
+      agentName: this.state.agents[agentId]?.name || "unknown",
+      reason,
+      acquiredAt: new Date().toISOString(),
+      expiresAt: new Date(now + LOCK_TIMEOUT_MS).toISOString()
+    };
+    
+    this._recordEvent("lock_acquired", {
+      agentId,
+      filePath: normalizedPath,
+      reason
+    });
+    
+    await this.save();
+    
+    return { success: true, lockId: normalizedPath };
+  }
+
+  /**
+   * Release a lock on a file
+   * @param {string} agentId - Agent releasing the lock
+   * @param {string} filePath - File to unlock
+   */
+  async releaseLock(agentId, filePath) {
+    const normalizedPath = this._normalizePath(filePath);
+    const lock = this.state.locks[normalizedPath];
+    
+    if (!lock) {
+      return { success: false, reason: "not-locked" };
+    }
+    
+    if (lock.agentId !== agentId) {
+      return { 
+        success: false, 
+        reason: "not-owner",
+        holder: lock.agentId
+      };
+    }
+    
+    delete this.state.locks[normalizedPath];
+    
+    this._recordEvent("lock_released", {
+      agentId,
+      filePath: normalizedPath
+    });
+    
+    await this.save();
+    
+    return { success: true };
+  }
+
+  /**
+   * Check if a file is locked
+   */
+  checkLock(filePath) {
+    const normalizedPath = this._normalizePath(filePath);
+    const lock = this.state.locks[normalizedPath];
+    
+    if (!lock) {
+      return { locked: false };
+    }
+    
+    const now = Date.now();
+    const lockAge = now - new Date(lock.acquiredAt).getTime();
+    const isStale = lockAge >= LOCK_TIMEOUT_MS;
+    
+    return {
+      locked: !isStale,
+      stale: isStale,
+      holder: lock.agentId,
+      holderName: lock.agentName,
+      reason: lock.reason,
+      acquiredAt: lock.acquiredAt,
+      lockAge
+    };
+  }
+
+  /**
+   * List all active locks
+   */
+  listLocks() {
+    const now = Date.now();
+    const locks = [];
+    
+    for (const [filePath, lock] of Object.entries(this.state.locks)) {
+      const lockAge = now - new Date(lock.acquiredAt).getTime();
+      locks.push({
+        filePath,
+        ...lock,
+        lockAge,
+        stale: lockAge >= LOCK_TIMEOUT_MS
+      });
+    }
+    
+    return locks;
+  }
+
+  /**
+   * Acquire locks on multiple files atomically
+   */
+  async acquireLocks(agentId, files, reason = "") {
+    const results = [];
+    const acquired = [];
+    
+    // Try to acquire all locks
+    for (const filePath of files) {
+      const result = await this.acquireLock(agentId, filePath, reason);
+      results.push({ filePath, ...result });
+      
+      if (result.success) {
+        acquired.push(filePath);
+      } else {
+        // Rollback - release all acquired locks
+        for (const acquiredPath of acquired) {
+          await this.releaseLock(agentId, acquiredPath);
+        }
+        
+        return {
+          success: false,
+          reason: "partial-failure",
+          failedFile: filePath,
+          failedReason: result.reason,
+          holder: result.holder
+        };
+      }
+    }
+    
+    return { success: true, locks: acquired };
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // CHANGE PROPOSALS
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Submit a change proposal
+   * @param {string} agentId - Agent submitting the proposal
+   * @param {Object} proposal - { description, files, changes, priority }
+   */
+  async propose(agentId, proposal) {
+    const id = generateUUID();
+    const now = new Date().toISOString();
+    
+    const fullProposal = {
+      id,
+      agentId,
+      agentName: this.state.agents[agentId]?.name || "unknown",
+      description: proposal.description || "",
+      files: proposal.files || [],
+      changes: proposal.changes || [],
+      priority: proposal.priority || "normal",
+      status: "pending",
+      createdAt: now,
+      updatedAt: now
+    };
+    
+    // Check for conflicts with other pending proposals
+    const conflicts = this._findConflicts(proposal);
+    if (conflicts.length > 0) {
+      fullProposal.conflicts = conflicts;
+      fullProposal.status = "conflict";
+    }
+    
+    this.state.proposals.push(fullProposal);
+    
+    this._recordEvent("proposal_created", {
+      proposalId: id,
+      agentId,
+      files: proposal.files,
+      hasConflicts: conflicts.length > 0
+    });
+    
+    await this.save();
+    
+    return fullProposal;
+  }
+
+  /**
+   * Find conflicts between a new proposal and existing pending proposals
+   */
+  _findConflicts(proposal) {
+    const conflicts = [];
+    const proposalFiles = new Set(proposal.files || []);
+    
+    for (const existing of this.state.proposals) {
+      // Only check pending proposals
+      if (existing.status !== "pending") continue;
+      
+      // Check for file overlap
+      const existingFiles = new Set(existing.files || []);
+      const overlap = [...proposalFiles].filter(f => existingFiles.has(f));
+      
+      if (overlap.length > 0) {
+        conflicts.push({
+          proposalId: existing.id,
+          agentId: existing.agentId,
+          agentName: existing.agentName,
+          description: existing.description,
+          files: overlap
+        });
+      }
+    }
+    
+    return conflicts;
+  }
+
+  /**
+   * Update proposal status
+   */
+  async updateProposal(proposalId, status, resolution = null) {
+    const proposal = this.state.proposals.find(p => p.id === proposalId);
+    
+    if (!proposal) {
+      return { success: false, reason: "proposal-not-found" };
+    }
+    
+    const validStatuses = ["pending", "approved", "rejected", "conflict", "merged", "cancelled"];
+    if (!validStatuses.includes(status)) {
+      return { success: false, reason: "invalid-status" };
+    }
+    
+    proposal.status = status;
+    proposal.updatedAt = new Date().toISOString();
+    
+    if (resolution) {
+      proposal.resolution = resolution;
+    }
+    
+    this._recordEvent("proposal_updated", {
+      proposalId,
+      status,
+      resolution
+    });
+    
+    await this.save();
+    
+    return { success: true, proposal };
+  }
+
+  /**
+   * Get a proposal by ID
+   */
+  getProposal(proposalId) {
+    return this.state.proposals.find(p => p.id === proposalId) || null;
+  }
+
+  /**
+   * List proposals with optional filtering
+   */
+  listProposals(filter = {}) {
+    let proposals = [...this.state.proposals];
+    
+    if (filter.status) {
+      proposals = proposals.filter(p => p.status === filter.status);
+    }
+    
+    if (filter.agentId) {
+      proposals = proposals.filter(p => p.agentId === filter.agentId);
+    }
+    
+    if (filter.hasConflicts !== undefined) {
+      proposals = proposals.filter(p => 
+        filter.hasConflicts ? (p.conflicts?.length > 0) : (!p.conflicts || p.conflicts.length === 0)
+      );
+    }
+    
+    return proposals;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // STATUS & REPORTING
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get overall conductor status
+   */
+  getStatus() {
+    const now = Date.now();
+    const agents = Object.values(this.state.agents);
+    
+    // Count active agents (seen within timeout)
+    const activeAgents = agents.filter(a => {
+      if (a.status !== "active") return false;
+      return now - new Date(a.lastSeen).getTime() < AGENT_TIMEOUT_MS;
+    });
+    
+    // Count active (non-stale) locks
+    const activeLocks = Object.entries(this.state.locks).filter(([_, lock]) => {
+      return now - new Date(lock.acquiredAt).getTime() < LOCK_TIMEOUT_MS;
+    });
+    
+    // Count proposals by status
+    const proposalsByStatus = {};
+    for (const p of this.state.proposals) {
+      proposalsByStatus[p.status] = (proposalsByStatus[p.status] || 0) + 1;
+    }
+    
+    return {
+      activeAgents: activeAgents.length,
+      totalAgents: agents.length,
+      activeLocks: activeLocks.length,
+      totalLocks: Object.keys(this.state.locks).length,
+      pendingProposals: proposalsByStatus.pending || 0,
+      conflictProposals: proposalsByStatus.conflict || 0,
+      totalProposals: this.state.proposals.length,
+      proposalsByStatus,
+      historyCount: this.state.history.length,
+      stateCreated: this.state.createdAt,
+      lastUpdated: this.state.updatedAt
+    };
+  }
+
+  /**
+   * Get recent history events
+   */
+  getHistory(limit = 50) {
+    return this.state.history.slice(-limit).reverse();
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // INTERNAL HELPERS
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Normalize a file path for consistent lookups
+   */
+  _normalizePath(filePath) {
+    // Convert to forward slashes, remove leading ./
+    return filePath
+      .replace(/\\/g, "/")
+      .replace(/^\.\//, "")
+      .replace(/\/+/g, "/");
+  }
+
+  /**
+   * Record an event in history
+   */
+  _recordEvent(type, data) {
+    this.state.history.push({
+      type,
+      timestamp: new Date().toISOString(),
+      ...data
+    });
+    
+    // Keep history bounded (last 1000 events)
+    if (this.state.history.length > 1000) {
+      this.state.history = this.state.history.slice(-1000);
+    }
+  }
+
+  /**
+   * Clean up stale locks and inactive agents
+   */
+  async cleanup() {
+    const now = Date.now();
+    let cleaned = { locks: 0, agents: 0 };
+    
+    // Remove stale locks
+    for (const [filePath, lock] of Object.entries(this.state.locks)) {
+      const lockAge = now - new Date(lock.acquiredAt).getTime();
+      if (lockAge >= LOCK_TIMEOUT_MS) {
+        delete this.state.locks[filePath];
+        cleaned.locks++;
+      }
+    }
+    
+    // Mark inactive agents
+    for (const agent of Object.values(this.state.agents)) {
+      if (agent.status === "active") {
+        const lastSeen = now - new Date(agent.lastSeen).getTime();
+        if (lastSeen >= AGENT_TIMEOUT_MS) {
+          agent.status = "inactive";
+          cleaned.agents++;
+        }
+      }
+    }
+    
+    if (cleaned.locks > 0 || cleaned.agents > 0) {
+      this._recordEvent("cleanup", cleaned);
+      await this.save();
+    }
+    
+    return cleaned;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SINGLETON EXPORT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const conductor = new Conductor();
+
+module.exports = {
+  Conductor,
+  conductor
+};