@defai.digital/agent-parallel 13.4.0

package/src/result-aggregator.ts

@@ -0,0 +1,238 @@
+/**
+ * Result Aggregator
+ *
+ * Combines results from parallel agent execution based on configured strategy.
+ *
+ * Invariants:
+ * - INV-APE-004: Result aggregation follows configured strategy
+ */
+
+import type { AgentParallelTaskResult } from '@defai.digital/contracts';
+import type {
+  ResultAggregator,
+  ResultAggregatorOptions,
+  CustomAggregator,
+  AggregationStrategy,
+} from './types.js';
+
+/**
+ * Deep merge two objects
+ * Later values override earlier values
+ */
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...target };
+
+  for (const [key, value] of Object.entries(source)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      result[key] &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key])
+    ) {
+      // Recursively merge objects
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        value as Record<string, unknown>
+      );
+    } else {
+      // Override with new value
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge strategy: Combine all outputs into single object
+ * INV-APE-004: Later tasks override earlier for same keys
+ */
+function mergeResults(results: AgentParallelTaskResult[]): unknown {
+  const merged: Record<string, unknown> = {};
+
+  // Sort by layer then completion time to ensure deterministic merge order
+  const sortedResults = [...results].sort((a, b) => {
+    // First by layer
+    const layerDiff = (a.layer ?? 0) - (b.layer ?? 0);
+    if (layerDiff !== 0) return layerDiff;
+
+    // Then by completion time
+    const aTime = a.completedAt ? new Date(a.completedAt).getTime() : 0;
+    const bTime = b.completedAt ? new Date(b.completedAt).getTime() : 0;
+    return aTime - bTime;
+  });
+
+  for (const result of sortedResults) {
+    if (result.success && result.output !== undefined) {
+      if (typeof result.output === 'object' && result.output !== null && !Array.isArray(result.output)) {
+        // Deep merge object outputs
+        Object.assign(merged, deepMerge(merged, result.output as Record<string, unknown>));
+      } else {
+        // For non-object outputs, use agent ID as key
+        merged[result.agentId] = result.output;
+      }
+    }
+  }
+
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/**
+ * List strategy: Return array of individual results
+ * INV-APE-004: Ordered by task definition order (taskId)
+ */
+function listResults(results: AgentParallelTaskResult[]): unknown {
+  return results
+    .filter((r) => r.success)
+    .sort((a, b) => a.taskId.localeCompare(b.taskId))
+    .map((r) => ({
+      taskId: r.taskId,
+      agentId: r.agentId,
+      output: r.output,
+      durationMs: r.durationMs,
+    }));
+}
+
+/**
+ * First success strategy: Return first successful result
+ * INV-APE-004: First by layer, then by completion time
+ */
+function firstSuccessResult(results: AgentParallelTaskResult[]): unknown {
+  const successResults = results
+    .filter((r) => r.success && r.output !== undefined)
+    .sort((a, b) => {
+      // First by layer
+      const layerDiff = (a.layer ?? 0) - (b.layer ?? 0);
+      if (layerDiff !== 0) return layerDiff;
+
+      // Then by completion time
+      const aTime = a.completedAt ? new Date(a.completedAt).getTime() : 0;
+      const bTime = b.completedAt ? new Date(b.completedAt).getTime() : 0;
+      return aTime - bTime;
+    });
+
+  return successResults[0]?.output;
+}
+
+/**
+ * Creates a result aggregator
+ */
+export function createResultAggregator(): ResultAggregator {
+  return {
+    /**
+     * Aggregate task results based on strategy
+     * INV-APE-004: Follows configured strategy exactly
+     */
+    aggregate(
+      results: AgentParallelTaskResult[],
+      options: ResultAggregatorOptions
+    ): unknown {
+      const { strategy, customAggregator } = options;
+
+      switch (strategy) {
+        case 'merge':
+          return mergeResults(results);
+
+        case 'list':
+          return listResults(results);
+
+        case 'firstSuccess':
+          return firstSuccessResult(results);
+
+        case 'custom':
+          if (!customAggregator) {
+            throw new Error(
+              'Custom aggregation strategy requires a customAggregator function'
+            );
+          }
+          return customAggregator(results);
+
+        default:
+          // Exhaustive check
+          const _exhaustive: never = strategy;
+          throw new Error(`Unknown aggregation strategy: ${_exhaustive}`);
+      }
+    },
+  };
+}
+
+/**
+ * Built-in aggregation strategies for convenience
+ */
+export const AggregationStrategies = {
+  /**
+   * Merge all successful outputs into single object
+   */
+  merge: mergeResults,
+
+  /**
+   * Return array of all successful results
+   */
+  list: listResults,
+
+  /**
+   * Return first successful result only
+   */
+  firstSuccess: firstSuccessResult,
+
+  /**
+   * Create custom strategy from function
+   */
+  custom: (fn: CustomAggregator) => fn,
+} as const;
+
+/**
+ * Utility: Create a keyed aggregator that groups results by a key
+ */
+export function createKeyedAggregator(
+  keyFn: (result: AgentParallelTaskResult) => string
+): CustomAggregator {
+  return (results: AgentParallelTaskResult[]) => {
+    const grouped: Record<string, unknown[]> = {};
+
+    for (const result of results) {
+      if (result.success && result.output !== undefined) {
+        const key = keyFn(result);
+        if (!grouped[key]) {
+          grouped[key] = [];
+        }
+        grouped[key].push(result.output);
+      }
+    }
+
+    return grouped;
+  };
+}
+
+/**
+ * Utility: Create aggregator that filters by success and transforms
+ */
+export function createTransformAggregator<T>(
+  transform: (output: unknown, result: AgentParallelTaskResult) => T
+): CustomAggregator {
+  return (results: AgentParallelTaskResult[]) => {
+    return results
+      .filter((r) => r.success && r.output !== undefined)
+      .map((r) => transform(r.output, r));
+  };
+}
+
+/**
+ * Get aggregation strategy from string
+ */
+export function getAggregationStrategy(
+  name: string
+): AggregationStrategy {
+  const valid: AggregationStrategy[] = ['merge', 'list', 'firstSuccess', 'custom'];
+  if (valid.includes(name as AggregationStrategy)) {
+    return name as AggregationStrategy;
+  }
+  throw new Error(
+    `Invalid aggregation strategy: ${name}. Valid strategies: ${valid.join(', ')}`
+  );
+}

package/src/types.ts

@@ -0,0 +1,320 @@
+/**
+ * Parallel Agent Execution Types
+ *
+ * Port interfaces and type definitions for parallel agent execution.
+ */
+
+import type {
+  AgentParallelTask,
+  AgentParallelTaskResult,
+  AgentParallelGroupResult,
+  AgentParallelExecutionConfig,
+  ExecutionPlan,
+  SharedContext,
+} from '@defai.digital/contracts';
+
+// ============================================================================
+// Agent Executor Port
+// ============================================================================
+
+/**
+ * Agent execution request
+ */
+export interface AgentExecuteRequest {
+  agentId: string;
+  input: unknown;
+  provider?: string;
+  model?: string;
+  timeout?: number;
+  sessionId?: string;
+}
+
+/**
+ * Agent execution result
+ */
+export interface AgentExecuteResult {
+  success: boolean;
+  agentId: string;
+  output?: unknown;
+  error?: string;
+  errorCode?: string;
+  durationMs: number;
+}
+
+/**
+ * Port interface for agent execution
+ * Implementations inject actual agent executor at runtime
+ */
+export interface AgentExecutorPort {
+  /**
+   * Execute a single agent with input
+   */
+  execute(request: AgentExecuteRequest): Promise<AgentExecuteResult>;
+
+  /**
+   * Check if an agent exists
+   */
+  exists(agentId: string): Promise<boolean>;
+}
+
+// ============================================================================
+// Parallel Orchestrator Interface
+// ============================================================================
+
+/**
+ * Parallel agent orchestrator interface
+ */
+export interface AgentParallelOrchestrator {
+  /**
+   * Execute multiple agents in parallel with DAG-based dependency management
+   * INV-APE-001: Respects maxConcurrentAgents
+   * INV-APE-002: Honors dependencies
+   * INV-APE-003: Shared context immutable
+   */
+  executeParallel(
+    tasks: AgentParallelTask[],
+    config?: Partial<AgentParallelExecutionConfig>,
+    sharedContext?: Record<string, unknown>
+  ): Promise<AgentParallelGroupResult>;
+
+  /**
+   * Build execution plan without executing
+   * Returns DAG analysis showing execution layers
+   */
+  buildExecutionPlan(tasks: AgentParallelTask[]): ExecutionPlan;
+
+  /**
+   * Cancel ongoing execution
+   */
+  cancel(): void;
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): AgentParallelExecutionConfig;
+}
+
+// ============================================================================
+// DAG Analyzer Interface
+// ============================================================================
+
+/**
+ * Execution layer - tasks at same level can run in parallel
+ */
+export interface TaskLayer {
+  index: number;
+  tasks: AgentParallelTask[];
+}
+
+/**
+ * DAG analysis result
+ */
+export interface DAGAnalysisResult {
+  layers: TaskLayer[];
+  totalLayers: number;
+  maxParallelism: number;
+  hasCycles: boolean;
+  cycleNodes?: string[];
+}
+
+/**
+ * DAG analyzer interface
+ */
+export interface DAGAnalyzer {
+  /**
+   * Analyze tasks and build execution layers
+   * INV-APE-002: Ensures dependencies honored
+   * INV-APE-200: Detects circular dependencies
+   */
+  analyze(tasks: AgentParallelTask[]): DAGAnalysisResult;
+
+  /**
+   * Validate DAG structure
+   */
+  validate(tasks: AgentParallelTask[]): { valid: boolean; errors: string[] };
+}
+
+// ============================================================================
+// Context Manager Interface
+// ============================================================================
+
+/**
+ * Context manager for shared immutable context
+ * INV-APE-003: Context immutable during execution
+ */
+export interface ContextManager {
+  /**
+   * Create frozen shared context
+   */
+  create(data: Record<string, unknown>): SharedContext;
+
+  /**
+   * Get read-only view of context
+   */
+  get(): SharedContext | null;
+
+  /**
+   * Check if context is frozen/immutable
+   */
+  isFrozen(): boolean;
+
+  /**
+   * Clear context (for cleanup)
+   */
+  clear(): void;
+}
+
+// ============================================================================
+// Result Aggregator Interface
+// ============================================================================
+
+/**
+ * Result aggregation strategy
+ */
+export type AggregationStrategy = 'merge' | 'list' | 'firstSuccess' | 'custom';
+
+/**
+ * Custom aggregation function
+ */
+export type CustomAggregator = (
+  results: AgentParallelTaskResult[]
+) => unknown;
+
+/**
+ * Result aggregator options
+ */
+export interface ResultAggregatorOptions {
+  strategy: AggregationStrategy;
+  customAggregator?: CustomAggregator;
+}
+
+/**
+ * Result aggregator interface
+ * INV-APE-004: Aggregation follows configured strategy
+ */
+export interface ResultAggregator {
+  /**
+   * Aggregate task results based on strategy
+   */
+  aggregate(
+    results: AgentParallelTaskResult[],
+    options: ResultAggregatorOptions
+  ): unknown;
+}
+
+// ============================================================================
+// Progress Tracking
+// ============================================================================
+
+/**
+ * Progress event types
+ */
+export type ParallelProgressEventType =
+  | 'execution.started'
+  | 'layer.started'
+  | 'layer.completed'
+  | 'task.started'
+  | 'task.completed'
+  | 'task.failed'
+  | 'task.skipped'
+  | 'execution.completed'
+  | 'execution.cancelled';
+
+/**
+ * Progress event
+ */
+export interface ParallelProgressEvent {
+  type: ParallelProgressEventType;
+  timestamp: string;
+  groupId: string;
+  layerIndex?: number;
+  taskId?: string;
+  agentId?: string;
+  totalTasks?: number;
+  completedTasks?: number;
+  failedTasks?: number;
+  message?: string;
+}
+
+/**
+ * Progress callback
+ */
+export type ParallelProgressCallback = (event: ParallelProgressEvent) => void;
+
+// ============================================================================
+// Orchestrator Options
+// ============================================================================
+
+/**
+ * Options for creating parallel orchestrator
+ */
+export interface AgentParallelOrchestratorOptions {
+  /**
+   * Agent executor port (for dependency injection)
+   */
+  agentExecutor: AgentExecutorPort;
+
+  /**
+   * Default configuration
+   */
+  defaultConfig?: Partial<AgentParallelExecutionConfig>;
+
+  /**
+   * Progress callback for execution updates
+   */
+  onProgress?: ParallelProgressCallback;
+}
+
+// ============================================================================
+// Stub Implementation (for testing)
+// ============================================================================
+
+/**
+ * Stub agent executor for testing
+ */
+export class StubAgentExecutor implements AgentExecutorPort {
+  private results: Map<string, AgentExecuteResult> = new Map();
+  private existingAgents: Set<string> = new Set();
+
+  /**
+   * Set expected result for an agent
+   */
+  setResult(agentId: string, result: Partial<AgentExecuteResult>): void {
+    this.results.set(agentId, {
+      success: true,
+      agentId,
+      durationMs: 100,
+      ...result,
+    });
+  }
+
+  /**
+   * Set agent as existing
+   */
+  setExists(agentId: string, exists: boolean): void {
+    if (exists) {
+      this.existingAgents.add(agentId);
+    } else {
+      this.existingAgents.delete(agentId);
+    }
+  }
+
+  async execute(request: AgentExecuteRequest): Promise<AgentExecuteResult> {
+    const result = this.results.get(request.agentId);
+    if (result) {
+      return result;
+    }
+
+    // Default: return success with echo output
+    return {
+      success: true,
+      agentId: request.agentId,
+      output: { input: request.input, echo: true },
+      durationMs: 50,
+    };
+  }
+
+  async exists(agentId: string): Promise<boolean> {
+    return this.existingAgents.has(agentId) || this.results.has(agentId);
+  }
+}