claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/shared/dist/core/interfaces/event.interface.d.ts

@@ -0,0 +1,224 @@
+/**
+ * V3 Event Interfaces
+ * Domain-Driven Design - Event Sourcing Pattern (ADR-007)
+ */
+/**
+ * Event priority levels
+ */
+export type EventPriority = 'critical' | 'high' | 'normal' | 'low';
+/**
+ * Core event structure
+ */
+export interface IEvent<T = unknown> {
+    readonly id: string;
+    readonly type: string;
+    readonly timestamp: Date;
+    readonly source: string;
+    payload: T;
+    priority?: EventPriority;
+    correlationId?: string;
+    causationId?: string;
+    metadata?: {
+        version?: number;
+        userId?: string;
+        sessionId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Event creation parameters
+ */
+export interface IEventCreate<T = unknown> {
+    type: string;
+    payload: T;
+    source?: string;
+    priority?: EventPriority;
+    correlationId?: string;
+    causationId?: string;
+    metadata?: IEvent['metadata'];
+}
+/**
+ * Event handler function type
+ */
+export type IEventHandler<T = unknown> = (event: IEvent<T>) => void | Promise<void>;
+/**
+ * Event filter for subscriptions
+ */
+export interface IEventFilter {
+    types?: string[];
+    sources?: string[];
+    priority?: EventPriority[];
+    correlationId?: string;
+}
+/**
+ * Event subscription handle
+ */
+export interface IEventSubscription {
+    readonly id: string;
+    readonly filter: IEventFilter;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(): void;
+    /**
+     * Pause subscription
+     */
+    pause(): void;
+    /**
+     * Resume subscription
+     */
+    resume(): void;
+    /**
+     * Check if subscription is active
+     */
+    isActive(): boolean;
+}
+/**
+ * Event bus interface for pub/sub communication
+ */
+export interface IEventBus {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): void;
+    /**
+     * Emit an event and wait for all handlers
+     */
+    emitAsync<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): Promise<void>;
+    /**
+     * Subscribe to events matching a type pattern
+     */
+    on<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+    /**
+     * Subscribe to events with filter
+     */
+    subscribe<T = unknown>(filter: IEventFilter, handler: IEventHandler<T>): IEventSubscription;
+    /**
+     * Subscribe to a single event occurrence
+     */
+    once<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription;
+    /**
+     * Remove a specific handler
+     */
+    off(type: string, handler: IEventHandler): void;
+    /**
+     * Remove all handlers for a type
+     */
+    removeAllListeners(type?: string): void;
+    /**
+     * Get count of listeners for a type
+     */
+    listenerCount(type: string): number;
+    /**
+     * Get all event types with active listeners
+     */
+    eventNames(): string[];
+}
+/**
+ * System event types enumeration
+ */
+export declare const SystemEventTypes: {
+    readonly SYSTEM_READY: "system:ready";
+    readonly SYSTEM_SHUTDOWN: "system:shutdown";
+    readonly SYSTEM_ERROR: "system:error";
+    readonly SYSTEM_HEALTHCHECK: "system:healthcheck";
+    readonly AGENT_SPAWNED: "agent:spawned";
+    readonly AGENT_TERMINATED: "agent:terminated";
+    readonly AGENT_ERROR: "agent:error";
+    readonly AGENT_IDLE: "agent:idle";
+    readonly AGENT_BUSY: "agent:busy";
+    readonly AGENT_HEALTH_CHANGED: "agent:health:changed";
+    readonly TASK_CREATED: "task:created";
+    readonly TASK_ASSIGNED: "task:assigned";
+    readonly TASK_STARTED: "task:started";
+    readonly TASK_COMPLETED: "task:completed";
+    readonly TASK_FAILED: "task:failed";
+    readonly TASK_CANCELLED: "task:cancelled";
+    readonly TASK_TIMEOUT: "task:timeout";
+    readonly TASK_RETRY: "task:retry";
+    readonly SESSION_CREATED: "session:created";
+    readonly SESSION_RESTORED: "session:restored";
+    readonly SESSION_TERMINATED: "session:terminated";
+    readonly SESSION_PERSISTED: "session:persisted";
+    readonly MEMORY_STORED: "memory:stored";
+    readonly MEMORY_RETRIEVED: "memory:retrieved";
+    readonly MEMORY_CLEARED: "memory:cleared";
+    readonly COORDINATION_STARTED: "coordination:started";
+    readonly COORDINATION_COMPLETED: "coordination:completed";
+    readonly DEADLOCK_DETECTED: "coordination:deadlock";
+    readonly METRICS_COLLECTED: "metrics:collected";
+};
+export type SystemEventType = typeof SystemEventTypes[keyof typeof SystemEventTypes];
+/**
+ * Event store interface for event sourcing
+ */
+export interface IEventStore {
+    /**
+     * Append an event to the store
+     */
+    append(event: IEvent): Promise<void>;
+    /**
+     * Get events by aggregate ID
+     */
+    getByAggregateId(aggregateId: string, fromVersion?: number): Promise<IEvent[]>;
+    /**
+     * Get events by type
+     */
+    getByType(type: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<IEvent[]>;
+    /**
+     * Get events in time range
+     */
+    getByTimeRange(start: Date, end: Date): Promise<IEvent[]>;
+    /**
+     * Get events by correlation ID
+     */
+    getByCorrelationId(correlationId: string): Promise<IEvent[]>;
+    /**
+     * Get all events (paginated)
+     */
+    getAll(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<IEvent[]>;
+    /**
+     * Get event count
+     */
+    count(filter?: IEventFilter): Promise<number>;
+    /**
+     * Clear old events
+     */
+    prune(olderThan: Date): Promise<number>;
+}
+/**
+ * Event coordinator for routing and orchestration
+ */
+export interface IEventCoordinator {
+    /**
+     * Initialize the coordinator
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown the coordinator
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Route an event to appropriate handlers
+     */
+    route(event: IEvent): Promise<void>;
+    /**
+     * Register a handler for event routing
+     */
+    registerHandler(type: string, handler: IEventHandler): void;
+    /**
+     * Unregister a handler
+     */
+    unregisterHandler(type: string, handler: IEventHandler): void;
+    /**
+     * Get event bus instance
+     */
+    getEventBus(): IEventBus;
+}
+//# sourceMappingURL=event.interface.d.ts.map

package/v3/@claude-flow/shared/dist/core/interfaces/event.interface.js

@@ -0,0 +1,46 @@
+/**
+ * V3 Event Interfaces
+ * Domain-Driven Design - Event Sourcing Pattern (ADR-007)
+ */
+/**
+ * System event types enumeration
+ */
+export const SystemEventTypes = {
+    // System lifecycle
+    SYSTEM_READY: 'system:ready',
+    SYSTEM_SHUTDOWN: 'system:shutdown',
+    SYSTEM_ERROR: 'system:error',
+    SYSTEM_HEALTHCHECK: 'system:healthcheck',
+    // Agent lifecycle
+    AGENT_SPAWNED: 'agent:spawned',
+    AGENT_TERMINATED: 'agent:terminated',
+    AGENT_ERROR: 'agent:error',
+    AGENT_IDLE: 'agent:idle',
+    AGENT_BUSY: 'agent:busy',
+    AGENT_HEALTH_CHANGED: 'agent:health:changed',
+    // Task lifecycle
+    TASK_CREATED: 'task:created',
+    TASK_ASSIGNED: 'task:assigned',
+    TASK_STARTED: 'task:started',
+    TASK_COMPLETED: 'task:completed',
+    TASK_FAILED: 'task:failed',
+    TASK_CANCELLED: 'task:cancelled',
+    TASK_TIMEOUT: 'task:timeout',
+    TASK_RETRY: 'task:retry',
+    // Session lifecycle
+    SESSION_CREATED: 'session:created',
+    SESSION_RESTORED: 'session:restored',
+    SESSION_TERMINATED: 'session:terminated',
+    SESSION_PERSISTED: 'session:persisted',
+    // Memory events
+    MEMORY_STORED: 'memory:stored',
+    MEMORY_RETRIEVED: 'memory:retrieved',
+    MEMORY_CLEARED: 'memory:cleared',
+    // Coordination events
+    COORDINATION_STARTED: 'coordination:started',
+    COORDINATION_COMPLETED: 'coordination:completed',
+    DEADLOCK_DETECTED: 'coordination:deadlock',
+    // Metrics events
+    METRICS_COLLECTED: 'metrics:collected',
+};
+//# sourceMappingURL=event.interface.js.map

package/v3/@claude-flow/shared/dist/core/interfaces/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * V3 Core Interfaces - Public API
+ * Domain-Driven Design with Clean Architecture
+ */
+export * from './task.interface.js';
+export * from './agent.interface.js';
+export * from './event.interface.js';
+export * from './memory.interface.js';
+export * from './coordinator.interface.js';
+//# sourceMappingURL=index.d.ts.map

package/v3/@claude-flow/shared/dist/core/interfaces/index.js

@@ -0,0 +1,15 @@
+/**
+ * V3 Core Interfaces - Public API
+ * Domain-Driven Design with Clean Architecture
+ */
+// Task interfaces
+export * from './task.interface.js';
+// Agent interfaces
+export * from './agent.interface.js';
+// Event interfaces
+export * from './event.interface.js';
+// Memory interfaces
+export * from './memory.interface.js';
+// Coordinator interfaces
+export * from './coordinator.interface.js';
+//# sourceMappingURL=index.js.map

package/v3/@claude-flow/shared/dist/core/interfaces/memory.interface.d.ts

@@ -0,0 +1,298 @@
+/**
+ * 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;
+    }>;
+}
+//# sourceMappingURL=memory.interface.d.ts.map

package/v3/@claude-flow/shared/dist/core/interfaces/memory.interface.js

@@ -0,0 +1,7 @@
+/**
+ * V3 Memory Interfaces
+ * Domain-Driven Design - Memory Management Bounded Context
+ * Aligned with ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend)
+ */
+export {};
+//# sourceMappingURL=memory.interface.js.map