@od-oneapp/ai-platform 0.1.0

package/src/agents/multi/swarm/swarm-executor.ts

@@ -0,0 +1,479 @@
+/**
+ * Swarm Executor - Core agent swarm coordination
+ * Based on VERCEL_AI_SDK_V6_PATTERNS.md section 4.4
+ * Orchestrates multiple agents working in parallel with various coordination strategies
+ */
+
+import { logInfo } from '@repo/shared/logs';
+import { z } from 'zod';
+
+/**
+ * Agent definition schema
+ * Describes an individual agent in the swarm
+ */
+export const AgentDefinitionSchema = z.object({
+  id: z.string().describe('Unique identifier for the agent'),
+  name: z.string().describe('Human-readable agent name'),
+  role: z.string().describe('Role/responsibility of the agent'),
+  description: z.string().describe('What this agent does'),
+  dependencies: z.array(z.string()).default([]).describe('IDs of agents this one depends on'),
+  config: z.record(z.string(), z.unknown()).optional().describe('Agent-specific configuration'),
+});
+
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+
+/**
+ * Agent result from execution
+ */
+export const AgentResultSchema = z.object({
+  agentId: z.string(),
+  agentName: z.string(),
+  status: z.enum(['success', 'failed', 'timeout', 'skipped']),
+  result: z.unknown().optional(),
+  error: z.string().optional(),
+  startTime: z.number(),
+  endTime: z.number(),
+  duration: z.number(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type AgentResult = z.infer<typeof AgentResultSchema>;
+
+/**
+ * Coordinator strategy types
+ */
+export type CoordinatorStrategy = 'sequential' | 'parallel' | 'hybrid' | 'custom';
+
+/**
+ * Swarm timing information
+ */
+export const SwarmTimingSchema = z.object({
+  startTime: z.number(),
+  endTime: z.number(),
+  totalDuration: z.number(),
+  parallelDuration: z.number(),
+  sequentialDuration: z.number(),
+  agentTimings: z.record(z.string(), z.number()),
+});
+
+export type SwarmTiming = z.infer<typeof SwarmTimingSchema>;
+
+/**
+ * Aggregation strategy type
+ */
+export type AggregationStrategy = 'merge' | 'vote' | 'consensus' | 'weighted' | 'custom';
+
+/**
+ * Swarm configuration
+ */
+export const SwarmConfigSchema = z.object({
+  agents: z.array(AgentDefinitionSchema),
+  coordinator: z.enum(['sequential', 'parallel', 'hybrid', 'custom']),
+  maxConcurrency: z.number().min(1).default(4),
+  timeout: z.number().min(1000).default(30000),
+  aggregation: z.enum(['merge', 'vote', 'consensus', 'weighted', 'custom']).default('merge'),
+  enableLogging: z.boolean().default(false),
+  retryPolicy: z
+    .object({
+      maxRetries: z.number().min(0).default(0),
+      retryDelay: z.number().min(0).default(1000),
+      retryableErrors: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type SwarmConfig = z.infer<typeof SwarmConfigSchema>;
+
+/**
+ * Swarm task definition
+ */
+export const SwarmTaskSchema = z.object({
+  taskId: z.string(),
+  description: z.string(),
+  params: z.record(z.string(), z.unknown()).optional(),
+  targetAgents: z.array(z.string()).optional().describe('Specific agents to run; empty = all'),
+  context: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('Shared context passed to all agents'),
+});
+
+export type SwarmTask = z.infer<typeof SwarmTaskSchema>;
+
+/**
+ * Swarm execution result
+ */
+export const SwarmResultSchema = z.object({
+  taskId: z.string(),
+  results: z.record(z.string(), AgentResultSchema),
+  aggregated: z.unknown().optional(),
+  timing: SwarmTimingSchema,
+  status: z.enum(['completed', 'partial', 'failed']),
+  error: z.string().optional(),
+});
+
+export type SwarmResult = z.infer<typeof SwarmResultSchema>;
+
+/**
+ * Swarm executor interface
+ */
+export interface Swarm {
+  execute(task: SwarmTask): Promise<SwarmResult>;
+  getAgent(agentId: string): AgentDefinition | undefined;
+  getAgents(): AgentDefinition[];
+  getConfig(): SwarmConfig;
+}
+
+/**
+ * Factory function to create a swarm executor
+ */
+export function createSwarm(config: SwarmConfig): Swarm {
+  return new SwarmExecutor(config);
+}
+
+/**
+ * Main swarm executor implementation
+ */
+class SwarmExecutor implements Swarm {
+  private config: SwarmConfig;
+  private agentMap: Map<string, AgentDefinition>;
+
+  constructor(config: SwarmConfig) {
+    this.config = config;
+    this.agentMap = new Map(config.agents.map(agent => [agent.id, agent]));
+  }
+
+  async execute(task: SwarmTask): Promise<SwarmResult> {
+    const startTime = Date.now();
+    const results = new Map<string, AgentResult>();
+
+    if (this.config.enableLogging) {
+      logInfo(`[Swarm] Starting execution of task: ${task.taskId}`);
+      logInfo(`[Swarm] Coordination strategy: ${this.config.coordinator}`);
+    }
+
+    try {
+      // Determine which agents to run
+      const targetAgents = task.targetAgents ?? [];
+      const agentsToRun =
+        targetAgents.length > 0
+          ? this.config.agents.filter(a => targetAgents.includes(a.id))
+          : this.config.agents;
+
+      if (this.config.enableLogging) {
+        logInfo(`[Swarm] Running ${agentsToRun.length} agents`);
+      }
+
+      // Execute based on coordination strategy
+      let parallelDuration = 0;
+      let sequentialDuration = 0;
+
+      switch (this.config.coordinator) {
+        case 'sequential':
+          sequentialDuration = await this.executeSequential(agentsToRun, task, results);
+          break;
+        case 'parallel':
+          parallelDuration = await this.executeParallel(agentsToRun, task, results);
+          break;
+        case 'hybrid': {
+          const { parallel, sequential } = await this.executeHybrid(agentsToRun, task, results);
+          parallelDuration = parallel;
+          sequentialDuration = sequential;
+          break;
+        }
+        case 'custom':
+          // Custom coordinators would be implemented via inheritance/composition
+          await this.executeParallel(agentsToRun, task, results);
+          break;
+      }
+
+      const endTime = Date.now();
+      const totalDuration = endTime - startTime;
+
+      // Aggregate results
+      const aggregated = await this.aggregateResults(Array.from(results.values()));
+
+      const timing: SwarmTiming = {
+        startTime,
+        endTime,
+        totalDuration,
+        parallelDuration,
+        sequentialDuration,
+        agentTimings: this.extractAgentTimings(results),
+      };
+
+      const status = Array.from(results.values()).every(r => r.status === 'success')
+        ? 'completed'
+        : Array.from(results.values()).some(r => r.status === 'success')
+          ? 'partial'
+          : 'failed';
+
+      if (this.config.enableLogging) {
+        logInfo(`[Swarm] Task ${task.taskId} completed with status: ${status}`);
+        logInfo(`[Swarm] Total duration: ${totalDuration}ms`);
+      }
+
+      return {
+        taskId: task.taskId,
+        results: Object.fromEntries(results),
+        aggregated,
+        timing,
+        status,
+      };
+    } catch (error) {
+      const endTime = Date.now();
+      const totalDuration = endTime - startTime;
+
+      return {
+        taskId: task.taskId,
+        results: Object.fromEntries(results),
+        timing: {
+          startTime,
+          endTime,
+          totalDuration,
+          parallelDuration: 0,
+          sequentialDuration: totalDuration,
+          agentTimings: this.extractAgentTimings(results),
+        },
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  private async executeSequential(
+    agents: AgentDefinition[],
+    task: SwarmTask,
+    results: Map<string, AgentResult>,
+  ): Promise<number> {
+    const startTime = Date.now();
+
+    for (const agent of agents) {
+      try {
+        const result = await this.executeAgent(agent, task);
+        results.set(agent.id, result);
+      } catch (error) {
+        results.set(agent.id, {
+          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 Date.now() - startTime;
+  }
+
+  private async executeParallel(
+    agents: AgentDefinition[],
+    task: SwarmTask,
+    results: Map<string, AgentResult>,
+  ): Promise<number> {
+    const startTime = Date.now();
+    const chunks = this.chunkArray(agents, this.config.maxConcurrency);
+
+    for (const chunk of chunks) {
+      const promises = chunk.map(async agent => {
+        try {
+          const result = await this.executeAgent(agent, task);
+          results.set(agent.id, result);
+        } catch (error) {
+          results.set(agent.id, {
+            agentId: agent.id,
+            agentName: agent.name,
+            status: 'failed',
+            error: error instanceof Error ? error.message : 'Unknown error',
+            startTime: Date.now(),
+            endTime: Date.now(),
+            duration: 0,
+          });
+        }
+      });
+
+      await Promise.all(promises);
+    }
+
+    return Date.now() - startTime;
+  }
+
+  private async executeHybrid(
+    agents: AgentDefinition[],
+    task: SwarmTask,
+    results: Map<string, AgentResult>,
+  ): Promise<{ parallel: number; sequential: number }> {
+    const parallelAgents = agents.filter(a => !a.dependencies || a.dependencies.length === 0);
+    const parallelDuration = await this.executeParallel(parallelAgents, task, results);
+
+    const dependentAgents = agents.filter(a => a.dependencies && a.dependencies.length > 0);
+    const sequentialDuration = await this.executeSequential(dependentAgents, task, results);
+
+    return {
+      parallel: parallelDuration,
+      sequential: sequentialDuration,
+    };
+  }
+
+  private async executeAgent(agent: AgentDefinition, task: SwarmTask): Promise<AgentResult> {
+    const startTime = Date.now();
+    const timeoutMs = this.config.timeout;
+
+    try {
+      // Execute with proactive timeout enforcement
+      const executionPromise = this.simulateAgentExecution(agent, task);
+      const timeoutPromise = new Promise<never>((resolve, reject) => {
+        void resolve;
+        setTimeout(() => reject(new Error('AGENT_TIMEOUT')), timeoutMs);
+      });
+
+      await Promise.race([executionPromise, timeoutPromise]);
+
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      return {
+        agentId: agent.id,
+        agentName: agent.name,
+        status: 'success',
+        result: {
+          processedAt: new Date().toISOString(),
+          role: agent.role,
+          taskId: task.taskId,
+        },
+        startTime,
+        endTime,
+        duration,
+      };
+    } catch (error) {
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      if (error instanceof Error && error.message === 'AGENT_TIMEOUT') {
+        return {
+          agentId: agent.id,
+          agentName: agent.name,
+          status: 'timeout',
+          error: `Agent execution exceeded timeout of ${timeoutMs}ms`,
+          startTime,
+          endTime,
+          duration,
+        };
+      }
+
+      return {
+        agentId: agent.id,
+        agentName: agent.name,
+        status: 'failed',
+        error: error instanceof Error ? error.message : 'Unknown error',
+        startTime,
+        endTime,
+        duration,
+      };
+    }
+  }
+
+  private async simulateAgentExecution(agent: AgentDefinition, task: SwarmTask): Promise<void> {
+    void agent;
+    void task;
+    // Simulate execution with random delay
+    const delay = Math.random() * 100 + 50;
+    await new Promise(resolve => setTimeout(resolve, delay));
+  }
+
+  private async aggregateResults(results: AgentResult[]): Promise<unknown> {
+    switch (this.config.aggregation) {
+      case 'merge':
+        return this.mergeResults(results);
+      case 'vote':
+        return this.voteOnResults(results);
+      case 'consensus':
+        return this.consensusResults(results);
+      case 'weighted':
+        return this.mergeResults(results);
+      case 'custom':
+        return this.mergeResults(results);
+      default:
+        return this.mergeResults(results);
+    }
+  }
+
+  private mergeResults(results: AgentResult[]): unknown {
+    return {
+      totalAgents: results.length,
+      successfulAgents: results.filter(r => r.status === 'success').length,
+      failedAgents: results.filter(r => r.status === 'failed').length,
+      agentResults: results.map(r => ({
+        agentId: r.agentId,
+        status: r.status,
+        duration: r.duration,
+      })),
+    };
+  }
+
+  private voteOnResults(results: AgentResult[]): unknown {
+    const successCount = results.filter(r => r.status === 'success').length;
+    const failureCount = results.filter(r => r.status === 'failed').length;
+
+    return {
+      consensus: successCount > failureCount ? 'success' : 'failure',
+      successVotes: successCount,
+      failureVotes: failureCount,
+      totalVotes: results.length,
+    };
+  }
+
+  private consensusResults(results: AgentResult[]): unknown {
+    const totalResults = results.length;
+    const successfulResults = results.filter(r => r.status === 'success').length;
+    const confidenceScore = totalResults > 0 ? successfulResults / totalResults : 0;
+
+    return {
+      consensus: confidenceScore >= 0.5,
+      confidenceScore: Math.round(confidenceScore * 100) / 100,
+      successfulResults,
+      totalResults,
+      details: results.map(r => ({
+        agentId: r.agentId,
+        status: r.status,
+      })),
+    };
+  }
+
+  private extractAgentTimings(results: Map<string, AgentResult>): Record<string, number> {
+    const timings: Record<string, number> = {};
+    results.forEach((result, agentId) => {
+      timings[agentId] = result.duration;
+    });
+    return timings;
+  }
+
+  private 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;
+  }
+
+  getAgent(agentId: string): AgentDefinition | undefined {
+    return this.agentMap.get(agentId);
+  }
+
+  getAgents(): AgentDefinition[] {
+    return this.config.agents;
+  }
+
+  getConfig(): SwarmConfig {
+    return this.config;
+  }
+}
+
+/**
+ * Execute a swarm with a given task
+ */
+export async function executeSwarm(swarm: Swarm, task: SwarmTask): Promise<SwarmResult> {
+  return swarm.execute(task);
+}

package/src/agents/multi/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Multi-agent coordination types
+ */
+
+import { z } from 'zod';
+
+/**
+ * Agent message schema for runtime validation
+ */
+export const AgentMessageSchema = z.object({
+  /** Unique message ID */
+  id: z.string().min(1),
+  /** Sender agent ID */
+  from: z.string().min(1),
+  /** Recipient agent ID(s) */
+  to: z.union([z.string().min(1), z.array(z.string().min(1))]),
+  /** Message type */
+  type: z.enum(['request', 'response', 'event', 'command']),
+  /** Message payload */
+  payload: z.unknown(),
+  /** Correlation ID for request/response matching */
+  correlationId: z.string().optional(),
+  /** Message timestamp (ISO 8601 string for serialization safety) */
+  timestamp: z.string(),
+  /** Time-to-live in milliseconds */
+  ttl: z.number().positive().optional(),
+});
+
+/**
+ * Agent message for inter-agent communication
+ */
+export type AgentMessage<T = unknown> = Omit<z.infer<typeof AgentMessageSchema>, 'payload'> & {
+  payload: T;
+};
+
+/**
+ * Message handler function
+ */
+export type MessageHandler = (message: AgentMessage) => Promise<void>;
+
+/**
+ * Unsubscribe function
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Message bus interface for agent communication
+ */
+export interface MessageBus {
+  /** Send a message to a specific agent */
+  send(message: AgentMessage): Promise<void>;
+  /** Broadcast a message to all subscribers of a topic */
+  broadcast(topic: string, message: AgentMessage): Promise<void>;
+  /** Subscribe to messages for an agent */
+  subscribe(agentId: string, handler: MessageHandler): Unsubscribe;
+  /** Send a request and wait for response */
+  request<T, R>(from: string, to: string, payload: T, timeout?: number): Promise<R>;
+}
+
+/**
+ * Agent interface
+ */
+export interface Agent {
+  /** Unique agent ID */
+  id: string;
+  /** Start the agent */
+  start(): Promise<void>;
+  /** Stop the agent */
+  stop(): Promise<void>;
+  /** Handle an incoming message */
+  handleMessage(message: AgentMessage): Promise<AgentMessage | void>;
+}
+
+/**
+ * Supervision strategy (Erlang-inspired)
+ */
+export type SupervisionStrategy = 'one-for-one' | 'one-for-all' | 'rest-for-one';
+
+/**
+ * Agent specification for supervisor
+ */
+export interface AgentSpec {
+  /** Unique agent ID */
+  id: string;
+  /** Factory function to create agent */
+  factory: () => Agent;
+  /** Restart strategy */
+  restart: 'permanent' | 'transient' | 'temporary';
+}
+
+/**
+ * Supervisor configuration
+ */
+export interface SupervisorConfig {
+  /** Supervision strategy */
+  strategy: SupervisionStrategy;
+  /** Maximum restarts allowed */
+  maxRestarts: number;
+  /** Time window for restart counting (ms) */
+  withinMs: number;
+  /** Child agent specifications */
+  children: AgentSpec[];
+}
+
+/**
+ * Swarm task schema for runtime validation
+ */
+export const SwarmTaskSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().min(1),
+  payload: z.unknown(),
+  priority: z.number().int().min(0).optional(),
+  timeout: z.number().positive().optional(),
+});
+
+/**
+ * Swarm task for distributed processing
+ */
+export type SwarmTask<T = unknown> = Omit<z.infer<typeof SwarmTaskSchema>, 'payload'> & {
+  payload: T;
+};
+
+/**
+ * Task error schema for runtime validation
+ */
+export const TaskErrorSchema = z.object({
+  message: z.string(),
+  name: z.string(),
+  stack: z.string().optional(),
+  code: z.string().optional(),
+});
+
+/**
+ * Serializable error information
+ */
+export type TaskError = z.infer<typeof TaskErrorSchema>;
+
+/**
+ * Swarm task result schema for runtime validation
+ */
+export const SwarmTaskResultSchema = z.object({
+  taskId: z.string().min(1),
+  agentId: z.string().min(1),
+  result: z.unknown(),
+  duration: z.number().nonnegative(),
+  error: TaskErrorSchema.optional(),
+});
+
+/**
+ * Swarm task result
+ */
+export type SwarmTaskResult<T = unknown> = Omit<z.infer<typeof SwarmTaskResultSchema>, 'result'> & {
+  result: T;
+};
+
+/**
+ * Validate an agent message at runtime
+ */
+export function validateAgentMessage(message: unknown): AgentMessage {
+  return AgentMessageSchema.parse(message);
+}
+
+/**
+ * Validate a swarm task at runtime
+ */
+export function validateSwarmTask(task: unknown): SwarmTask {
+  return SwarmTaskSchema.parse(task);
+}
+
+/**
+ * Safely validate an agent message (returns result object instead of throwing)
+ */
+export function safeValidateAgentMessage(
+  message: unknown,
+): { success: true; data: AgentMessage } | { success: false; error: z.ZodError } {
+  const result = AgentMessageSchema.safeParse(message);
+  if (result.success) {
+    return { success: true, data: result.data as AgentMessage };
+  }
+  return { success: false, error: result.error };
+}