@stackmemoryai/stackmemory 0.3.22 → 0.3.25

package/dist/integrations/ralph/swarm/swarm-coordinator.js

@@ -0,0 +1,656 @@
+import { v4 as uuidv4 } from "uuid";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { logger } from "../../../core/monitoring/logger.js";
+import { FrameManager } from "../../../core/context/frame-manager.js";
+import { sessionManager } from "../../../core/session/index.js";
+import { sharedContextLayer } from "../../../core/context/shared-context-layer.js";
+import { RalphStackMemoryBridge } from "../bridge/ralph-stackmemory-bridge.js";
+import { GitWorkflowManager } from "./git-workflow-manager.js";
+class SwarmCoordinator {
+  frameManager;
+  activeAgents = /* @__PURE__ */ new Map();
+  swarmState;
+  config;
+  coordinationTimer;
+  plannerWakeupQueue = /* @__PURE__ */ new Map();
+  gitWorkflowManager;
+  constructor(config) {
+    this.config = {
+      maxAgents: 10,
+      coordinationInterval: 3e4,
+      // 30 seconds
+      driftDetectionThreshold: 5,
+      // 5 failed iterations before considering drift
+      freshStartInterval: 36e5,
+      // 1 hour
+      conflictResolutionStrategy: "expertise",
+      enableDynamicPlanning: true,
+      pathologicalBehaviorDetection: true,
+      ...config
+    };
+    this.swarmState = {
+      id: uuidv4(),
+      status: "idle",
+      startTime: Date.now(),
+      activeTaskCount: 0,
+      completedTaskCount: 0,
+      coordination: {
+        events: [],
+        conflicts: [],
+        resolutions: []
+      },
+      performance: {
+        throughput: 0,
+        efficiency: 0,
+        coordination_overhead: 0
+      }
+    };
+    this.gitWorkflowManager = new GitWorkflowManager({
+      enableGitWorkflow: true,
+      branchStrategy: "agent",
+      autoCommit: true,
+      commitFrequency: 5,
+      mergStrategy: "squash"
+    });
+    logger.info("Swarm coordinator initialized", this.config);
+  }
+  async initialize() {
+    try {
+      await sessionManager.initialize();
+      await sharedContextLayer.initialize();
+      const session = await sessionManager.getOrCreateSession({});
+      if (session.database) {
+        this.frameManager = new FrameManager(session.database, session.projectId);
+      }
+      this.startCoordinationLoop();
+      logger.info("Swarm coordinator initialized successfully");
+    } catch (error) {
+      logger.error("Failed to initialize swarm coordinator", error);
+      throw error;
+    }
+  }
+  /**
+   * Launch a swarm of agents to work on a complex project
+   */
+  async launchSwarm(projectDescription, agents, coordination) {
+    logger.info("Launching swarm", {
+      project: projectDescription.substring(0, 100),
+      agentCount: agents.length
+    });
+    const swarmId = uuidv4();
+    try {
+      if (agents.length > this.config.maxAgents) {
+        throw new Error(`Too many agents requested: ${agents.length} > ${this.config.maxAgents}`);
+      }
+      const swarmTasks = await this.decomposeProjectIntoSwarmTasks(projectDescription);
+      const initializedAgents = await this.initializeSpecializedAgents(agents, swarmTasks);
+      const allocation = await this.allocateTasksToAgents(swarmTasks, initializedAgents);
+      this.swarmState = {
+        ...this.swarmState,
+        id: swarmId,
+        status: "active",
+        activeTaskCount: swarmTasks.length,
+        project: projectDescription,
+        agents: initializedAgents,
+        tasks: swarmTasks,
+        allocation
+      };
+      await this.executeSwarmTasks(allocation);
+      logger.info("Swarm launched successfully", { swarmId, agentCount: initializedAgents.length });
+      return swarmId;
+    } catch (error) {
+      logger.error("Failed to launch swarm", error);
+      throw error;
+    }
+  }
+  /**
+   * Decompose project into tasks suitable for swarm execution
+   */
+  async decomposeProjectIntoSwarmTasks(projectDescription) {
+    const tasks = [];
+    const complexity = this.analyzeProjectComplexity(projectDescription);
+    if (complexity.needsArchitecture) {
+      tasks.push({
+        id: uuidv4(),
+        type: "architecture",
+        title: "System Architecture Design",
+        description: "Design overall system architecture and component relationships",
+        priority: 1,
+        estimatedEffort: "high",
+        requiredRoles: ["architect", "system_designer"],
+        dependencies: [],
+        acceptanceCriteria: [
+          "Architecture diagram created",
+          "Component interfaces defined",
+          "Data flow documented"
+        ]
+      });
+    }
+    const coreFeatures = this.extractCoreFeatures(projectDescription);
+    for (const feature of coreFeatures) {
+      tasks.push({
+        id: uuidv4(),
+        type: "implementation",
+        title: `Implement ${feature.name}`,
+        description: feature.description,
+        priority: 2,
+        estimatedEffort: feature.complexity,
+        requiredRoles: ["developer", feature.specialization || "fullstack"],
+        dependencies: complexity.needsArchitecture ? [tasks[0].id] : [],
+        acceptanceCriteria: feature.criteria
+      });
+    }
+    if (complexity.needsTesting) {
+      tasks.push({
+        id: uuidv4(),
+        type: "testing",
+        title: "Comprehensive Testing Suite",
+        description: "Create unit, integration, and end-to-end tests",
+        priority: 3,
+        estimatedEffort: "medium",
+        requiredRoles: ["qa_engineer", "test_automation"],
+        dependencies: tasks.filter((t) => t.type === "implementation").map((t) => t.id),
+        acceptanceCriteria: [
+          "Unit tests achieve >90% coverage",
+          "Integration tests pass",
+          "Performance benchmarks met"
+        ]
+      });
+    }
+    if (complexity.needsDocumentation) {
+      tasks.push({
+        id: uuidv4(),
+        type: "documentation",
+        title: "Documentation and Examples",
+        description: "Create user documentation, API docs, and usage examples",
+        priority: 4,
+        estimatedEffort: "low",
+        requiredRoles: ["technical_writer", "developer"],
+        dependencies: [],
+        // Can run in parallel
+        acceptanceCriteria: [
+          "README with setup instructions",
+          "API documentation complete",
+          "Usage examples provided"
+        ]
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Initialize specialized agents with role-specific configurations
+   */
+  async initializeSpecializedAgents(specifications, tasks) {
+    const agents = [];
+    for (const spec of specifications) {
+      const agent = {
+        id: uuidv4(),
+        role: spec.role,
+        specialization: spec,
+        status: "initializing",
+        capabilities: this.defineCapabilities(spec.role),
+        workingDirectory: `.swarm/${spec.role}-${Date.now()}`,
+        currentTask: null,
+        performance: {
+          tasksCompleted: 0,
+          successRate: 1,
+          averageTaskTime: 0,
+          driftDetected: false,
+          lastFreshStart: Date.now()
+        },
+        coordination: {
+          communicationStyle: this.defineCommuncationStyle(spec.role),
+          conflictResolution: spec.conflictResolution || "defer_to_expertise",
+          collaborationPreferences: spec.collaborationPreferences || []
+        }
+      };
+      await this.setupAgentEnvironment(agent);
+      await this.configureAgentPrompts(agent);
+      agents.push(agent);
+      this.activeAgents.set(agent.id, agent);
+    }
+    logger.info(`Initialized ${agents.length} specialized agents`);
+    return agents;
+  }
+  /**
+   * Allocate tasks to agents based on specialization and workload
+   */
+  async allocateTasksToAgents(tasks, agents) {
+    const allocation = {
+      assignments: /* @__PURE__ */ new Map(),
+      loadBalancing: "capability_based",
+      conflictResolution: this.config.conflictResolutionStrategy
+    };
+    const sortedTasks = this.topologicalSort(tasks);
+    for (const task of sortedTasks) {
+      const suitableAgents = agents.filter(
+        (agent) => task.requiredRoles.some((role) => this.agentCanHandle(agent, role))
+      );
+      if (suitableAgents.length === 0) {
+        logger.warn(`No suitable agents found for task: ${task.title}`);
+        continue;
+      }
+      const selectedAgent = this.selectOptimalAgent(suitableAgents, task);
+      allocation.assignments.set(task.id, {
+        agentId: selectedAgent.id,
+        taskId: task.id,
+        assignedAt: Date.now(),
+        estimatedCompletion: Date.now() + this.estimateTaskDuration(task),
+        coordination: {
+          collaborators: this.findCollaborators(selectedAgent, task, agents),
+          reviewers: this.findReviewers(selectedAgent, task, agents)
+        }
+      });
+      selectedAgent.currentTask = task.id;
+    }
+    return allocation;
+  }
+  /**
+   * Execute swarm tasks with coordination
+   */
+  async executeSwarmTasks(allocation) {
+    const executionPromises = [];
+    for (const [taskId, assignment] of allocation.assignments) {
+      const agent = this.activeAgents.get(assignment.agentId);
+      const task = this.swarmState.tasks?.find((t) => t.id === taskId);
+      if (!agent || !task) continue;
+      const executionPromise = this.executeAgentTask(agent, task, assignment);
+      executionPromises.push(executionPromise);
+    }
+    await Promise.allSettled(executionPromises);
+  }
+  /**
+   * Execute a single agent task with coordination
+   */
+  async executeAgentTask(agent, task, assignment) {
+    logger.info(`Agent ${agent.role} starting task: ${task.title}`);
+    try {
+      agent.status = "active";
+      await this.gitWorkflowManager.initializeAgentWorkflow(agent, task);
+      const ralph = new RalphStackMemoryBridge({
+        baseDir: path.join(agent.workingDirectory, task.id),
+        maxIterations: this.calculateMaxIterations(task),
+        useStackMemory: true
+      });
+      const contextualPrompt = await this.synthesizeContextualPrompt(agent, task);
+      await ralph.initialize({
+        task: contextualPrompt,
+        criteria: task.acceptanceCriteria.join("\n")
+      });
+      this.setupAgentCoordination(agent, ralph, assignment);
+      await ralph.run();
+      await this.gitWorkflowManager.commitAgentWork(agent, task);
+      this.updateAgentPerformance(agent, true);
+      await this.gitWorkflowManager.mergeAgentWork(agent, task);
+      await this.notifyTaskCompletion(agent, task, true);
+      agent.status = "idle";
+      logger.info(`Agent ${agent.role} completed task: ${task.title}`);
+    } catch (error) {
+      logger.error(`Agent ${agent.role} failed task: ${task.title}`, error);
+      this.updateAgentPerformance(agent, false);
+      await this.handleTaskFailure(agent, task, error);
+      agent.status = "error";
+    }
+  }
+  /**
+   * Synthesize contextual prompt incorporating swarm knowledge
+   */
+  async synthesizeContextualPrompt(agent, task) {
+    const basePrompt = task.description;
+    const roleSpecificInstructions = this.getRoleSpecificInstructions(agent.role);
+    const swarmContext = await this.getSwarmContext(task);
+    const coordinationInstructions = this.getCoordinationInstructions(agent);
+    return `
+${roleSpecificInstructions}
+
+TASK: ${basePrompt}
+
+SWARM CONTEXT:
+${swarmContext}
+
+COORDINATION GUIDELINES:
+${coordinationInstructions}
+
+Remember:
+- You are part of a swarm working on: ${this.swarmState.project}
+- Other agents are working on related tasks
+- Communicate findings through StackMemory shared context
+- Focus on your specialization while being aware of the bigger picture
+- Detect and avoid pathological behaviors (infinite loops, tunnel vision)
+- Request fresh starts if you detect drift in your approach
+
+ACCEPTANCE CRITERIA:
+${task.acceptanceCriteria.map((c) => `- ${c}`).join("\n")}
+`;
+  }
+  /**
+   * Start coordination monitoring loop
+   */
+  startCoordinationLoop() {
+    this.coordinationTimer = setInterval(() => {
+      this.performCoordinationCycle().catch((error) => {
+        logger.error("Coordination cycle failed", error);
+      });
+    }, this.config.coordinationInterval);
+  }
+  /**
+   * Perform coordination cycle
+   */
+  async performCoordinationCycle() {
+    if (this.swarmState.status !== "active") return;
+    logger.debug("Performing coordination cycle");
+    if (this.config.pathologicalBehaviorDetection) {
+      await this.detectPathologicalBehaviors();
+    }
+    if (this.config.enableDynamicPlanning) {
+      await this.wakeUpPlanners();
+    }
+    await this.resolveActiveConflicts();
+    await this.rebalanceWorkload();
+    await this.triggerFreshStartsIfNeeded();
+    this.updateSwarmMetrics();
+  }
+  /**
+   * Detect pathological behaviors in agents
+   */
+  async detectPathologicalBehaviors() {
+    for (const agent of this.activeAgents.values()) {
+      if (agent.status !== "active") continue;
+      if (agent.performance.driftDetected) {
+        logger.warn(`Drift detected in agent ${agent.role}, triggering fresh start`);
+        await this.triggerFreshStart(agent);
+        continue;
+      }
+      if (await this.detectTunnelVision(agent)) {
+        logger.warn(`Tunnel vision detected in agent ${agent.role}, providing alternative approach`);
+        await this.provideAlternativeApproach(agent);
+      }
+      if (await this.detectExcessiveRuntime(agent)) {
+        logger.warn(`Excessive runtime detected in agent ${agent.role}, requesting checkpoint`);
+        await this.requestCheckpoint(agent);
+      }
+    }
+  }
+  /**
+   * Wake up planners when their tasks complete
+   */
+  async wakeUpPlanners() {
+    for (const [agentId, wakeupCallback] of this.plannerWakeupQueue) {
+      const agent = this.activeAgents.get(agentId);
+      if (!agent || agent.status !== "idle") continue;
+      logger.info(`Waking up planner agent: ${agent.role}`);
+      wakeupCallback();
+      this.plannerWakeupQueue.delete(agentId);
+    }
+  }
+  // Helper methods for role specialization and coordination
+  defineCapabilities(role) {
+    const capabilityMap = {
+      "architect": ["system_design", "component_modeling", "architecture_validation"],
+      "planner": ["task_decomposition", "dependency_analysis", "resource_planning"],
+      "developer": ["code_implementation", "debugging", "refactoring"],
+      "reviewer": ["code_review", "quality_assessment", "best_practice_enforcement"],
+      "tester": ["test_design", "automation", "validation"],
+      "optimizer": ["performance_analysis", "resource_optimization", "bottleneck_identification"],
+      "documenter": ["technical_writing", "api_documentation", "example_creation"],
+      "coordinator": ["task_coordination", "conflict_resolution", "progress_tracking"]
+    };
+    return capabilityMap[role] || [];
+  }
+  defineCommuncationStyle(role) {
+    const styleMap = {
+      "architect": "high_level_design_focused",
+      "planner": "structured_and_methodical",
+      "developer": "implementation_focused",
+      "reviewer": "quality_focused_constructive",
+      "tester": "validation_focused",
+      "optimizer": "performance_metrics_focused",
+      "documenter": "clarity_focused",
+      "coordinator": "facilitative_and_diplomatic"
+    };
+    return styleMap[role] || "collaborative";
+  }
+  getRoleSpecificInstructions(role) {
+    const instructionMap = {
+      "architect": `
+You are a SYSTEM ARCHITECT. Your role is to:
+- Design high-level system architecture
+- Define component interfaces and relationships
+- Ensure architectural consistency across the project
+- Think in terms of scalability, maintainability, and extensibility
+- Collaborate with developers to validate feasibility`,
+      "planner": `
+You are a PROJECT PLANNER. Your role is to:
+- Break down complex tasks into manageable steps
+- Identify dependencies and critical path
+- Coordinate with other agents on sequencing
+- Wake up when tasks complete to plan next steps
+- Adapt plans based on actual progress`,
+      "developer": `
+You are a SPECIALIZED DEVELOPER. Your role is to:
+- Implement features according to specifications
+- Write clean, maintainable code
+- Follow established patterns and conventions
+- Integrate with other components
+- Communicate implementation details clearly`,
+      "reviewer": `
+You are a CODE REVIEWER. Your role is to:
+- Review code for quality, correctness, and best practices
+- Provide constructive feedback
+- Ensure consistency with project standards
+- Identify potential issues before they become problems
+- Approve or request changes`,
+      "tester": `
+You are a QA ENGINEER. Your role is to:
+- Design comprehensive test strategies
+- Implement automated tests
+- Validate functionality and performance
+- Report bugs clearly and reproducibly
+- Ensure quality gates are met`,
+      "optimizer": `
+You are a PERFORMANCE OPTIMIZER. Your role is to:
+- Analyze system performance and identify bottlenecks
+- Implement optimizations
+- Monitor resource usage
+- Establish performance benchmarks
+- Ensure scalability requirements are met`,
+      "documenter": `
+You are a TECHNICAL WRITER. Your role is to:
+- Create clear, comprehensive documentation
+- Write API documentation and usage examples
+- Ensure documentation stays up-to-date
+- Focus on user experience and clarity
+- Collaborate with developers to understand features`,
+      "coordinator": `
+You are a PROJECT COORDINATOR. Your role is to:
+- Facilitate communication between agents
+- Resolve conflicts and blockers
+- Track overall project progress
+- Ensure no tasks fall through cracks
+- Maintain project timeline and quality`
+    };
+    return instructionMap[role] || "You are a specialized agent contributing to a larger project.";
+  }
+  // Additional helper methods would be implemented here...
+  analyzeProjectComplexity(description) {
+    return {
+      needsArchitecture: description.length > 500 || description.includes("system") || description.includes("platform"),
+      needsTesting: true,
+      // Almost all projects need testing
+      needsDocumentation: description.includes("API") || description.includes("library"),
+      complexity: "medium"
+    };
+  }
+  extractCoreFeatures(description) {
+    return [{
+      name: "Core Feature",
+      description: "Main functionality implementation",
+      complexity: "medium",
+      criteria: ["Feature works correctly", "Handles edge cases", "Follows coding standards"]
+    }];
+  }
+  // Implement remaining helper methods...
+  async setupAgentEnvironment(agent) {
+    try {
+      await fs.mkdir(agent.workingDirectory, { recursive: true });
+      logger.debug(`Created working directory for agent ${agent.id}: ${agent.workingDirectory}`);
+    } catch (error) {
+      logger.warn(`Could not create working directory for agent ${agent.id}`, error);
+    }
+  }
+  async configureAgentPrompts(agent) {
+    logger.debug(`Configured prompts for agent ${agent.role}`);
+  }
+  topologicalSort(tasks) {
+    const sorted = [];
+    const visited = /* @__PURE__ */ new Set();
+    const visiting = /* @__PURE__ */ new Set();
+    const visit = (task) => {
+      if (visited.has(task.id)) return;
+      if (visiting.has(task.id)) {
+        logger.warn(`Circular dependency detected for task: ${task.id}`);
+        return;
+      }
+      visiting.add(task.id);
+      for (const depId of task.dependencies) {
+        const depTask = tasks.find((t) => t.id === depId);
+        if (depTask) visit(depTask);
+      }
+      visiting.delete(task.id);
+      visited.add(task.id);
+      sorted.push(task);
+    };
+    tasks.forEach(visit);
+    return sorted;
+  }
+  agentCanHandle(agent, role) {
+    return agent.role === role || agent.capabilities.includes(role);
+  }
+  selectOptimalAgent(agents, task) {
+    return agents.reduce((best, current) => {
+      const bestLoad = best.currentTask ? 1 : 0;
+      const currentLoad = current.currentTask ? 1 : 0;
+      return currentLoad < bestLoad ? current : best;
+    });
+  }
+  estimateTaskDuration(task) {
+    const durations = {
+      low: 6e4,
+      // 1 minute
+      medium: 3e5,
+      // 5 minutes
+      high: 9e5
+      // 15 minutes
+    };
+    return durations[task.estimatedEffort] || 3e5;
+  }
+  findCollaborators(agent, task, agents) {
+    return agents.filter((a) => a.id !== agent.id && a.currentTask).map((a) => a.id).slice(0, 2);
+  }
+  findReviewers(agent, task, agents) {
+    return agents.filter((a) => a.role === "reviewer" && a.id !== agent.id).map((a) => a.id);
+  }
+  calculateMaxIterations(task) {
+    const iterations = {
+      low: 5,
+      medium: 10,
+      high: 20
+    };
+    return iterations[task.estimatedEffort] || 10;
+  }
+  async getSwarmContext(task) {
+    const relatedTasks = Array.from(this.activeAgents.values()).filter((a) => a.currentTask).map((a) => `- Agent ${a.role} is working on task ${a.currentTask}`).join("\n");
+    return relatedTasks || "No other agents currently active";
+  }
+  getCoordinationInstructions(agent) {
+    return `
+- Save progress to shared context regularly
+- Check for updates from collaborators
+- Request help if blocked for more than 2 iterations
+- Report completion immediately`;
+  }
+  setupAgentCoordination(agent, ralph, assignment) {
+    logger.debug(`Setting up coordination for agent ${agent.id}`);
+  }
+  updateAgentPerformance(agent, success) {
+    agent.performance.tasksCompleted++;
+    if (!success) {
+      agent.performance.successRate = agent.performance.successRate * (agent.performance.tasksCompleted - 1) / agent.performance.tasksCompleted;
+    }
+  }
+  async notifyTaskCompletion(agent, task, success) {
+    const event = {
+      type: "task_completion",
+      agentId: agent.id,
+      timestamp: Date.now(),
+      data: {
+        taskId: task.id,
+        success,
+        agent: agent.role
+      }
+    };
+    this.swarmState.coordination?.events.push(event);
+    logger.info(`Task ${task.id} completed by agent ${agent.role}: ${success ? "SUCCESS" : "FAILED"}`);
+  }
+  async handleTaskFailure(agent, task, error) {
+    logger.error(`Agent ${agent.role} failed task ${task.id}`, error);
+    if (this.swarmState.coordination) {
+      this.swarmState.coordination.conflicts.push({
+        type: "task_failure",
+        agents: [agent.id],
+        timestamp: Date.now(),
+        description: error.message
+      });
+    }
+  }
+  async detectTunnelVision(agent) {
+    return false;
+  }
+  async provideAlternativeApproach(agent) {
+    logger.info(`Providing alternative approach to agent ${agent.role}`);
+  }
+  async detectExcessiveRuntime(agent) {
+    if (!agent.performance.lastFreshStart) return false;
+    return Date.now() - agent.performance.lastFreshStart > 36e5;
+  }
+  async requestCheckpoint(agent) {
+    logger.info(`Requesting checkpoint from agent ${agent.role}`);
+  }
+  async triggerFreshStart(agent) {
+    logger.info(`Triggering fresh start for agent ${agent.role}`);
+    agent.performance.lastFreshStart = Date.now();
+    agent.performance.driftDetected = false;
+  }
+  async resolveActiveConflicts() {
+    if (this.swarmState.coordination?.conflicts.length) {
+      logger.debug(`Resolving ${this.swarmState.coordination.conflicts.length} conflicts`);
+    }
+  }
+  async rebalanceWorkload() {
+    const activeAgents = Array.from(this.activeAgents.values()).filter((a) => a.status === "active");
+    if (activeAgents.length > 0) {
+      logger.debug(`Rebalancing workload among ${activeAgents.length} active agents`);
+    }
+  }
+  async triggerFreshStartsIfNeeded() {
+    for (const agent of this.activeAgents.values()) {
+      if (agent.performance.driftDetected) {
+        await this.triggerFreshStart(agent);
+      }
+    }
+  }
+  updateSwarmMetrics() {
+    if (!this.swarmState.performance) return;
+    const activeCount = Array.from(this.activeAgents.values()).filter((a) => a.status === "active").length;
+    this.swarmState.performance.throughput = this.swarmState.completedTaskCount / ((Date.now() - this.swarmState.startTime) / 1e3);
+    this.swarmState.performance.efficiency = activeCount > 0 ? this.swarmState.completedTaskCount / activeCount : 0;
+  }
+  [Symbol.toStringTag] = "SwarmCoordinator";
+}
+const swarmCoordinator = new SwarmCoordinator();
+export {
+  SwarmCoordinator,
+  swarmCoordinator
+};
+//# sourceMappingURL=swarm-coordinator.js.map