@od-oneapp/ai-platform 0.1.0

package/src/agents/multi/swarm/coordination.ts

@@ -0,0 +1,380 @@
+/**
+ * Coordination Strategies - Different execution patterns for agent swarms
+ * Based on VERCEL_AI_SDK_V6_PATTERNS.md section 4.4
+ * Provides sequential, parallel, hybrid, and dependency-aware coordination
+ */
+
+import { z } from 'zod';
+
+import type { AgentDefinition, SwarmTask, AgentResult } from './swarm-executor';
+
+/**
+ * Execution phase for hybrid coordination
+ */
+export interface ExecutionPhase {
+  phaseId: string;
+  agents: AgentDefinition[];
+  dependsOn: string[];
+  parallel: boolean;
+}
+
+/**
+ * Dependency graph node
+ */
+export interface DependencyNode {
+  agentId: string;
+  agent: AgentDefinition;
+  dependencies: string[];
+  dependents: string[];
+  level: number;
+}
+
+/**
+ * Sequential execution strategy
+ * Agents run one after another in order
+ * Useful for: Tasks with strict ordering requirements or low parallelism
+ */
+export async function sequentialExecution(
+  agents: AgentDefinition[],
+  task: SwarmTask,
+  executeAgent: (agent: AgentDefinition, task: SwarmTask) => Promise<AgentResult>,
+): Promise<AgentResult[]> {
+  const results: AgentResult[] = [];
+
+  for (const agent of agents) {
+    try {
+      const result = await executeAgent(agent, task);
+      results.push(result);
+    } catch (error) {
+      results.push({
+        agentId: agent.id,
+        agentName: agent.name,
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+        startTime: Date.now(),
+        endTime: Date.now(),
+        duration: 0,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Parallel execution strategy
+ * Agents run concurrently up to maxConcurrency limit
+ * Useful for: Independent tasks that can run simultaneously
+ */
+export async function parallelExecution(
+  agents: AgentDefinition[],
+  task: SwarmTask,
+  executeAgent: (agent: AgentDefinition, task: SwarmTask) => Promise<AgentResult>,
+  maxConcurrency: number = 4,
+): Promise<AgentResult[]> {
+  const results: AgentResult[] = [];
+  const chunks = chunkArray(agents, maxConcurrency);
+
+  for (const chunk of chunks) {
+    const promises = chunk.map(async agent => {
+      try {
+        return await executeAgent(agent, task);
+      } catch (error) {
+        const failureResult: AgentResult = {
+          agentId: agent.id,
+          agentName: agent.name,
+          status: 'failed',
+          error: error instanceof Error ? error.message : 'Unknown error',
+          startTime: Date.now(),
+          endTime: Date.now(),
+          duration: 0,
+        };
+        return failureResult;
+      }
+    });
+
+    const chunkResults = await Promise.all(promises);
+    results.push(...chunkResults);
+  }
+
+  return results;
+}
+
+/**
+ * Hybrid execution strategy
+ * Combines sequential and parallel execution based on dependencies
+ * Agents with no dependencies run in parallel
+ * Agents with dependencies run sequentially after their dependencies
+ * Useful for: Complex workflows with mixed dependency patterns
+ */
+export async function hybridExecution(
+  agents: AgentDefinition[],
+  task: SwarmTask,
+  executeAgent: (agent: AgentDefinition, task: SwarmTask) => Promise<AgentResult>,
+  maxConcurrency: number = 4,
+): Promise<AgentResult[]> {
+  // Build dependency graph
+  const graph = createDependencyGraph(agents);
+  const phases = buildExecutionPhases(graph);
+
+  const results: AgentResult[] = [];
+  const completedAgents = new Set<string>();
+
+  for (const phase of phases) {
+    if (phase.parallel) {
+      // Execute agents in parallel
+      const phaseResults = await parallelExecution(
+        phase.agents,
+        task,
+        executeAgent,
+        maxConcurrency,
+      );
+      results.push(...phaseResults);
+      for (const r of phaseResults) {
+        completedAgents.add(r.agentId);
+      }
+    } else {
+      // Execute agents sequentially
+      const phaseResults = await sequentialExecution(phase.agents, task, executeAgent);
+      results.push(...phaseResults);
+      for (const r of phaseResults) {
+        completedAgents.add(r.agentId);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Create a dependency graph from agents
+ * Analyzes agent dependencies and builds a directed acyclic graph
+ */
+export function createDependencyGraph(agents: AgentDefinition[]): DependencyNode[] {
+  const agentMap = new Map(agents.map(a => [a.id, a]));
+  const nodes: DependencyNode[] = [];
+
+  // First pass: create all nodes and validate dependencies exist
+  for (const agent of agents) {
+    // Validate all dependencies exist
+    for (const depId of agent.dependencies || []) {
+      if (!agentMap.has(depId)) {
+        throw new Error(`Agent "${agent.id}" depends on unknown agent "${depId}"`);
+      }
+    }
+    nodes.push({
+      agentId: agent.id,
+      agent,
+      dependencies: agent.dependencies || [],
+      dependents: [],
+      level: 0,
+    });
+  }
+
+  // Second pass: build relationships
+  for (const node of nodes) {
+    for (const depId of node.dependencies) {
+      const depNode = nodes.find(n => n.agentId === depId);
+      if (depNode) {
+        depNode.dependents.push(node.agentId);
+      }
+    }
+  }
+
+  // Third pass: calculate levels (topological sort)
+  calculateLevels(nodes);
+
+  return nodes;
+}
+
+/**
+ * Build execution phases from dependency graph
+ * Groups agents into phases that can be executed together
+ */
+export function buildExecutionPhases(graph: DependencyNode[]): ExecutionPhase[] {
+  const phases: ExecutionPhase[] = [];
+  const maxLevel = Math.max(...graph.map(n => n.level), 0);
+
+  for (let level = 0; level <= maxLevel; level++) {
+    const agentsAtLevel = graph.filter(n => n.level === level).map(n => n.agent);
+
+    if (agentsAtLevel.length > 0) {
+      phases.push({
+        phaseId: `phase_${level}`,
+        agents: agentsAtLevel,
+        dependsOn: level > 0 ? [`phase_${level - 1}`] : [],
+        parallel: agentsAtLevel.length > 1,
+      });
+    }
+  }
+
+  return phases;
+}
+
+/**
+ * Validate dependency graph for cycles
+ * Returns true if graph is acyclic, false if cycles detected
+ */
+export function validateDependencyGraph(graph: DependencyNode[]): boolean {
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  const hasCycle = (nodeId: string): boolean => {
+    visited.add(nodeId);
+    recursionStack.add(nodeId);
+
+    const node = graph.find(n => n.agentId === nodeId);
+    if (!node) return false;
+
+    for (const depId of node.dependencies) {
+      if (!visited.has(depId)) {
+        if (hasCycle(depId)) return true;
+      } else if (recursionStack.has(depId)) {
+        return true;
+      }
+    }
+
+    recursionStack.delete(nodeId);
+    return false;
+  };
+
+  for (const node of graph) {
+    if (!visited.has(node.agentId)) {
+      if (hasCycle(node.agentId)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Get agents that are ready to execute
+ * Returns agents whose dependencies have all been satisfied
+ */
+export function getReadyAgents(
+  graph: DependencyNode[],
+  completedAgents: Set<string>,
+): DependencyNode[] {
+  return graph.filter(node => {
+    if (completedAgents.has(node.agentId)) {
+      return false;
+    }
+    return node.dependencies.every(depId => completedAgents.has(depId));
+  });
+}
+
+/**
+ * Get all agents that depend on a specific agent
+ */
+export function getDependentAgents(nodeId: string, graph: DependencyNode[]): DependencyNode[] {
+  const node = graph.find(n => n.agentId === nodeId);
+  if (!node) return [];
+
+  return graph.filter(n => node.dependents.includes(n.agentId));
+}
+
+/**
+ * Get all agents that a specific agent depends on
+ */
+export function getDependencies(nodeId: string, graph: DependencyNode[]): DependencyNode[] {
+  const node = graph.find(n => n.agentId === nodeId);
+  if (!node) return [];
+
+  return graph.filter(n => node.dependencies.includes(n.agentId));
+}
+
+/**
+ * Calculate execution order based on dependencies
+ */
+export function calculateExecutionOrder(graph: DependencyNode[]): string[][] {
+  const order: string[][] = [];
+  const visited = new Set<string>();
+
+  const visit = (nodeId: string): void => {
+    if (visited.has(nodeId)) return;
+    visited.add(nodeId);
+
+    const node = graph.find(n => n.agentId === nodeId);
+    if (!node) return;
+
+    for (const depId of node.dependencies) {
+      visit(depId);
+    }
+
+    const { level } = node;
+    if (!order[level]) {
+      order[level] = [];
+    }
+    order[level].push(nodeId);
+  };
+
+  for (const node of graph) {
+    visit(node.agentId);
+  }
+
+  return order.filter(group => group.length > 0);
+}
+
+/**
+ * Helper: Calculate levels in dependency graph (topological sort)
+ */
+function calculateLevels(nodes: DependencyNode[]): void {
+  const visited = new Set<string>();
+
+  const calculateLevel = (nodeId: string): number => {
+    const node = nodes.find(n => n.agentId === nodeId);
+    if (!node) return 0;
+
+    if (visited.has(nodeId)) {
+      return node.level;
+    }
+
+    visited.add(nodeId);
+
+    if (node.dependencies.length === 0) {
+      node.level = 0;
+    } else {
+      const maxDepLevel = Math.max(
+        ...node.dependencies.map(depId => {
+          const depNode = nodes.find(n => n.agentId === depId);
+          if (!depNode) return 0;
+          return calculateLevel(depId);
+        }),
+        0,
+      );
+      node.level = maxDepLevel + 1;
+    }
+
+    return node.level;
+  };
+
+  for (const node of nodes) {
+    calculateLevel(node.agentId);
+  }
+}
+
+/**
+ * Helper: Split array into chunks
+ */
+function chunkArray<T>(array: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+
+/**
+ * Coordination strategy schema for configuration
+ */
+export const CoordinationStrategySchema = z.object({
+  type: z.enum(['sequential', 'parallel', 'hybrid', 'custom']),
+  maxConcurrency: z.number().min(1).default(4),
+  enableDependencyTracking: z.boolean().default(true),
+  allowPartialFailure: z.boolean().default(true),
+  timeoutPerAgent: z.number().min(1000).default(30000),
+});
+
+export type CoordinationStrategy = z.infer<typeof CoordinationStrategySchema>;

package/src/agents/multi/swarm/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Agent swarm coordination with parallel task execution and result aggregation.
+ * @module @od-oneapp/ai-platform/agents/multi/swarm
+ */
+
+// Swarm Executor
+export {
+  createSwarm,
+  executeSwarm,
+  type Swarm,
+  type SwarmConfig,
+  type SwarmResult,
+  type SwarmTask,
+  type SwarmTiming,
+  type CoordinatorStrategy,
+  type AggregationStrategy,
+  type AgentDefinition,
+  type AgentResult,
+  AgentDefinitionSchema,
+  AgentResultSchema,
+  SwarmConfigSchema,
+  SwarmTaskSchema,
+  SwarmResultSchema,
+  SwarmTimingSchema,
+} from './swarm-executor';
+
+// Coordination Strategies
+export {
+  sequentialExecution,
+  parallelExecution,
+  hybridExecution,
+  createDependencyGraph,
+  buildExecutionPhases,
+  validateDependencyGraph,
+  getReadyAgents,
+  getDependentAgents,
+  getDependencies,
+  calculateExecutionOrder,
+  type ExecutionPhase,
+  type DependencyNode,
+  type CoordinationStrategy as CoordinationStrategyConfig,
+  CoordinationStrategySchema,
+} from './coordination';
+
+// Communication System
+export {
+  createMessageBus,
+  broadcastMessage,
+  routeMessage,
+  subscribeToMessages,
+  sendRequest,
+  MessageBuilder,
+  type Message,
+  type MessageBus,
+  type MessageHandler,
+  type MessageSubscription,
+  MessageSchema,
+} from './communication';
+
+// Result Aggregation
+export {
+  aggregateResults,
+  mergeResults,
+  voteOnResults,
+  consensusResult,
+  weightedAggregation,
+  compareStrategies,
+  buildCustomAggregator,
+  type AggregationResult,
+  type CustomAggregator,
+  type AggregationOptions,
+  AggregationResultSchema,
+} from './aggregation';