@sparkleideas/swarm 3.0.0-alpha.7

package/src/shared/events.ts

@@ -0,0 +1,285 @@
+/**
+ * @sparkleideas/swarm - Standalone Event System
+ * Event-driven communication for multi-agent swarm coordination
+ *
+ * This file provides a complete event system for standalone operation
+ * without dependency on @sparkleideas/shared
+ */
+
+import type { SwarmEvent, EventType, EventHandler, AgentId } from './types.js';
+
+// =============================================================================
+// Event Bus Interface
+// =============================================================================
+
+export interface IEventBus {
+  subscribe<T>(eventType: EventType, handler: EventHandler<T>): () => void;
+  subscribeAll(handler: EventHandler): () => void;
+  emit<T>(event: SwarmEvent<T>): Promise<void>;
+  emitSync<T>(event: SwarmEvent<T>): void;
+  getHistory(filter?: EventFilter): SwarmEvent[];
+  clear(): void;
+}
+
+export interface EventFilter {
+  types?: EventType[];
+  sources?: (AgentId | 'swarm')[];
+  since?: number;
+  until?: number;
+  limit?: number;
+}
+
+// =============================================================================
+// Event Bus Implementation
+// =============================================================================
+
+export class EventBus implements IEventBus {
+  private handlers: Map<EventType | '*', Set<EventHandler>> = new Map();
+  private history: SwarmEvent[] = [];
+  private maxHistorySize: number;
+
+  constructor(options: { maxHistorySize?: number } = {}) {
+    this.maxHistorySize = options.maxHistorySize ?? 10000;
+  }
+
+  subscribe<T>(eventType: EventType, handler: EventHandler<T>): () => void {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+    }
+
+    const handlers = this.handlers.get(eventType)!;
+    handlers.add(handler as EventHandler);
+
+    return () => {
+      handlers.delete(handler as EventHandler);
+    };
+  }
+
+  subscribeAll(handler: EventHandler): () => void {
+    if (!this.handlers.has('*')) {
+      this.handlers.set('*', new Set());
+    }
+
+    const handlers = this.handlers.get('*')!;
+    handlers.add(handler);
+
+    return () => {
+      handlers.delete(handler);
+    };
+  }
+
+  async emit<T>(event: SwarmEvent<T>): Promise<void> {
+    this.addToHistory(event);
+
+    const typeHandlers = this.handlers.get(event.type) ?? new Set();
+    const allHandlers = this.handlers.get('*') ?? new Set();
+
+    const allPromises: Promise<void>[] = [];
+
+    for (const handler of typeHandlers) {
+      allPromises.push(this.safeExecute(handler, event));
+    }
+
+    for (const handler of allHandlers) {
+      allPromises.push(this.safeExecute(handler, event));
+    }
+
+    await Promise.all(allPromises);
+  }
+
+  emitSync<T>(event: SwarmEvent<T>): void {
+    this.addToHistory(event);
+
+    const typeHandlers = this.handlers.get(event.type) ?? new Set();
+    const allHandlers = this.handlers.get('*') ?? new Set();
+
+    for (const handler of typeHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch(err => console.error(`Event handler error: ${err}`));
+        }
+      } catch (err) {
+        console.error(`Event handler error: ${err}`);
+      }
+    }
+
+    for (const handler of allHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch(err => console.error(`Event handler error: ${err}`));
+        }
+      } catch (err) {
+        console.error(`Event handler error: ${err}`);
+      }
+    }
+  }
+
+  getHistory(filter?: EventFilter): SwarmEvent[] {
+    let events = [...this.history];
+
+    if (filter?.types?.length) {
+      events = events.filter(e => filter.types!.includes(e.type));
+    }
+
+    if (filter?.sources?.length) {
+      events = events.filter(e => filter.sources!.includes(e.source));
+    }
+
+    if (filter?.since) {
+      events = events.filter(e => e.timestamp >= filter.since!);
+    }
+
+    if (filter?.until) {
+      events = events.filter(e => e.timestamp <= filter.until!);
+    }
+
+    if (filter?.limit) {
+      events = events.slice(-filter.limit);
+    }
+
+    return events;
+  }
+
+  clear(): void {
+    this.history = [];
+  }
+
+  private addToHistory(event: SwarmEvent): void {
+    this.history.push(event);
+
+    if (this.history.length > this.maxHistorySize) {
+      this.history = this.history.slice(-Math.floor(this.maxHistorySize / 2));
+    }
+  }
+
+  private async safeExecute(handler: EventHandler, event: SwarmEvent): Promise<void> {
+    try {
+      await handler(event);
+    } catch (err) {
+      console.error(`Event handler error for ${event.type}: ${err}`);
+    }
+  }
+}
+
+// =============================================================================
+// Event Factory Functions
+// =============================================================================
+
+let eventCounter = 0;
+
+export function createEvent<T>(
+  type: EventType,
+  source: AgentId | 'swarm',
+  payload: T
+): SwarmEvent<T> {
+  return {
+    id: `evt-${Date.now()}-${++eventCounter}`,
+    type,
+    timestamp: Date.now(),
+    source,
+    payload
+  };
+}
+
+// Helper function to generate event IDs
+function generateEventId(): string {
+  return `evt-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+// Helper function to create a base SwarmEvent
+function createSwarmEvent<T>(
+  type: EventType,
+  source: string,
+  payload: T
+): SwarmEvent<T> {
+  return {
+    id: generateEventId(),
+    type,
+    timestamp: Date.now(),
+    source,
+    payload,
+  };
+}
+
+// Agent events
+export function agentSpawnedEvent(agentId: string, state: unknown): SwarmEvent<{ agentId: string; state: unknown }> {
+  return createSwarmEvent('agent:spawned', agentId, { agentId, state });
+}
+
+export function agentStatusChangedEvent(
+  agentId: AgentId,
+  previousStatus: string,
+  newStatus: string
+): SwarmEvent {
+  return createEvent('agent:status-changed', agentId, { previousStatus, newStatus });
+}
+
+export function agentTaskAssignedEvent(agentId: AgentId, taskId: string): SwarmEvent {
+  return createEvent('agent:task-assigned', 'swarm', { agentId, taskId });
+}
+
+export function agentTaskCompletedEvent(agentId: AgentId, taskId: string, result: unknown): SwarmEvent {
+  return createEvent('agent:task-completed', agentId, { taskId, result });
+}
+
+export function agentErrorEvent(agentId: AgentId, error: Error): SwarmEvent {
+  return createEvent('agent:error', agentId, {
+    message: error.message,
+    stack: error.stack
+  });
+}
+
+// Task Events
+export function taskCreatedEvent(taskId: string, spec: { type: string; title: string }): SwarmEvent {
+  return createEvent('task:created', 'swarm', { taskId, type: spec.type, title: spec.title });
+}
+
+export function taskQueuedEvent(taskId: string, position: number): SwarmEvent {
+  return createEvent('task:queued', 'swarm', { taskId, position });
+}
+
+export function taskAssignedEvent(taskId: string, agentId: AgentId): SwarmEvent {
+  return createEvent('task:assigned', 'swarm', { taskId, agentId });
+}
+
+export function taskStartedEvent(taskId: string, agentId: AgentId): SwarmEvent {
+  return createEvent('task:started', agentId, { taskId });
+}
+
+export function taskCompletedEvent(taskId: string, result: unknown): SwarmEvent {
+  return createEvent('task:completed', 'swarm', { taskId, result });
+}
+
+export function taskFailedEvent(taskId: string, error: Error): SwarmEvent {
+  return createEvent('task:failed', 'swarm', {
+    taskId,
+    error: error.message,
+    stack: error.stack
+  });
+}
+
+export function taskBlockedEvent(taskId: string, reason: string, blockingTask: string): SwarmEvent {
+  return createEvent('task:blocked', 'swarm', { taskId, reason, blockingTask });
+}
+
+// Swarm Events
+export function swarmInitializedEvent(source: string, config: unknown): SwarmEvent {
+  return createEvent('swarm:initialized', source, { config });
+}
+
+export function swarmPhaseChangedEvent(source: string, previousPhase: string, newPhase: string): SwarmEvent {
+  return createEvent('swarm:phase-changed', source, { previousPhase, newPhase });
+}
+
+export function swarmMilestoneReachedEvent(milestoneId: string, name: string): SwarmEvent {
+  return createEvent('swarm:milestone-reached', 'swarm', { milestoneId, name });
+}
+
+export function swarmErrorEvent(error: Error): SwarmEvent {
+  return createEvent('swarm:error', 'swarm', {
+    message: error.message,
+    stack: error.stack
+  });
+}

package/src/shared/types.ts

@@ -0,0 +1,389 @@
+/**
+ * @sparkleideas/swarm - Standalone Types
+ * Core type definitions for multi-agent swarm coordination
+ *
+ * This file provides all types needed for standalone operation
+ * without dependency on @sparkleideas/shared
+ */
+
+// =============================================================================
+// Agent Types
+// =============================================================================
+
+export type AgentId = `agent-${number}` | string;
+
+export type AgentRole =
+  | 'queen-coordinator'      // Agent #1
+  | 'security-architect'     // Agent #2
+  | 'security-implementer'   // Agent #3
+  | 'security-tester'        // Agent #4
+  | 'core-architect'         // Agent #5
+  | 'core-implementer'       // Agent #6
+  | 'memory-specialist'      // Agent #7
+  | 'swarm-specialist'       // Agent #8
+  | 'mcp-specialist'         // Agent #9
+  | 'integration-architect'  // Agent #10
+  | 'cli-hooks-developer'    // Agent #11
+  | 'neural-learning-dev'    // Agent #12
+  | 'tdd-test-engineer'      // Agent #13
+  | 'performance-engineer'   // Agent #14
+  | 'release-engineer';      // Agent #15
+
+export type AgentStatus =
+  | 'idle'
+  | 'active'
+  | 'blocked'
+  | 'completed'
+  | 'error';
+
+export type AgentDomain =
+  | 'security'      // Agents #2-4
+  | 'core'          // Agents #5-9
+  | 'integration'   // Agents #10-12
+  | 'quality'       // Agent #13
+  | 'performance'   // Agent #14
+  | 'deployment';   // Agent #15
+
+export interface AgentCapability {
+  name: string;
+  description: string;
+  supportedTaskTypes: TaskType[];
+}
+
+export interface AgentDefinition {
+  id: AgentId;
+  role: AgentRole;
+  domain: AgentDomain;
+  description: string;
+  capabilities: AgentCapability[];
+  dependencies: AgentId[];
+  priority: number;
+}
+
+export interface AgentState {
+  id: AgentId;
+  role: AgentRole;
+  status: AgentStatus;
+  currentTask: TaskId | null;
+  completedTasks: TaskId[];
+  metrics: AgentMetrics;
+  lastHeartbeat: number;
+}
+
+export interface AgentMetrics {
+  tasksCompleted: number;
+  tasksFailed: number;
+  averageTaskDuration: number;
+  utilization: number;
+  startTime: number;
+}
+
+// =============================================================================
+// Task Types
+// =============================================================================
+
+export type TaskId = `task-${string}`;
+
+export type TaskType =
+  | 'security-audit'
+  | 'security-fix'
+  | 'security-test'
+  | 'architecture-design'
+  | 'implementation'
+  | 'memory-optimization'
+  | 'swarm-coordination'
+  | 'mcp-enhancement'
+  | 'integration'
+  | 'cli-development'
+  | 'neural-training'
+  | 'test-writing'
+  | 'benchmark'
+  | 'deployment'
+  | 'documentation';
+
+export type TaskStatus =
+  | 'pending'
+  | 'queued'
+  | 'assigned'
+  | 'in-progress'
+  | 'blocked'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export type TaskPriority =
+  | 'critical'
+  | 'high'
+  | 'medium'
+  | 'low';
+
+export interface TaskDefinition {
+  id: TaskId;
+  type: TaskType;
+  title: string;
+  description: string;
+  assignedAgent: AgentId | null;
+  status: TaskStatus;
+  priority: TaskPriority;
+  dependencies: TaskId[];
+  blockedBy: TaskId[];
+  metadata: TaskMetadata;
+  createdAt: number;
+  updatedAt: number;
+  completedAt: number | null;
+}
+
+export interface TaskMetadata {
+  domain: AgentDomain;
+  phase: PhaseId;
+  estimatedDuration: number;
+  actualDuration: number | null;
+  retryCount: number;
+  maxRetries: number;
+  artifacts: string[];
+  tags: string[];
+}
+
+export interface TaskResult {
+  taskId: TaskId;
+  success: boolean;
+  output: unknown;
+  error: Error | null;
+  duration: number;
+  metrics: TaskResultMetrics;
+}
+
+export interface TaskResultMetrics {
+  linesOfCode: number;
+  testsWritten: number;
+  testsPassed: number;
+  coveragePercent: number;
+  performanceImpact: number;
+}
+
+// =============================================================================
+// Phase Types
+// =============================================================================
+
+export type PhaseId =
+  | 'phase-1-foundation'
+  | 'phase-2-core'
+  | 'phase-3-integration'
+  | 'phase-4-release';
+
+export interface PhaseDefinition {
+  id: PhaseId;
+  name: string;
+  description: string;
+  weeks: [number, number];
+  activeAgents: AgentId[];
+  goals: string[];
+  milestones: MilestoneDefinition[];
+}
+
+export interface MilestoneDefinition {
+  id: string;
+  name: string;
+  description: string;
+  criteria: MilestoneCriteria[];
+  status: MilestoneStatus;
+  completedAt: number | null;
+}
+
+export type MilestoneStatus = 'pending' | 'in-progress' | 'completed' | 'blocked';
+
+export interface MilestoneCriteria {
+  description: string;
+  met: boolean;
+  evidence: string | null;
+}
+
+// =============================================================================
+// Swarm Types
+// =============================================================================
+
+export type TopologyType =
+  | 'hierarchical-mesh'
+  | 'mesh'
+  | 'hierarchical'
+  | 'centralized'
+  | 'hybrid';
+
+export interface SwarmConfig {
+  topology: TopologyType;
+  maxAgents: number;
+  messageTimeout: number;
+  retryAttempts: number;
+  healthCheckInterval: number;
+  loadBalancingStrategy: LoadBalancingStrategy;
+}
+
+export type LoadBalancingStrategy =
+  | 'round-robin'
+  | 'least-loaded'
+  | 'capability-match'
+  | 'priority-based';
+
+export interface SwarmState {
+  initialized: boolean;
+  topology: TopologyType;
+  agents: Map<AgentId, AgentState>;
+  tasks: Map<TaskId, TaskDefinition>;
+  currentPhase: PhaseId;
+  metrics: SwarmMetrics;
+}
+
+export interface SwarmMetrics {
+  totalAgents: number;
+  activeAgents: number;
+  idleAgents: number;
+  blockedAgents: number;
+  totalTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  pendingTasks: number;
+  averageTaskDuration: number;
+  utilization: number;
+  startTime: number;
+  lastUpdate: number;
+}
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export type EventType =
+  | 'agent:spawned'
+  | 'agent:status-changed'
+  | 'agent:task-assigned'
+  | 'agent:task-completed'
+  | 'agent:error'
+  | 'task:created'
+  | 'task:queued'
+  | 'task:assigned'
+  | 'task:started'
+  | 'task:completed'
+  | 'task:failed'
+  | 'task:blocked'
+  | 'swarm:initialized'
+  | 'swarm:phase-changed'
+  | 'swarm:milestone-reached'
+  | 'swarm:error';
+
+export interface SwarmEvent<T = unknown> {
+  id: string;
+  type: EventType;
+  timestamp: number;
+  source: AgentId | 'swarm';
+  payload: T;
+}
+
+export type EventHandler<T = unknown> = (event: SwarmEvent<T>) => void | Promise<void>;
+
+// =============================================================================
+// Message Types
+// =============================================================================
+
+export type MessageType =
+  | 'task_assignment'
+  | 'task_complete'
+  | 'task_failed'
+  | 'dependency_ready'
+  | 'review_request'
+  | 'status_update'
+  | 'heartbeat'
+  | 'broadcast';
+
+export interface SwarmMessage<T = unknown> {
+  id: string;
+  type: MessageType;
+  from: AgentId;
+  to: AgentId | 'broadcast';
+  payload: T;
+  timestamp: number;
+  correlationId: string | null;
+}
+
+export type MessageHandler<T = unknown> = (message: SwarmMessage<T>) => void | Promise<void>;
+
+// =============================================================================
+// Interface Types (for dependency injection)
+// =============================================================================
+
+export interface IAgent {
+  id: AgentId;
+  role: AgentRole;
+  status: AgentStatus;
+  execute(task: TaskDefinition): Promise<TaskResult>;
+  getState(): AgentState;
+}
+
+export interface ITask {
+  id: TaskId;
+  type: TaskType;
+  status: TaskStatus;
+  priority: TaskPriority;
+  execute(): Promise<TaskResult>;
+}
+
+// =============================================================================
+// Performance Targets
+// =============================================================================
+
+export interface PerformanceTargets {
+  flashAttention: {
+    minSpeedup: number;
+    maxSpeedup: number;
+  };
+  agentDbSearch: {
+    minSpeedup: number;
+    maxSpeedup: number;
+  };
+  memoryReduction: {
+    minPercent: number;
+    maxPercent: number;
+  };
+  codeReduction: {
+    targetLines: number;
+    currentLines: number;
+  };
+  startupTime: {
+    targetMs: number;
+  };
+  sonaLearning: {
+    targetMs: number;
+  };
+}
+
+export const V3_PERFORMANCE_TARGETS: PerformanceTargets = {
+  flashAttention: { minSpeedup: 2.49, maxSpeedup: 7.47 },
+  agentDbSearch: { minSpeedup: 150, maxSpeedup: 12500 },
+  memoryReduction: { minPercent: 50, maxPercent: 75 },
+  codeReduction: { targetLines: 5000, currentLines: 15000 },
+  startupTime: { targetMs: 500 },
+  sonaLearning: { targetMs: 0.05 }
+};
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+export type AsyncCallback<T = void> = () => Promise<T>;
+
+export interface Result<T, E = Error> {
+  success: boolean;
+  value?: T;
+  error?: E;
+}
+
+export function success<T>(value: T): Result<T> {
+  return { success: true, value };
+}
+
+export function failure<E = Error>(error: E): Result<never, E> {
+  return { success: false, error };
+}