@vibecheckai/cli 3.2.6 → 3.3.0

package/mcp-server/conductor/execution-planner.js

@@ -0,0 +1,544 @@
+/**
+ * Conductor Execution Planner
+ * 
+ * Plans deterministic execution ordering for multi-agent operations.
+ * Uses topological sorting to respect dependencies.
+ * 
+ * Codename: Conductor
+ */
+
+"use strict";
+
+import path from "path";
+
+/**
+ * @typedef {Object} ExecutionStep
+ * @property {number} order - Execution order (0 = first)
+ * @property {string} proposalId - Proposal to execute
+ * @property {string} agentId - Agent that owns the proposal
+ * @property {string[]} dependsOn - Proposal IDs this depends on
+ * @property {string[]} blockedBy - Proposal IDs blocking this
+ * @property {boolean} canExecuteNow - Can execute immediately
+ * @property {string} status - pending, executing, completed, failed
+ */
+
+/**
+ * @typedef {Object} ExecutionPlan
+ * @property {string} planId - Unique plan ID
+ * @property {ExecutionStep[]} steps - Ordered execution steps
+ * @property {boolean} canExecute - Can the plan be executed
+ * @property {Object[]} conflicts - Unresolved conflicts blocking execution
+ * @property {Date} createdAt - When plan was created
+ */
+
+/**
+ * Tier priority mapping (higher = more priority)
+ */
+const TIER_PRIORITY = {
+  ENTERPRISE: 4,
+  PRO: 3,
+  STARTER: 2,
+  FREE: 1,
+};
+
+/**
+ * Execution Planner class
+ */
+class ExecutionPlanner {
+  constructor(conflictResolver = null) {
+    this.conflictResolver = conflictResolver;
+    this.plans = new Map(); // planId -> ExecutionPlan
+    this.executionHistory = []; // For auditing
+  }
+  
+  /**
+   * Set the conflict resolver
+   * @param {Object} resolver - Conflict resolver instance
+   */
+  setConflictResolver(resolver) {
+    this.conflictResolver = resolver;
+  }
+  
+  /**
+   * Create an execution plan from proposals
+   * @param {Object[]} proposals - Proposals to plan
+   * @param {Object} options - Planning options
+   * @returns {ExecutionPlan} Execution plan
+   */
+  createPlan(proposals, options = {}) {
+    const planId = `plan_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    
+    // Build dependency graph
+    const graph = this.buildDependencyGraph(proposals);
+    
+    // Check for cycles
+    const cycles = this.detectCycles(graph);
+    if (cycles.length > 0) {
+      return {
+        planId,
+        steps: [],
+        canExecute: false,
+        conflicts: cycles.map(c => ({
+          type: "circular_dependency",
+          proposals: c,
+          description: `Circular dependency detected: ${c.join(" -> ")}`,
+        })),
+        createdAt: new Date(),
+      };
+    }
+    
+    // Topological sort
+    const sortedOrder = this.topologicalSort(graph);
+    
+    if (!sortedOrder) {
+      return {
+        planId,
+        steps: [],
+        canExecute: false,
+        conflicts: [{ type: "sort_failed", description: "Could not determine execution order" }],
+        createdAt: new Date(),
+      };
+    }
+    
+    // Apply tier-based priority within independent groups
+    const prioritizedOrder = this.applyTierPriority(sortedOrder, proposals);
+    
+    // Build execution steps
+    const steps = this.buildExecutionSteps(prioritizedOrder, proposals, graph);
+    
+    // Check for blocking conflicts
+    const blockingConflicts = this.getBlockingConflicts(proposals);
+    
+    const plan = {
+      planId,
+      steps,
+      canExecute: blockingConflicts.length === 0,
+      conflicts: blockingConflicts,
+      createdAt: new Date(),
+    };
+    
+    this.plans.set(planId, plan);
+    
+    return plan;
+  }
+  
+  /**
+   * Build a dependency graph from proposals
+   * @param {Object[]} proposals - Proposals to analyze
+   * @returns {Map} Dependency graph (proposalId -> Set<dependsOn>)
+   */
+  buildDependencyGraph(proposals) {
+    const graph = new Map();
+    
+    // Initialize all nodes
+    for (const proposal of proposals) {
+      graph.set(proposal.proposalId, new Set());
+    }
+    
+    // Build dependencies based on file overlaps and assumptions
+    for (const proposalA of proposals) {
+      const filesA = this.extractAffectedFiles(proposalA);
+      const assumptionsA = proposalA.assumptions || [];
+      
+      for (const proposalB of proposals) {
+        if (proposalA.proposalId === proposalB.proposalId) continue;
+        
+        const operationsB = proposalB.operations || [];
+        
+        // Check if A's assumptions depend on B's operations
+        for (const assumption of assumptionsA) {
+          for (const operation of operationsB) {
+            if (this.assumptionDependsOnOperation(assumption, operation)) {
+              // A depends on B (B must execute first)
+              graph.get(proposalA.proposalId).add(proposalB.proposalId);
+            }
+          }
+        }
+        
+        // Check for file-based dependencies
+        const filesB = this.extractAffectedFiles(proposalB);
+        for (const fileA of filesA) {
+          for (const fileB of filesB) {
+            const dependency = this.checkFileDependency(fileA, fileB, proposalA, proposalB);
+            if (dependency) {
+              graph.get(dependency.dependent).add(dependency.dependsOn);
+            }
+          }
+        }
+      }
+    }
+    
+    return graph;
+  }
+  
+  /**
+   * Check if an assumption depends on an operation
+   * @param {Object} assumption - Assumption to check
+   * @param {Object} operation - Operation to check against
+   * @returns {boolean} Has dependency
+   */
+  assumptionDependsOnOperation(assumption, operation) {
+    const assumptionTarget = this.normalizePath(assumption.target || assumption.path || "");
+    const operationTarget = this.normalizePath(operation.path || operation.file || "");
+    
+    if (!assumptionTarget || !operationTarget) return false;
+    
+    // If assumption is about a file that the operation creates/modifies
+    if (assumptionTarget === operationTarget) {
+      // file_exists depends on create
+      if (assumption.type === "file_exists" && operation.type === "create") {
+        return true;
+      }
+      // file_contains depends on modify that adds content
+      if (assumption.type === "file_contains" && operation.type === "modify") {
+        return true;
+      }
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Check for file-based dependency between operations
+   * @param {Object} fileA - First file operation
+   * @param {Object} fileB - Second file operation
+   * @param {Object} proposalA - First proposal
+   * @param {Object} proposalB - Second proposal
+   * @returns {Object|null} Dependency info or null
+   */
+  checkFileDependency(fileA, fileB, proposalA, proposalB) {
+    const pathA = this.normalizePath(fileA.path);
+    const pathB = this.normalizePath(fileB.path);
+    
+    if (pathA !== pathB) return null;
+    
+    // Create before modify/read
+    if (fileB.operation === "create" && fileA.operation === "modify") {
+      return { dependent: proposalA.proposalId, dependsOn: proposalB.proposalId };
+    }
+    if (fileA.operation === "create" && fileB.operation === "modify") {
+      return { dependent: proposalB.proposalId, dependsOn: proposalA.proposalId };
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Extract affected files from a proposal
+   * @param {Object} proposal - Proposal to analyze
+   * @returns {Object[]} Affected files
+   */
+  extractAffectedFiles(proposal) {
+    const files = [];
+    for (const op of proposal.operations || []) {
+      if (op.path || op.file || op.filePath) {
+        files.push({
+          path: op.path || op.file || op.filePath,
+          operation: op.type || op.operation || "modify",
+        });
+      }
+    }
+    return files;
+  }
+  
+  /**
+   * Detect cycles in the dependency graph
+   * @param {Map} graph - Dependency graph
+   * @returns {string[][]} Detected cycles
+   */
+  detectCycles(graph) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    
+    const dfs = (node, path) => {
+      if (inStack.has(node)) {
+        const cycleStart = path.indexOf(node);
+        cycles.push(path.slice(cycleStart));
+        return;
+      }
+      
+      if (visited.has(node)) return;
+      
+      visited.add(node);
+      inStack.add(node);
+      path.push(node);
+      
+      const deps = graph.get(node) || new Set();
+      for (const dep of deps) {
+        dfs(dep, [...path]);
+      }
+      
+      inStack.delete(node);
+    };
+    
+    for (const node of graph.keys()) {
+      if (!visited.has(node)) {
+        dfs(node, []);
+      }
+    }
+    
+    return cycles;
+  }
+  
+  /**
+   * Perform topological sort
+   * @param {Map} graph - Dependency graph
+   * @returns {string[]|null} Sorted order or null if not possible
+   */
+  topologicalSort(graph) {
+    const inDegree = new Map();
+    const sorted = [];
+    const queue = [];
+    
+    // Initialize in-degrees
+    for (const node of graph.keys()) {
+      inDegree.set(node, 0);
+    }
+    
+    // Calculate in-degrees
+    for (const [, deps] of graph) {
+      for (const dep of deps) {
+        inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
+      }
+    }
+    
+    // Find nodes with no dependencies
+    for (const [node, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(node);
+      }
+    }
+    
+    // Process queue
+    while (queue.length > 0) {
+      const node = queue.shift();
+      sorted.push(node);
+      
+      const deps = graph.get(node) || new Set();
+      for (const dep of deps) {
+        inDegree.set(dep, inDegree.get(dep) - 1);
+        if (inDegree.get(dep) === 0) {
+          queue.push(dep);
+        }
+      }
+    }
+    
+    // Check if all nodes were processed
+    if (sorted.length !== graph.size) {
+      return null; // Cycle detected
+    }
+    
+    // Reverse to get correct order (dependencies first)
+    return sorted.reverse();
+  }
+  
+  /**
+   * Apply tier-based priority to execution order
+   * @param {string[]} sortedOrder - Topologically sorted order
+   * @param {Object[]} proposals - Proposals
+   * @returns {string[]} Priority-adjusted order
+   */
+  applyTierPriority(sortedOrder, proposals) {
+    const proposalMap = new Map(proposals.map(p => [p.proposalId, p]));
+    
+    // Group by dependency level
+    const levels = this.groupByDependencyLevel(sortedOrder, proposalMap);
+    
+    // Sort within each level by tier priority
+    const prioritized = [];
+    for (const level of levels) {
+      level.sort((a, b) => {
+        const proposalA = proposalMap.get(a);
+        const proposalB = proposalMap.get(b);
+        const priorityA = TIER_PRIORITY[proposalA?.tier] || 1;
+        const priorityB = TIER_PRIORITY[proposalB?.tier] || 1;
+        return priorityB - priorityA; // Higher priority first
+      });
+      prioritized.push(...level);
+    }
+    
+    return prioritized;
+  }
+  
+  /**
+   * Group proposals by dependency level
+   * @param {string[]} sorted - Sorted order
+   * @param {Map} proposalMap - Proposal map
+   * @returns {string[][]} Grouped levels
+   */
+  groupByDependencyLevel(sorted, proposalMap) {
+    // Simple grouping - items that can execute in parallel at each step
+    // For now, return as individual levels
+    return sorted.map(id => [id]);
+  }
+  
+  /**
+   * Build execution steps from sorted order
+   * @param {string[]} order - Execution order
+   * @param {Object[]} proposals - Proposals
+   * @param {Map} graph - Dependency graph
+   * @returns {ExecutionStep[]} Execution steps
+   */
+  buildExecutionSteps(order, proposals, graph) {
+    const proposalMap = new Map(proposals.map(p => [p.proposalId, p]));
+    const steps = [];
+    const completed = new Set();
+    
+    for (let i = 0; i < order.length; i++) {
+      const proposalId = order[i];
+      const proposal = proposalMap.get(proposalId);
+      
+      if (!proposal) continue;
+      
+      const dependencies = Array.from(graph.get(proposalId) || []);
+      const blockedBy = dependencies.filter(dep => !completed.has(dep));
+      
+      steps.push({
+        order: i,
+        proposalId,
+        agentId: proposal.agentId,
+        sessionId: proposal.sessionId,
+        tier: proposal.tier,
+        intent: proposal.intent,
+        dependsOn: dependencies,
+        blockedBy,
+        canExecuteNow: blockedBy.length === 0,
+        status: "pending",
+      });
+      
+      // For planning purposes, mark as "completed"
+      completed.add(proposalId);
+    }
+    
+    return steps;
+  }
+  
+  /**
+   * Get blocking conflicts from the conflict resolver
+   * @param {Object[]} proposals - Proposals to check
+   * @returns {Object[]} Blocking conflicts
+   */
+  getBlockingConflicts(proposals) {
+    if (!this.conflictResolver) return [];
+    
+    const blocking = [];
+    
+    for (const proposal of proposals) {
+      const result = this.conflictResolver.canProceed(proposal.proposalId);
+      if (!result.canProceed) {
+        blocking.push(...result.mustResolve);
+      }
+    }
+    
+    return blocking;
+  }
+  
+  /**
+   * Update step status
+   * @param {string} planId - Plan ID
+   * @param {string} proposalId - Proposal ID
+   * @param {string} status - New status
+   */
+  updateStepStatus(planId, proposalId, status) {
+    const plan = this.plans.get(planId);
+    if (!plan) return;
+    
+    const step = plan.steps.find(s => s.proposalId === proposalId);
+    if (step) {
+      step.status = status;
+      
+      // Update canExecuteNow for dependent steps
+      if (status === "completed") {
+        for (const s of plan.steps) {
+          s.blockedBy = s.blockedBy.filter(b => b !== proposalId);
+          s.canExecuteNow = s.blockedBy.length === 0 && s.status === "pending";
+        }
+      }
+      
+      // Record in history
+      this.executionHistory.push({
+        planId,
+        proposalId,
+        status,
+        timestamp: new Date(),
+      });
+    }
+  }
+  
+  /**
+   * Get next executable steps from a plan
+   * @param {string} planId - Plan ID
+   * @returns {ExecutionStep[]} Executable steps
+   */
+  getNextExecutableSteps(planId) {
+    const plan = this.plans.get(planId);
+    if (!plan) return [];
+    
+    return plan.steps.filter(s => s.canExecuteNow && s.status === "pending");
+  }
+  
+  /**
+   * Check if plan is complete
+   * @param {string} planId - Plan ID
+   * @returns {boolean} Is complete
+   */
+  isPlanComplete(planId) {
+    const plan = this.plans.get(planId);
+    if (!plan) return false;
+    
+    return plan.steps.every(s => s.status === "completed" || s.status === "failed");
+  }
+  
+  /**
+   * Get plan summary
+   * @param {string} planId - Plan ID
+   * @returns {Object} Plan summary
+   */
+  getPlanSummary(planId) {
+    const plan = this.plans.get(planId);
+    if (!plan) return null;
+    
+    const pending = plan.steps.filter(s => s.status === "pending").length;
+    const executing = plan.steps.filter(s => s.status === "executing").length;
+    const completed = plan.steps.filter(s => s.status === "completed").length;
+    const failed = plan.steps.filter(s => s.status === "failed").length;
+    
+    return {
+      planId,
+      totalSteps: plan.steps.length,
+      pending,
+      executing,
+      completed,
+      failed,
+      canExecute: plan.canExecute,
+      isComplete: pending === 0 && executing === 0,
+      conflicts: plan.conflicts.length,
+    };
+  }
+  
+  /**
+   * Normalize a file path
+   * @param {string} filePath - Path to normalize
+   * @returns {string} Normalized path
+   */
+  normalizePath(filePath) {
+    if (!filePath) return "";
+    return path.resolve(filePath).replace(/\\/g, "/").toLowerCase();
+  }
+}
+
+/**
+ * Create a new execution planner
+ * @param {Object} conflictResolver - Optional conflict resolver
+ * @returns {ExecutionPlanner} New planner
+ */
+function createExecutionPlanner(conflictResolver = null) {
+  return new ExecutionPlanner(conflictResolver);
+}
+
+export {
+  ExecutionPlanner,
+  createExecutionPlanner,
+  TIER_PRIORITY,
+};