claudehq 1.0.2 → 1.0.5

package/lib/data/orchestration.js

@@ -0,0 +1,941 @@
+/**
+ * Orchestration Data Module - Multi-Agent Orchestration Management
+ *
+ * Handles creating, updating, and managing orchestrations and their agents.
+ * Orchestrations coordinate multiple Claude agents working in parallel.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { ORCHESTRATIONS_DIR, AGENT_STATUS, ORCHESTRATION_STATUS } = require('../core/config');
+const { eventBus, EventTypes } = require('../core/event-bus');
+
+/**
+ * Built-in orchestration templates
+ */
+const ORCHESTRATION_TEMPLATES = {
+  'code-review': {
+    id: 'code-review',
+    name: 'Code Review Pipeline',
+    description: 'Analyze code, review for issues, then fix problems',
+    icon: '🔍',
+    agents: [
+      {
+        name: 'Code Analyzer',
+        model: 'sonnet',
+        prompt: 'Analyze the codebase structure and identify the main components, patterns, and potential areas of concern. Create a summary of findings.',
+        dependencies: []
+      },
+      {
+        name: 'Code Reviewer',
+        model: 'sonnet',
+        prompt: 'Review the code for bugs, security issues, performance problems, and code quality. List all issues found with severity ratings.',
+        dependencies: [] // Will be set to depend on Analyzer
+      },
+      {
+        name: 'Code Fixer',
+        model: 'sonnet',
+        prompt: 'Based on the review findings, fix the identified issues. Make the necessary code changes and explain what was fixed.',
+        dependencies: [] // Will be set to depend on Reviewer
+      }
+    ]
+  },
+  'full-stack-feature': {
+    id: 'full-stack-feature',
+    name: 'Full-Stack Feature',
+    description: 'Build frontend, backend, and tests in parallel, then integrate',
+    icon: '🏗️',
+    agents: [
+      {
+        name: 'Frontend Developer',
+        model: 'sonnet',
+        prompt: 'Implement the frontend components for this feature. Create the UI, handle user interactions, and manage state.',
+        dependencies: []
+      },
+      {
+        name: 'Backend Developer',
+        model: 'sonnet',
+        prompt: 'Implement the backend API endpoints for this feature. Create the routes, controllers, and data models.',
+        dependencies: []
+      },
+      {
+        name: 'Test Engineer',
+        model: 'haiku',
+        prompt: 'Write comprehensive tests for this feature including unit tests, integration tests, and edge cases.',
+        dependencies: []
+      },
+      {
+        name: 'Integration Lead',
+        model: 'sonnet',
+        prompt: 'Integrate the frontend and backend components. Ensure they work together correctly and fix any integration issues.',
+        dependencies: [] // Will depend on Frontend and Backend
+      }
+    ]
+  },
+  'documentation': {
+    id: 'documentation',
+    name: 'Documentation Generator',
+    description: 'Read code, write documentation, then review for quality',
+    icon: '📚',
+    agents: [
+      {
+        name: 'Code Reader',
+        model: 'haiku',
+        prompt: 'Read and understand the codebase. Identify all public APIs, functions, classes, and their purposes.',
+        dependencies: []
+      },
+      {
+        name: 'Doc Writer',
+        model: 'sonnet',
+        prompt: 'Write comprehensive documentation including API reference, usage examples, and architecture overview.',
+        dependencies: [] // Will depend on Code Reader
+      },
+      {
+        name: 'Doc Reviewer',
+        model: 'haiku',
+        prompt: 'Review the documentation for accuracy, clarity, and completeness. Suggest improvements.',
+        dependencies: [] // Will depend on Doc Writer
+      }
+    ]
+  },
+  'bug-fix': {
+    id: 'bug-fix',
+    name: 'Bug Investigation & Fix',
+    description: 'Investigate bug, propose fix, implement and test',
+    icon: '🐛',
+    agents: [
+      {
+        name: 'Bug Investigator',
+        model: 'sonnet',
+        prompt: 'Investigate the reported bug. Find the root cause by examining logs, code, and reproducing the issue.',
+        dependencies: []
+      },
+      {
+        name: 'Fix Implementer',
+        model: 'sonnet',
+        prompt: 'Implement a fix for the bug based on the investigation findings. Make the necessary code changes.',
+        dependencies: [] // Will depend on Investigator
+      },
+      {
+        name: 'Test Verifier',
+        model: 'haiku',
+        prompt: 'Write tests to verify the bug is fixed and add regression tests to prevent future occurrences.',
+        dependencies: [] // Will depend on Implementer
+      }
+    ]
+  },
+  'refactor': {
+    id: 'refactor',
+    name: 'Code Refactoring',
+    description: 'Analyze, plan, and execute a code refactoring',
+    icon: '♻️',
+    agents: [
+      {
+        name: 'Architecture Analyst',
+        model: 'sonnet',
+        prompt: 'Analyze the current code architecture and identify areas that need refactoring. Document technical debt.',
+        dependencies: []
+      },
+      {
+        name: 'Refactor Planner',
+        model: 'sonnet',
+        prompt: 'Create a detailed refactoring plan with step-by-step changes that maintain backward compatibility.',
+        dependencies: [] // Will depend on Analyst
+      },
+      {
+        name: 'Refactor Executor',
+        model: 'sonnet',
+        prompt: 'Execute the refactoring plan. Make incremental changes and ensure tests pass after each change.',
+        dependencies: [] // Will depend on Planner
+      }
+    ]
+  }
+};
+
+/**
+ * Get all available templates
+ * @returns {Array} Array of template summaries
+ */
+function getTemplates() {
+  return Object.values(ORCHESTRATION_TEMPLATES).map(t => ({
+    id: t.id,
+    name: t.name,
+    description: t.description,
+    icon: t.icon,
+    agentCount: t.agents.length
+  }));
+}
+
+/**
+ * Get a specific template by ID
+ * @param {string} templateId - Template ID
+ * @returns {Object|null} Template or null
+ */
+function getTemplate(templateId) {
+  return ORCHESTRATION_TEMPLATES[templateId] || null;
+}
+
+/**
+ * Create orchestration from template
+ * @param {string} templateId - Template ID
+ * @param {Object} options - Override options
+ * @returns {Object} Result with orchestration or error
+ */
+function createFromTemplate(templateId, options = {}) {
+  const template = getTemplate(templateId);
+
+  if (!template) {
+    return { error: 'Template not found' };
+  }
+
+  // Create orchestration config from template
+  const config = {
+    name: options.name || template.name,
+    description: options.description || template.description,
+    templateId: templateId,
+    agents: []
+  };
+
+  // Create agents and set up dependencies
+  const agentIdMap = new Map(); // Map from index to generated ID
+
+  // First pass: create agents
+  template.agents.forEach((agentConfig, index) => {
+    const agent = {
+      name: agentConfig.name,
+      model: agentConfig.model,
+      prompt: options.customPrompts?.[index] || agentConfig.prompt,
+      workingDirectory: options.workingDirectory || process.cwd(),
+      dependencies: []
+    };
+    config.agents.push(agent);
+  });
+
+  // Second pass: set up dependencies based on template structure
+  // For sequential templates, each agent depends on the previous
+  if (['code-review', 'documentation', 'bug-fix', 'refactor'].includes(templateId)) {
+    for (let i = 1; i < config.agents.length; i++) {
+      // Dependency will be resolved after agents are created
+      config.agents[i]._dependsOnIndex = i - 1;
+    }
+  }
+
+  // For full-stack-feature, the Integration Lead depends on Frontend and Backend
+  if (templateId === 'full-stack-feature') {
+    config.agents[3]._dependsOnIndex = [0, 1]; // Integration depends on Frontend and Backend
+  }
+
+  // Create the orchestration
+  const result = createOrchestration(config);
+
+  if (result.error) {
+    return result;
+  }
+
+  // Now set up dependencies using actual agent IDs
+  const orch = result.orchestration;
+  const updates = [];
+
+  orch.agents.forEach((agent, index) => {
+    const templateAgent = config.agents[index];
+    if (templateAgent._dependsOnIndex !== undefined) {
+      const depIndexes = Array.isArray(templateAgent._dependsOnIndex)
+        ? templateAgent._dependsOnIndex
+        : [templateAgent._dependsOnIndex];
+
+      depIndexes.forEach(depIndex => {
+        const depAgentId = orch.agents[depIndex]?.id;
+        if (depAgentId) {
+          addAgentDependency(orch.id, agent.id, depAgentId);
+        }
+      });
+    }
+  });
+
+  // Reload the orchestration to get updated dependencies
+  return { success: true, orchestration: getOrchestration(orch.id) };
+}
+
+/**
+ * Generate a unique ID for orchestrations and agents
+ * @param {string} prefix - Prefix for the ID
+ * @returns {string} Unique ID
+ */
+function generateId(prefix = 'orch') {
+  return `${prefix}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+/**
+ * Ensure orchestrations directory exists
+ */
+function ensureDir() {
+  if (!fs.existsSync(ORCHESTRATIONS_DIR)) {
+    fs.mkdirSync(ORCHESTRATIONS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get the file path for an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {string} File path
+ */
+function getOrchestrationPath(orchestrationId) {
+  return path.join(ORCHESTRATIONS_DIR, `${orchestrationId}.json`);
+}
+
+/**
+ * Create a new agent object
+ * @param {Object} config - Agent configuration
+ * @returns {Object} Agent object
+ */
+function createAgentObject(config) {
+  return {
+    id: generateId('agent'),
+    name: config.name || 'Unnamed Agent',
+    type: config.type || 'general-purpose', // general-purpose, explore, plan, custom
+    status: AGENT_STATUS.PENDING,
+    prompt: config.prompt || '',
+    model: config.model || 'sonnet', // haiku, sonnet, opus
+    workingDirectory: config.workingDirectory || process.cwd(),
+    sessionId: null, // Will be set when agent is spawned
+    tmuxWindow: null, // tmux window name
+    parentAgentId: config.parentAgentId || null,
+    dependencies: config.dependencies || [], // Agent IDs this agent depends on
+    createdAt: new Date().toISOString(),
+    startedAt: null,
+    completedAt: null,
+    error: null,
+    output: null,
+    toolsUsed: [],
+    metadata: config.metadata || {}
+  };
+}
+
+/**
+ * Create a new orchestration
+ * @param {Object} config - Orchestration configuration
+ * @returns {Object} Result with orchestration or error
+ */
+function createOrchestration(config) {
+  ensureDir();
+
+  const orchestration = {
+    id: generateId('orch'),
+    name: config.name || 'Unnamed Orchestration',
+    description: config.description || '',
+    status: ORCHESTRATION_STATUS.DRAFT,
+    agents: [],
+    createdAt: new Date().toISOString(),
+    startedAt: null,
+    completedAt: null,
+    templateId: config.templateId || null,
+    metadata: config.metadata || {}
+  };
+
+  // Add initial agents if provided
+  if (config.agents && Array.isArray(config.agents)) {
+    for (const agentConfig of config.agents) {
+      orchestration.agents.push(createAgentObject(agentConfig));
+    }
+  }
+
+  try {
+    const filePath = getOrchestrationPath(orchestration.id);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.ORCHESTRATION_CREATED, { orchestration });
+
+    return { success: true, orchestration };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Get an orchestration by ID
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {Object|null} Orchestration object or null
+ */
+function getOrchestration(orchestrationId) {
+  const filePath = getOrchestrationPath(orchestrationId);
+
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.error(`Error reading orchestration ${orchestrationId}:`, e.message);
+    return null;
+  }
+}
+
+/**
+ * List all orchestrations
+ * @returns {Array} Array of orchestration objects
+ */
+function listOrchestrations() {
+  ensureDir();
+
+  const orchestrations = [];
+
+  try {
+    const files = fs.readdirSync(ORCHESTRATIONS_DIR).filter(f => f.endsWith('.json'));
+
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(ORCHESTRATIONS_DIR, file), 'utf-8');
+        const orchestration = JSON.parse(content);
+        orchestrations.push(orchestration);
+      } catch (e) {
+        console.error(`Error reading ${file}:`, e.message);
+      }
+    }
+
+    // Sort by creation date, newest first
+    orchestrations.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  } catch (e) {
+    console.error('Error listing orchestrations:', e.message);
+  }
+
+  return orchestrations;
+}
+
+/**
+ * Update an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {Object} updates - Updates to apply
+ * @returns {Object} Result with updated orchestration or error
+ */
+function updateOrchestration(orchestrationId, updates) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const previousStatus = orchestration.status;
+
+  // Apply updates
+  if (updates.name !== undefined) orchestration.name = updates.name;
+  if (updates.description !== undefined) orchestration.description = updates.description;
+  if (updates.status !== undefined) orchestration.status = updates.status;
+  if (updates.startedAt !== undefined) orchestration.startedAt = updates.startedAt;
+  if (updates.completedAt !== undefined) orchestration.completedAt = updates.completedAt;
+  if (updates.metadata !== undefined) {
+    orchestration.metadata = { ...orchestration.metadata, ...updates.metadata };
+  }
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.ORCHESTRATION_UPDATED, {
+      orchestrationId,
+      orchestration,
+      updates,
+      previousStatus
+    });
+
+    // Emit specific status events
+    if (updates.status && updates.status !== previousStatus) {
+      switch (updates.status) {
+        case ORCHESTRATION_STATUS.RUNNING:
+          eventBus.emit(EventTypes.ORCHESTRATION_STARTED, { orchestrationId, orchestration });
+          break;
+        case ORCHESTRATION_STATUS.COMPLETED:
+          eventBus.emit(EventTypes.ORCHESTRATION_COMPLETED, { orchestrationId, orchestration });
+          break;
+        case ORCHESTRATION_STATUS.FAILED:
+          eventBus.emit(EventTypes.ORCHESTRATION_FAILED, { orchestrationId, orchestration });
+          break;
+        case ORCHESTRATION_STATUS.PAUSED:
+          eventBus.emit(EventTypes.ORCHESTRATION_PAUSED, { orchestrationId, orchestration });
+          break;
+      }
+    }
+
+    return { success: true, orchestration };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Delete an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {Object} Result with success flag or error
+ */
+function deleteOrchestration(orchestrationId) {
+  const filePath = getOrchestrationPath(orchestrationId);
+
+  if (!fs.existsSync(filePath)) {
+    return { error: 'Orchestration not found' };
+  }
+
+  try {
+    const orchestration = getOrchestration(orchestrationId);
+    fs.unlinkSync(filePath);
+
+    eventBus.emit(EventTypes.ORCHESTRATION_DELETED, { orchestrationId, orchestration });
+
+    return { success: true };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Add an agent to an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {Object} agentConfig - Agent configuration
+ * @returns {Object} Result with agent or error
+ */
+function addAgent(orchestrationId, agentConfig) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  if (orchestration.status === ORCHESTRATION_STATUS.COMPLETED) {
+    return { error: 'Cannot add agents to a completed orchestration' };
+  }
+
+  const agent = createAgentObject(agentConfig);
+  orchestration.agents.push(agent);
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.AGENT_CREATED, { orchestrationId, agent });
+
+    return { success: true, agent };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Get an agent from an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID
+ * @returns {Object|null} Agent object or null
+ */
+function getAgent(orchestrationId, agentId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return null;
+  }
+
+  return orchestration.agents.find(a => a.id === agentId) || null;
+}
+
+/**
+ * Update an agent within an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID
+ * @param {Object} updates - Updates to apply
+ * @returns {Object} Result with updated agent or error
+ */
+function updateAgent(orchestrationId, agentId, updates) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const agentIndex = orchestration.agents.findIndex(a => a.id === agentId);
+
+  if (agentIndex === -1) {
+    return { error: 'Agent not found' };
+  }
+
+  const agent = orchestration.agents[agentIndex];
+  const previousStatus = agent.status;
+
+  // Apply updates
+  if (updates.name !== undefined) agent.name = updates.name;
+  if (updates.status !== undefined) agent.status = updates.status;
+  if (updates.prompt !== undefined) agent.prompt = updates.prompt;
+  if (updates.sessionId !== undefined) agent.sessionId = updates.sessionId;
+  if (updates.tmuxWindow !== undefined) agent.tmuxWindow = updates.tmuxWindow;
+  if (updates.startedAt !== undefined) agent.startedAt = updates.startedAt;
+  if (updates.completedAt !== undefined) agent.completedAt = updates.completedAt;
+  if (updates.error !== undefined) agent.error = updates.error;
+  if (updates.output !== undefined) agent.output = updates.output;
+  if (updates.toolsUsed !== undefined) agent.toolsUsed = updates.toolsUsed;
+  if (updates.metadata !== undefined) {
+    agent.metadata = { ...agent.metadata, ...updates.metadata };
+  }
+
+  orchestration.agents[agentIndex] = agent;
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.AGENT_STATUS_CHANGED, {
+      orchestrationId,
+      agentId,
+      agent,
+      updates,
+      previousStatus
+    });
+
+    // Emit specific agent events
+    if (updates.status && updates.status !== previousStatus) {
+      switch (updates.status) {
+        case AGENT_STATUS.RUNNING:
+          eventBus.emit(EventTypes.AGENT_SPAWNED, { orchestrationId, agent });
+          break;
+        case AGENT_STATUS.COMPLETED:
+          eventBus.emit(EventTypes.AGENT_COMPLETED, { orchestrationId, agent });
+          break;
+        case AGENT_STATUS.FAILED:
+          eventBus.emit(EventTypes.AGENT_FAILED, { orchestrationId, agent });
+          break;
+        case AGENT_STATUS.CANCELLED:
+          eventBus.emit(EventTypes.AGENT_KILLED, { orchestrationId, agent });
+          break;
+      }
+    }
+
+    return { success: true, agent };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Remove an agent from an orchestration
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID
+ * @returns {Object} Result with success flag or error
+ */
+function removeAgent(orchestrationId, agentId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const agentIndex = orchestration.agents.findIndex(a => a.id === agentId);
+
+  if (agentIndex === -1) {
+    return { error: 'Agent not found' };
+  }
+
+  const agent = orchestration.agents[agentIndex];
+
+  // Check if agent is running - can't remove running agents
+  if (agent.status === AGENT_STATUS.RUNNING || agent.status === AGENT_STATUS.SPAWNING) {
+    return { error: 'Cannot remove a running agent. Kill it first.' };
+  }
+
+  // Remove this agent from dependencies of other agents
+  for (const otherAgent of orchestration.agents) {
+    if (otherAgent.dependencies.includes(agentId)) {
+      otherAgent.dependencies = otherAgent.dependencies.filter(id => id !== agentId);
+    }
+  }
+
+  orchestration.agents.splice(agentIndex, 1);
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.AGENT_KILLED, { orchestrationId, agent, removed: true });
+
+    return { success: true };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Add a dependency between agents
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID (the one that will be blocked)
+ * @param {string} dependsOnAgentId - Agent ID to depend on (the blocker)
+ * @returns {Object} Result with success flag or error
+ */
+function addAgentDependency(orchestrationId, agentId, dependsOnAgentId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const agent = orchestration.agents.find(a => a.id === agentId);
+  const dependsOnAgent = orchestration.agents.find(a => a.id === dependsOnAgentId);
+
+  if (!agent || !dependsOnAgent) {
+    return { error: 'Agent not found' };
+  }
+
+  if (agentId === dependsOnAgentId) {
+    return { error: 'Agent cannot depend on itself' };
+  }
+
+  // Check for circular dependencies
+  if (wouldCreateCycle(orchestration, agentId, dependsOnAgentId)) {
+    return { error: 'This would create a circular dependency' };
+  }
+
+  if (!agent.dependencies.includes(dependsOnAgentId)) {
+    agent.dependencies.push(dependsOnAgentId);
+
+    try {
+      const filePath = getOrchestrationPath(orchestrationId);
+      fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+      eventBus.emit(EventTypes.ORCHESTRATION_UPDATED, {
+        orchestrationId,
+        orchestration,
+        updates: { dependencyAdded: { agentId, dependsOnAgentId } }
+      });
+
+      return { success: true };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  return { success: true }; // Already exists
+}
+
+/**
+ * Remove a dependency between agents
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID
+ * @param {string} dependsOnAgentId - Agent ID to remove from dependencies
+ * @returns {Object} Result with success flag or error
+ */
+function removeAgentDependency(orchestrationId, agentId, dependsOnAgentId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const agent = orchestration.agents.find(a => a.id === agentId);
+
+  if (!agent) {
+    return { error: 'Agent not found' };
+  }
+
+  agent.dependencies = agent.dependencies.filter(id => id !== dependsOnAgentId);
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.ORCHESTRATION_UPDATED, {
+      orchestrationId,
+      orchestration,
+      updates: { dependencyRemoved: { agentId, dependsOnAgentId } }
+    });
+
+    return { success: true };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/**
+ * Check if adding a dependency would create a cycle
+ * @param {Object} orchestration - Orchestration object
+ * @param {string} agentId - Agent that would get the dependency
+ * @param {string} dependsOnAgentId - The dependency to add
+ * @returns {boolean} True if it would create a cycle
+ */
+function wouldCreateCycle(orchestration, agentId, dependsOnAgentId) {
+  const visited = new Set();
+  const stack = [dependsOnAgentId];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+
+    if (current === agentId) {
+      return true; // Found a cycle
+    }
+
+    if (visited.has(current)) {
+      continue;
+    }
+
+    visited.add(current);
+
+    const agent = orchestration.agents.find(a => a.id === current);
+    if (agent) {
+      stack.push(...agent.dependencies);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get agents that are ready to run (no pending dependencies)
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {Array} Array of agents ready to run
+ */
+function getReadyAgents(orchestrationId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return [];
+  }
+
+  return orchestration.agents.filter(agent => {
+    // Only pending agents can be ready
+    if (agent.status !== AGENT_STATUS.PENDING) {
+      return false;
+    }
+
+    // Check all dependencies are completed
+    for (const depId of agent.dependencies) {
+      const depAgent = orchestration.agents.find(a => a.id === depId);
+      if (!depAgent || depAgent.status !== AGENT_STATUS.COMPLETED) {
+        return false;
+      }
+    }
+
+    return true;
+  });
+}
+
+/**
+ * Get orchestration statistics
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {Object} Statistics object
+ */
+function getOrchestrationStats(orchestrationId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return null;
+  }
+
+  const agents = orchestration.agents;
+
+  return {
+    total: agents.length,
+    pending: agents.filter(a => a.status === AGENT_STATUS.PENDING).length,
+    spawning: agents.filter(a => a.status === AGENT_STATUS.SPAWNING).length,
+    running: agents.filter(a => a.status === AGENT_STATUS.RUNNING).length,
+    waiting: agents.filter(a => a.status === AGENT_STATUS.WAITING).length,
+    completed: agents.filter(a => a.status === AGENT_STATUS.COMPLETED).length,
+    failed: agents.filter(a => a.status === AGENT_STATUS.FAILED).length,
+    cancelled: agents.filter(a => a.status === AGENT_STATUS.CANCELLED).length,
+    readyToRun: getReadyAgents(orchestrationId).length
+  };
+}
+
+/**
+ * Check if orchestration is complete (all agents done)
+ * @param {string} orchestrationId - Orchestration ID
+ * @returns {boolean} True if complete
+ */
+function isOrchestrationComplete(orchestrationId) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration || orchestration.agents.length === 0) {
+    return false;
+  }
+
+  const terminalStatuses = [
+    AGENT_STATUS.COMPLETED,
+    AGENT_STATUS.FAILED,
+    AGENT_STATUS.CANCELLED
+  ];
+
+  return orchestration.agents.every(a => terminalStatuses.includes(a.status));
+}
+
+/**
+ * Record tool usage for an agent
+ * @param {string} orchestrationId - Orchestration ID
+ * @param {string} agentId - Agent ID
+ * @param {Object} toolData - Tool usage data
+ * @returns {Object} Result with success flag
+ */
+function recordAgentToolUsage(orchestrationId, agentId, toolData) {
+  const orchestration = getOrchestration(orchestrationId);
+
+  if (!orchestration) {
+    return { error: 'Orchestration not found' };
+  }
+
+  const agent = orchestration.agents.find(a => a.id === agentId);
+
+  if (!agent) {
+    return { error: 'Agent not found' };
+  }
+
+  agent.toolsUsed.push({
+    tool: toolData.tool,
+    timestamp: new Date().toISOString(),
+    duration: toolData.duration || null,
+    status: toolData.status || 'unknown'
+  });
+
+  try {
+    const filePath = getOrchestrationPath(orchestrationId);
+    fs.writeFileSync(filePath, JSON.stringify(orchestration, null, 2));
+
+    eventBus.emit(EventTypes.AGENT_OUTPUT, {
+      orchestrationId,
+      agentId,
+      type: 'tool_use',
+      data: toolData
+    });
+
+    return { success: true };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+module.exports = {
+  // Orchestration CRUD
+  createOrchestration,
+  getOrchestration,
+  listOrchestrations,
+  updateOrchestration,
+  deleteOrchestration,
+
+  // Agent CRUD
+  addAgent,
+  getAgent,
+  updateAgent,
+  removeAgent,
+
+  // Dependencies
+  addAgentDependency,
+  removeAgentDependency,
+  getReadyAgents,
+
+  // Templates
+  getTemplates,
+  getTemplate,
+  createFromTemplate,
+
+  // Utilities
+  getOrchestrationStats,
+  isOrchestrationComplete,
+  recordAgentToolUsage,
+  generateId,
+
+  // Constants re-export for convenience
+  AGENT_STATUS,
+  ORCHESTRATION_STATUS
+};