@sparkleideas/shared 3.0.0-alpha.7

package/src/core/interfaces/memory.interface.ts

@@ -0,0 +1,332 @@
+/**
+ * V3 Memory Interfaces
+ * Domain-Driven Design - Memory Management Bounded Context
+ * Aligned with ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend)
+ */
+
+/**
+ * Memory entry types
+ */
+export type MemoryType = 'session' | 'persistent' | 'vector' | 'cache' | 'pattern';
+
+/**
+ * Memory entry structure
+ */
+export interface IMemoryEntry {
+  readonly id: string;
+  readonly key: string;
+  readonly type: MemoryType;
+  readonly createdAt: Date;
+
+  value: unknown;
+  updatedAt: Date;
+  expiresAt?: Date;
+
+  metadata?: {
+    source?: string;
+    agentId?: string;
+    sessionId?: string;
+    version?: number;
+    tags?: string[];
+    embedding?: number[];
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Memory entry creation parameters
+ */
+export interface IMemoryEntryCreate {
+  key: string;
+  value: unknown;
+  type?: MemoryType;
+  expiresAt?: Date;
+  ttlMs?: number;
+  metadata?: IMemoryEntry['metadata'];
+}
+
+/**
+ * Vector search parameters
+ */
+export interface IVectorSearchParams {
+  embedding: number[];
+  k?: number;
+  threshold?: number;
+  filter?: {
+    type?: MemoryType;
+    tags?: string[];
+    agentId?: string;
+  };
+}
+
+/**
+ * Vector search result
+ */
+export interface IVectorSearchResult {
+  entry: IMemoryEntry;
+  score: number;
+  distance: number;
+}
+
+/**
+ * Memory backend interface for storage operations
+ */
+export interface IMemoryBackend {
+  /**
+   * Initialize the backend
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the backend
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Store a memory entry
+   */
+  store(entry: IMemoryEntryCreate): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve a memory entry by key
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Retrieve by ID
+   */
+  retrieveById(id: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Update a memory entry
+   */
+  update(key: string, value: unknown, metadata?: Partial<IMemoryEntry['metadata']>): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Delete a memory entry
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * Check if a key exists
+   */
+  exists(key: string): Promise<boolean>;
+
+  /**
+   * List all keys matching a pattern
+   */
+  keys(pattern?: string): Promise<string[]>;
+
+  /**
+   * Get all entries matching filter
+   */
+  list(filter?: { type?: MemoryType; tags?: string[] }): Promise<IMemoryEntry[]>;
+
+  /**
+   * Clear all entries
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get entry count
+   */
+  count(): Promise<number>;
+
+  /**
+   * Prune expired entries
+   */
+  prune(): Promise<number>;
+
+  /**
+   * Get health status
+   */
+  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
+}
+
+/**
+ * Vector memory backend for similarity search
+ */
+export interface IVectorMemoryBackend extends IMemoryBackend {
+  /**
+   * Store with embedding
+   */
+  storeVector(entry: IMemoryEntryCreate & { embedding: number[] }): Promise<IMemoryEntry>;
+
+  /**
+   * Search by vector similarity
+   */
+  search(params: IVectorSearchParams): Promise<IVectorSearchResult[]>;
+
+  /**
+   * Update embedding for an entry
+   */
+  updateEmbedding(key: string, embedding: number[]): Promise<boolean>;
+
+  /**
+   * Build or rebuild index
+   */
+  buildIndex(): Promise<void>;
+
+  /**
+   * Get index statistics
+   */
+  getIndexStats(): Promise<{
+    vectorCount: number;
+    dimensions: number;
+    indexType: string;
+    memoryUsageMb: number;
+  }>;
+}
+
+/**
+ * Memory bank for agent-specific storage
+ */
+export interface IMemoryBank {
+  readonly id: string;
+  readonly agentId: string;
+  readonly createdAt: Date;
+
+  /**
+   * Store in bank
+   */
+  store(key: string, value: unknown, options?: Partial<IMemoryEntryCreate>): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve from bank
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Delete from bank
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * List all entries in bank
+   */
+  list(): Promise<IMemoryEntry[]>;
+
+  /**
+   * Clear all entries in bank
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get bank size
+   */
+  size(): Promise<number>;
+
+  /**
+   * Close the bank
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Memory manager interface
+ */
+export interface IMemoryManager {
+  /**
+   * Initialize the manager
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Shutdown the manager
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Create a memory bank for an agent
+   */
+  createBank(agentId: string): Promise<string>;
+
+  /**
+   * Get a memory bank
+   */
+  getBank(bankId: string): IMemoryBank | undefined;
+
+  /**
+   * Close a memory bank
+   */
+  closeBank(bankId: string): Promise<void>;
+
+  /**
+   * Store in global memory
+   */
+  store(entry: IMemoryEntryCreate): Promise<IMemoryEntry>;
+
+  /**
+   * Retrieve from global memory
+   */
+  retrieve(key: string): Promise<IMemoryEntry | undefined>;
+
+  /**
+   * Search vectors (if vector backend available)
+   */
+  searchVectors?(params: IVectorSearchParams): Promise<IVectorSearchResult[]>;
+
+  /**
+   * Perform maintenance
+   */
+  performMaintenance(): Promise<void>;
+
+  /**
+   * Get health status
+   */
+  getHealthStatus(): Promise<{ healthy: boolean; error?: string; metrics?: Record<string, number> }>;
+
+  /**
+   * Get memory usage statistics
+   */
+  getStats(): Promise<{
+    totalEntries: number;
+    memoryUsageMb: number;
+    banksCount: number;
+    cacheHitRate?: number;
+  }>;
+}
+
+/**
+ * Pattern storage for ReasoningBank integration
+ */
+export interface IPatternStorage {
+  /**
+   * Store a learned pattern
+   */
+  storePattern(pattern: {
+    sessionId: string;
+    task: string;
+    input: string;
+    output: string;
+    reward: number;
+    success: boolean;
+    critique?: string;
+    tokensUsed?: number;
+    latencyMs?: number;
+  }): Promise<void>;
+
+  /**
+   * Search for similar patterns
+   */
+  searchPatterns(params: {
+    task: string;
+    k?: number;
+    minReward?: number;
+    onlyFailures?: boolean;
+  }): Promise<Array<{
+    task: string;
+    reward: number;
+    critique: string;
+    output: string;
+  }>>;
+
+  /**
+   * Get pattern statistics
+   */
+  getPatternStats(): Promise<{
+    totalPatterns: number;
+    avgReward: number;
+    successRate: number;
+  }>;
+}

package/src/core/interfaces/task.interface.ts

@@ -0,0 +1,223 @@
+/**
+ * V3 Task Interfaces
+ * Domain-Driven Design - Task Bounded Context
+ */
+
+/**
+ * Task priority levels
+ */
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
+
+/**
+ * Task status throughout its lifecycle
+ */
+export type TaskStatus =
+  | 'pending'
+  | 'queued'
+  | 'assigned'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'timeout';
+
+/**
+ * Core task entity
+ */
+export interface ITask {
+  readonly id: string;
+  readonly type: string;
+  readonly description: string;
+  readonly priority: number;
+  readonly createdAt: Date;
+
+  status: TaskStatus;
+  assignedAgent?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  timeout?: number;
+
+  input?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+  error?: Error;
+
+  metadata?: {
+    requiredCapabilities?: string[];
+    retryCount?: number;
+    maxRetries?: number;
+    critical?: boolean;
+    parentTaskId?: string;
+    childTaskIds?: string[];
+    tags?: string[];
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Task creation parameters
+ */
+export interface ITaskCreate {
+  type: string;
+  description: string;
+  priority?: number;
+  timeout?: number;
+  assignedAgent?: string;
+  input?: Record<string, unknown>;
+  metadata?: ITask['metadata'];
+}
+
+/**
+ * Task result after completion
+ */
+export interface ITaskResult {
+  taskId: string;
+  success: boolean;
+  output?: Record<string, unknown>;
+  error?: Error;
+  duration: number;
+  agentId?: string;
+  metrics?: {
+    tokensUsed?: number;
+    memoryPeakMb?: number;
+    retryCount?: number;
+  };
+}
+
+/**
+ * Task queue interface for managing task ordering and processing
+ */
+export interface ITaskQueue {
+  /**
+   * Add a task to the queue
+   */
+  enqueue(task: ITask): Promise<void>;
+
+  /**
+   * Remove and return the highest priority task
+   */
+  dequeue(): Promise<ITask | undefined>;
+
+  /**
+   * Peek at the next task without removing it
+   */
+  peek(): Promise<ITask | undefined>;
+
+  /**
+   * Get the current queue size
+   */
+  size(): number;
+
+  /**
+   * Check if the queue is empty
+   */
+  isEmpty(): boolean;
+
+  /**
+   * Clear all tasks from the queue
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Get all queued tasks (for inspection)
+   */
+  getAll(): Promise<ITask[]>;
+
+  /**
+   * Remove a specific task by ID
+   */
+  remove(taskId: string): Promise<boolean>;
+
+  /**
+   * Update task priority
+   */
+  updatePriority(taskId: string, priority: number): Promise<boolean>;
+}
+
+/**
+ * Task manager interface for lifecycle management
+ */
+export interface ITaskManager {
+  /**
+   * Create a new task
+   */
+  createTask(params: ITaskCreate): Promise<ITask>;
+
+  /**
+   * Get a task by ID
+   */
+  getTask(taskId: string): ITask | undefined;
+
+  /**
+   * Get all tasks matching optional filter
+   */
+  getTasks(filter?: Partial<Pick<ITask, 'status' | 'type' | 'assignedAgent'>>): ITask[];
+
+  /**
+   * Assign a task to an agent
+   */
+  assignTask(taskId: string, agentId: string): Promise<void>;
+
+  /**
+   * Start task execution
+   */
+  startTask(taskId: string): Promise<void>;
+
+  /**
+   * Complete a task with result
+   */
+  completeTask(taskId: string, result: ITaskResult): Promise<void>;
+
+  /**
+   * Fail a task with error
+   */
+  failTask(taskId: string, error: Error): Promise<void>;
+
+  /**
+   * Cancel a task
+   */
+  cancelTask(taskId: string, reason?: string): Promise<void>;
+
+  /**
+   * Retry a failed task
+   */
+  retryTask(taskId: string): Promise<void>;
+
+  /**
+   * Get task metrics
+   */
+  getMetrics(): TaskManagerMetrics;
+
+  /**
+   * Clean up old completed/failed tasks
+   */
+  cleanup(olderThan: Date): Promise<number>;
+}
+
+/**
+ * Task manager metrics
+ */
+export interface TaskManagerMetrics {
+  totalTasks: number;
+  pendingTasks: number;
+  runningTasks: number;
+  completedTasks: number;
+  failedTasks: number;
+  cancelledTasks: number;
+  avgDuration: number;
+  avgWaitTime: number;
+}
+
+/**
+ * Task assignment strategy interface
+ */
+export interface ITaskAssignmentStrategy {
+  /**
+   * Select the best agent for a task
+   */
+  selectAgent(task: ITask, availableAgents: string[]): Promise<string | undefined>;
+
+  /**
+   * Score an agent for a task (higher is better)
+   */
+  scoreAgent(task: ITask, agentId: string): Promise<number>;
+}

package/src/core/orchestrator/event-coordinator.ts

@@ -0,0 +1,122 @@
+/**
+ * V3 Event Coordinator
+ * Decomposed from orchestrator.ts - Event routing
+ * ~100 lines (target achieved)
+ */
+
+import type {
+  IEvent,
+  IEventBus,
+  IEventHandler,
+  IEventCoordinator,
+} from '../interfaces/event.interface.js';
+import { SystemEventTypes } from '../interfaces/event.interface.js';
+
+/**
+ * Event coordinator implementation
+ */
+export class EventCoordinator implements IEventCoordinator {
+  private handlers = new Map<string, Set<IEventHandler>>();
+  private initialized = false;
+
+  constructor(private eventBus: IEventBus) {}
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Register default system event handlers
+    this.registerSystemHandlers();
+
+    this.initialized = true;
+  }
+
+  async shutdown(): Promise<void> {
+    // Clear all handlers
+    this.handlers.clear();
+    this.initialized = false;
+  }
+
+  async route(event: IEvent): Promise<void> {
+    const handlers = this.handlers.get(event.type);
+    if (!handlers || handlers.size === 0) {
+      return;
+    }
+
+    const handlerPromises = Array.from(handlers).map(async handler => {
+      try {
+        await handler(event);
+      } catch (error) {
+        // Log error but don't throw
+        console.error(`Error in event handler for ${event.type}:`, error);
+      }
+    });
+
+    await Promise.allSettled(handlerPromises);
+  }
+
+  registerHandler(type: string, handler: IEventHandler): void {
+    let handlers = this.handlers.get(type);
+    if (!handlers) {
+      handlers = new Set();
+      this.handlers.set(type, handlers);
+    }
+    handlers.add(handler);
+
+    // Also register with event bus
+    this.eventBus.on(type, handler);
+  }
+
+  unregisterHandler(type: string, handler: IEventHandler): void {
+    const handlers = this.handlers.get(type);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.handlers.delete(type);
+      }
+    }
+
+    // Also unregister from event bus
+    this.eventBus.off(type, handler);
+  }
+
+  getEventBus(): IEventBus {
+    return this.eventBus;
+  }
+
+  private registerSystemHandlers(): void {
+    // Error handling
+    this.eventBus.on(SystemEventTypes.SYSTEM_ERROR, (event: IEvent) => {
+      const { error, component } = event.payload as { error: Error; component: string };
+      console.error(`System error in ${component}:`, error);
+    });
+
+    // Deadlock detection
+    this.eventBus.on(SystemEventTypes.DEADLOCK_DETECTED, (event: IEvent) => {
+      const { agents, resources } = event.payload as { agents: string[]; resources: string[] };
+      console.warn('Deadlock detected:', { agents, resources });
+    });
+  }
+
+  /**
+   * Get registered handler count for a type
+   */
+  getHandlerCount(type: string): number {
+    return this.handlers.get(type)?.size ?? 0;
+  }
+
+  /**
+   * Get all registered event types
+   */
+  getRegisteredTypes(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  /**
+   * Check if coordinator is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+}