claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/shared/dist/hooks/types.d.ts

@@ -0,0 +1,267 @@
+/**
+ * V3 Hooks System - Type Definitions
+ *
+ * Provides extensible hook points for tool execution, file operations,
+ * and session lifecycle events. Integrates with event bus for coordination.
+ *
+ * @module v3/shared/hooks/types
+ */
+/**
+ * Hook event types
+ */
+export declare enum HookEvent {
+    PreToolUse = "hook:pre-tool-use",
+    PostToolUse = "hook:post-tool-use",
+    PreEdit = "hook:pre-edit",
+    PostEdit = "hook:post-edit",
+    PreRead = "hook:pre-read",
+    PostRead = "hook:post-read",
+    PreWrite = "hook:pre-write",
+    PostWrite = "hook:post-write",
+    PreCommand = "hook:pre-command",
+    PostCommand = "hook:post-command",
+    SessionStart = "hook:session-start",
+    SessionEnd = "hook:session-end",
+    SessionPause = "hook:session-pause",
+    SessionResume = "hook:session-resume",
+    PreAgentSpawn = "hook:pre-agent-spawn",
+    PostAgentSpawn = "hook:post-agent-spawn",
+    PreAgentTerminate = "hook:pre-agent-terminate",
+    PostAgentTerminate = "hook:post-agent-terminate",
+    PreTaskExecute = "hook:pre-task-execute",
+    PostTaskExecute = "hook:post-task-execute",
+    PreTaskComplete = "hook:pre-task-complete",
+    PostTaskComplete = "hook:post-task-complete",
+    PreMemoryStore = "hook:pre-memory-store",
+    PostMemoryStore = "hook:post-memory-store",
+    PreMemoryRetrieve = "hook:pre-memory-retrieve",
+    PostMemoryRetrieve = "hook:post-memory-retrieve",
+    OnError = "hook:on-error",
+    OnWarning = "hook:on-warning"
+}
+/**
+ * Hook priority levels (higher = earlier execution)
+ */
+export declare enum HookPriority {
+    Critical = 1000,
+    High = 500,
+    Normal = 0,
+    Low = -500,
+    Lowest = -1000
+}
+/**
+ * Tool information for tool-related hooks
+ */
+export interface ToolInfo {
+    /** Tool name (e.g., 'Read', 'Write', 'Bash') */
+    name: string;
+    /** Tool parameters */
+    parameters: Record<string, unknown>;
+    /** Estimated execution time in ms */
+    estimatedDuration?: number;
+    /** Tool category */
+    category?: 'file' | 'bash' | 'search' | 'edit' | 'git' | 'other';
+}
+/**
+ * Command information for command-related hooks
+ */
+export interface CommandInfo {
+    /** Command string */
+    command: string;
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Command timeout in ms */
+    timeout?: number;
+    /** Whether command is destructive */
+    isDestructive?: boolean;
+}
+/**
+ * File operation information
+ */
+export interface FileOperationInfo {
+    /** File path */
+    path: string;
+    /** Operation type */
+    operation: 'read' | 'write' | 'edit' | 'delete';
+    /** File content (for write/edit operations) */
+    content?: string;
+    /** Previous content (for edit operations) */
+    previousContent?: string;
+    /** File size in bytes */
+    size?: number;
+}
+/**
+ * Session information
+ */
+export interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** Session start time */
+    startTime: Date;
+    /** Session end time */
+    endTime?: Date;
+    /** Session metadata */
+    metadata?: Record<string, unknown>;
+    /** User ID (if available) */
+    userId?: string;
+}
+/**
+ * Agent information
+ */
+export interface AgentInfo {
+    /** Agent ID */
+    id: string;
+    /** Agent type/role */
+    type: string;
+    /** Agent configuration */
+    config?: Record<string, unknown>;
+    /** Parent agent ID */
+    parentId?: string;
+}
+/**
+ * Task information
+ */
+export interface TaskInfo {
+    /** Task ID */
+    id: string;
+    /** Task description */
+    description: string;
+    /** Task priority */
+    priority?: number;
+    /** Assigned agent ID */
+    agentId?: string;
+    /** Task metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Memory operation information
+ */
+export interface MemoryInfo {
+    /** Memory key */
+    key: string;
+    /** Memory value */
+    value?: unknown;
+    /** Memory namespace */
+    namespace?: string;
+    /** TTL in seconds */
+    ttl?: number;
+}
+/**
+ * Error information
+ */
+export interface ErrorInfo {
+    /** Error object */
+    error: Error;
+    /** Error context */
+    context?: string;
+    /** Error severity */
+    severity: 'warning' | 'error' | 'fatal';
+    /** Recoverable flag */
+    recoverable: boolean;
+}
+/**
+ * Hook context - contains information about the event being hooked
+ */
+export interface HookContext {
+    /** Event type */
+    event: HookEvent;
+    /** Timestamp when hook was triggered */
+    timestamp: Date;
+    /** Correlation ID for tracking related events */
+    correlationId?: string;
+    /** Tool information (for tool hooks) */
+    tool?: ToolInfo;
+    /** Command information (for command hooks) */
+    command?: CommandInfo;
+    /** File operation information (for file hooks) */
+    file?: FileOperationInfo;
+    /** Session information (for session hooks) */
+    session?: SessionInfo;
+    /** Agent information (for agent hooks) */
+    agent?: AgentInfo;
+    /** Task information (for task hooks) */
+    task?: TaskInfo;
+    /** Memory information (for memory hooks) */
+    memory?: MemoryInfo;
+    /** Error information (for error hooks) */
+    error?: ErrorInfo;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Hook result - returned by hook handlers
+ */
+export interface HookResult {
+    /** Whether the hook succeeded */
+    success: boolean;
+    /** Result data (can modify context) */
+    data?: Partial<HookContext>;
+    /** Error if hook failed */
+    error?: Error;
+    /** Whether to continue executing other hooks */
+    continueChain?: boolean;
+    /** Whether to abort the operation */
+    abort?: boolean;
+    /** Hook execution time in ms */
+    executionTime?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Hook handler function type
+ */
+export type HookHandler = (context: HookContext) => Promise<HookResult> | HookResult;
+/**
+ * Hook definition with metadata
+ */
+export interface HookDefinition {
+    /** Unique hook ID */
+    id: string;
+    /** Hook event type */
+    event: HookEvent;
+    /** Hook handler function */
+    handler: HookHandler;
+    /** Hook priority */
+    priority: HookPriority;
+    /** Hook name/description */
+    name?: string;
+    /** Whether hook is enabled */
+    enabled: boolean;
+    /** Hook timeout in ms */
+    timeout?: number;
+    /** Hook metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Hook statistics
+ */
+export interface HookStats {
+    /** Total hooks registered */
+    totalHooks: number;
+    /** Hooks by event type */
+    byEvent: Record<HookEvent, number>;
+    /** Total executions */
+    totalExecutions: number;
+    /** Total failures */
+    totalFailures: number;
+    /** Average execution time in ms */
+    avgExecutionTime: number;
+    /** Total execution time in ms */
+    totalExecutionTime: number;
+}
+/**
+ * Hook execution options
+ */
+export interface HookExecutionOptions {
+    /** Timeout in ms (overrides hook-specific timeout) */
+    timeout?: number;
+    /** Whether to continue on error */
+    continueOnError?: boolean;
+    /** Maximum parallel executions */
+    maxParallel?: number;
+    /** Whether to collect results from all hooks */
+    collectResults?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/v3/@claude-flow/shared/dist/hooks/types.js

@@ -0,0 +1,62 @@
+/**
+ * V3 Hooks System - Type Definitions
+ *
+ * Provides extensible hook points for tool execution, file operations,
+ * and session lifecycle events. Integrates with event bus for coordination.
+ *
+ * @module v3/shared/hooks/types
+ */
+/**
+ * Hook event types
+ */
+export var HookEvent;
+(function (HookEvent) {
+    // Tool execution hooks
+    HookEvent["PreToolUse"] = "hook:pre-tool-use";
+    HookEvent["PostToolUse"] = "hook:post-tool-use";
+    // File operation hooks
+    HookEvent["PreEdit"] = "hook:pre-edit";
+    HookEvent["PostEdit"] = "hook:post-edit";
+    HookEvent["PreRead"] = "hook:pre-read";
+    HookEvent["PostRead"] = "hook:post-read";
+    HookEvent["PreWrite"] = "hook:pre-write";
+    HookEvent["PostWrite"] = "hook:post-write";
+    // Command execution hooks
+    HookEvent["PreCommand"] = "hook:pre-command";
+    HookEvent["PostCommand"] = "hook:post-command";
+    // Session lifecycle hooks
+    HookEvent["SessionStart"] = "hook:session-start";
+    HookEvent["SessionEnd"] = "hook:session-end";
+    HookEvent["SessionPause"] = "hook:session-pause";
+    HookEvent["SessionResume"] = "hook:session-resume";
+    // Agent lifecycle hooks
+    HookEvent["PreAgentSpawn"] = "hook:pre-agent-spawn";
+    HookEvent["PostAgentSpawn"] = "hook:post-agent-spawn";
+    HookEvent["PreAgentTerminate"] = "hook:pre-agent-terminate";
+    HookEvent["PostAgentTerminate"] = "hook:post-agent-terminate";
+    // Task lifecycle hooks
+    HookEvent["PreTaskExecute"] = "hook:pre-task-execute";
+    HookEvent["PostTaskExecute"] = "hook:post-task-execute";
+    HookEvent["PreTaskComplete"] = "hook:pre-task-complete";
+    HookEvent["PostTaskComplete"] = "hook:post-task-complete";
+    // Memory hooks
+    HookEvent["PreMemoryStore"] = "hook:pre-memory-store";
+    HookEvent["PostMemoryStore"] = "hook:post-memory-store";
+    HookEvent["PreMemoryRetrieve"] = "hook:pre-memory-retrieve";
+    HookEvent["PostMemoryRetrieve"] = "hook:post-memory-retrieve";
+    // Error hooks
+    HookEvent["OnError"] = "hook:on-error";
+    HookEvent["OnWarning"] = "hook:on-warning";
+})(HookEvent || (HookEvent = {}));
+/**
+ * Hook priority levels (higher = earlier execution)
+ */
+export var HookPriority;
+(function (HookPriority) {
+    HookPriority[HookPriority["Critical"] = 1000] = "Critical";
+    HookPriority[HookPriority["High"] = 500] = "High";
+    HookPriority[HookPriority["Normal"] = 0] = "Normal";
+    HookPriority[HookPriority["Low"] = -500] = "Low";
+    HookPriority[HookPriority["Lowest"] = -1000] = "Lowest";
+})(HookPriority || (HookPriority = {}));
+//# sourceMappingURL=types.js.map

package/v3/@claude-flow/shared/dist/hooks/verify-exports.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * V3 Hooks System - Export Verification
+ *
+ * Verifies that all exports are accessible through the public API.
+ *
+ * @module v3/shared/hooks/verify-exports.test
+ */
+export {};
+//# sourceMappingURL=verify-exports.test.d.ts.map

package/v3/@claude-flow/shared/dist/hooks/verify-exports.test.js

@@ -0,0 +1,93 @@
+/**
+ * V3 Hooks System - Export Verification
+ *
+ * Verifies that all exports are accessible through the public API.
+ *
+ * @module v3/shared/hooks/verify-exports.test
+ */
+import { describe, it, expect } from 'vitest';
+describe('Hooks Module Exports', () => {
+    it('should export all types from main module', async () => {
+        const module = await import('./index.js');
+        // Enums
+        expect(module.HookEvent).toBeDefined();
+        expect(module.HookPriority).toBeDefined();
+        // Classes
+        expect(module.HookRegistry).toBeDefined();
+        expect(module.HookExecutor).toBeDefined();
+        // Factory functions
+        expect(module.createHookRegistry).toBeDefined();
+        expect(module.createHookExecutor).toBeDefined();
+    });
+    it('should export types (type-only imports)', () => {
+        expect(true).toBe(true);
+    });
+    it('should create instances from exported factories', async () => {
+        const { createHookRegistry, createHookExecutor } = await import('./index.js');
+        const registry = createHookRegistry();
+        expect(registry).toBeDefined();
+        expect(typeof registry.register).toBe('function');
+        expect(typeof registry.unregister).toBe('function');
+        const executor = createHookExecutor(registry);
+        expect(executor).toBeDefined();
+        expect(typeof executor.execute).toBe('function');
+    });
+    it('should have all 26 hook events defined', async () => {
+        const { HookEvent } = await import('./index.js');
+        const expectedEvents = [
+            'PreToolUse',
+            'PostToolUse',
+            'PreEdit',
+            'PostEdit',
+            'PreRead',
+            'PostRead',
+            'PreWrite',
+            'PostWrite',
+            'PreCommand',
+            'PostCommand',
+            'SessionStart',
+            'SessionEnd',
+            'SessionPause',
+            'SessionResume',
+            'PreAgentSpawn',
+            'PostAgentSpawn',
+            'PreAgentTerminate',
+            'PostAgentTerminate',
+            'PreTaskExecute',
+            'PostTaskExecute',
+            'PreTaskComplete',
+            'PostTaskComplete',
+            'PreMemoryStore',
+            'PostMemoryStore',
+            'PreMemoryRetrieve',
+            'PostMemoryRetrieve',
+            'OnError',
+            'OnWarning',
+        ];
+        for (const event of expectedEvents) {
+            expect(HookEvent[event]).toBeDefined();
+        }
+    });
+    it('should have all 5 priority levels defined', async () => {
+        const { HookPriority } = await import('./index.js');
+        expect(HookPriority.Critical).toBe(1000);
+        expect(HookPriority.High).toBe(500);
+        expect(HookPriority.Normal).toBe(0);
+        expect(HookPriority.Low).toBe(-500);
+        expect(HookPriority.Lowest).toBe(-1000);
+    });
+});
+describe('Hooks Integration with Shared Module', () => {
+    it('should be importable from @claude-flow/shared', async () => {
+        // This would be the actual import path in production
+        const module = await import('../index.js');
+        // Verify hooks are exported from main shared module
+        expect(module.HookEvent).toBeDefined();
+        expect(module.HookPriority).toBeDefined();
+        expect(module.HookRegistry).toBeDefined();
+        expect(module.HookExecutor).toBeDefined();
+        expect(module.createHookRegistry).toBeDefined();
+        expect(module.createHookExecutor).toBeDefined();
+    });
+});
+//# sourceMappingURL=verify-exports.test.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * @claude-flow/shared - Shared Module
+ * Common types, events, utilities, and core interfaces for V3 Claude-Flow
+ *
+ * Based on ADR-002 (DDD) and ADR-006 (Unified Memory Service)
+ */
+export * from './types.js';
+export { EventBus } from './events.js';
+export type { IEventBus, EventFilter } from './events.js';
+export type { DomainEvent, AllDomainEvents, AgentSpawnedEvent, AgentStartedEvent, AgentStoppedEvent, AgentFailedEvent, AgentStatusChangedEvent, AgentTaskAssignedEvent, AgentTaskCompletedEvent, TaskCreatedEvent, TaskStartedEvent, TaskCompletedEvent, TaskFailedEvent, TaskBlockedEvent, TaskQueuedEvent, MemoryStoredEvent, MemoryRetrievedEvent, MemoryDeletedEvent, MemoryExpiredEvent, SwarmInitializedEvent, SwarmScaledEvent, SwarmTerminatedEvent, SwarmPhaseChangedEvent, SwarmMilestoneReachedEvent, SwarmErrorEvent, EventStoreConfig, EventSnapshot, EventStoreStats, AgentProjectionState, TaskProjectionState, MemoryProjectionState, AggregateRoot, ReconstructorOptions, } from './events/index.js';
+export { createAgentSpawnedEvent, createAgentStartedEvent, createAgentStoppedEvent, createAgentFailedEvent, createTaskCreatedEvent, createTaskStartedEvent, createTaskCompletedEvent, createTaskFailedEvent, createMemoryStoredEvent, createMemoryRetrievedEvent, createMemoryDeletedEvent, createSwarmInitializedEvent, createSwarmScaledEvent, createSwarmTerminatedEvent, EventStore, Projection, AgentStateProjection, TaskHistoryProjection, MemoryIndexProjection, StateReconstructor, createStateReconstructor, AgentAggregate, TaskAggregate, } from './events/index.js';
+export * from './plugin-loader.js';
+export * from './plugin-registry.js';
+export { createEventBus, createOrchestrator, TaskManager, SessionManager, HealthMonitor, LifecycleManager, EventCoordinator, ConfigLoader, loadConfig, ConfigValidator, validateAgentConfig, validateTaskConfig, validateSwarmConfig, validateMemoryConfig, validateMCPServerConfig, validateOrchestratorConfig, validateSystemConfig, defaultAgentConfig, defaultTaskConfig, defaultSwarmConfigCore, defaultMemoryConfig, defaultMCPServerConfig, defaultOrchestratorConfig, defaultSystemConfig, agentTypePresets, mergeWithDefaults, } from './core/index.js';
+export type { LoadedConfig, ConfigSource, ValidationResult, ValidationError, OrchestratorFacadeConfig, OrchestratorComponents, SessionManagerConfig, HealthMonitorConfig, LifecycleManagerConfig, AgentConfig, TaskConfig, SwarmConfig as SwarmConfigSchema, MemoryConfig, MCPServerConfig, OrchestratorConfig, SystemConfig, AgentConfigInput, TaskConfigInput, SwarmConfigInput, MemoryConfigInput, MCPServerConfigInput, OrchestratorConfigInput, SystemConfigInput, ITask, ITaskCreate, ITaskResult, IAgent, IAgentConfig, IEventBus as ICoreEventBus, IMemoryBackend as ICoreMemoryBackend, ISwarmConfig, ISwarmState, ICoordinator, ICoordinationManager, IHealthStatus, IComponentHealth, IHealthMonitor, IMetricsCollector, IOrchestratorMetrics, IOrchestrator, SwarmTopology, CoordinationStatus, } from './core/index.js';
+export * from './hooks/index.js';
+export * from './security/index.js';
+export * from './resilience/index.js';
+export * from './services/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,50 @@
+/**
+ * @claude-flow/shared - Shared Module
+ * Common types, events, utilities, and core interfaces for V3 Claude-Flow
+ *
+ * Based on ADR-002 (DDD) and ADR-006 (Unified Memory Service)
+ */
+// =============================================================================
+// Types - Primary type definitions (from ./types.js)
+// =============================================================================
+export * from './types.js';
+// =============================================================================
+// Events - Event bus and basic event interfaces (from ./events.js)
+// =============================================================================
+export { EventBus } from './events.js';
+export { createAgentSpawnedEvent, createAgentStartedEvent, createAgentStoppedEvent, createAgentFailedEvent, createTaskCreatedEvent, createTaskStartedEvent, createTaskCompletedEvent, createTaskFailedEvent, createMemoryStoredEvent, createMemoryRetrievedEvent, createMemoryDeletedEvent, createSwarmInitializedEvent, createSwarmScaledEvent, createSwarmTerminatedEvent, EventStore, Projection, AgentStateProjection, TaskHistoryProjection, MemoryIndexProjection, StateReconstructor, createStateReconstructor, AgentAggregate, TaskAggregate, } from './events/index.js';
+// =============================================================================
+// Plugin System - ADR-004
+// =============================================================================
+export * from './plugin-loader.js';
+export * from './plugin-registry.js';
+// =============================================================================
+// Core - DDD interfaces, config, orchestrator
+// Note: Only export non-overlapping items from core to avoid duplicates with types.js
+// =============================================================================
+export { 
+// Event Bus
+createEventBus, 
+// Orchestrator
+createOrchestrator, TaskManager, SessionManager, HealthMonitor, LifecycleManager, EventCoordinator, 
+// Config validation/loading
+ConfigLoader, loadConfig, ConfigValidator, validateAgentConfig, validateTaskConfig, validateSwarmConfig, validateMemoryConfig, validateMCPServerConfig, validateOrchestratorConfig, validateSystemConfig, 
+// Defaults
+defaultAgentConfig, defaultTaskConfig, defaultSwarmConfigCore, defaultMemoryConfig, defaultMCPServerConfig, defaultOrchestratorConfig, defaultSystemConfig, agentTypePresets, mergeWithDefaults, } from './core/index.js';
+// =============================================================================
+// Hooks System
+// =============================================================================
+export * from './hooks/index.js';
+// =============================================================================
+// Security Utilities
+// =============================================================================
+export * from './security/index.js';
+// =============================================================================
+// Resilience Patterns
+// =============================================================================
+export * from './resilience/index.js';
+// =============================================================================
+// Services
+// =============================================================================
+export * from './services/index.js';
+//# sourceMappingURL=index.js.map

package/v3/@claude-flow/shared/dist/mcp/connection-pool.d.ts

@@ -0,0 +1,98 @@
+/**
+ * V3 MCP Connection Pool Manager
+ *
+ * High-performance connection pooling for MCP server:
+ * - Reusable connections to reduce overhead
+ * - Max connections: 10 (configurable)
+ * - Idle timeout handling with automatic eviction
+ * - Connection health monitoring
+ * - Graceful shutdown support
+ *
+ * Performance Targets:
+ * - Connection acquire: <5ms
+ * - Connection release: <1ms
+ */
+import { EventEmitter } from 'events';
+import { PooledConnection, ConnectionPoolStats, ConnectionPoolConfig, IConnectionPool, ILogger, TransportType } from './types.js';
+/**
+ * Connection Pool Manager
+ *
+ * Manages a pool of reusable connections for optimal performance
+ */
+export declare class ConnectionPool extends EventEmitter implements IConnectionPool {
+    private readonly logger;
+    private readonly transportType;
+    private readonly config;
+    private readonly connections;
+    private readonly waitingClients;
+    private evictionTimer?;
+    private connectionCounter;
+    private isShuttingDown;
+    private stats;
+    constructor(config: Partial<ConnectionPoolConfig> | undefined, logger: ILogger, transportType?: TransportType);
+    /**
+     * Initialize minimum number of connections
+     */
+    private initializeMinConnections;
+    /**
+     * Create a new connection
+     */
+    private createConnection;
+    /**
+     * Acquire a connection from the pool
+     */
+    acquire(): Promise<PooledConnection>;
+    /**
+     * Wait for a connection to become available
+     */
+    private waitForConnection;
+    /**
+     * Release a connection back to the pool
+     */
+    release(connection: PooledConnection): void;
+    /**
+     * Destroy a connection (remove from pool)
+     */
+    destroy(connection: PooledConnection): void;
+    /**
+     * Get pool statistics
+     */
+    getStats(): ConnectionPoolStats;
+    /**
+     * Drain the pool (wait for all connections to be released)
+     */
+    drain(): Promise<void>;
+    /**
+     * Clear all connections from the pool
+     */
+    clear(): Promise<void>;
+    /**
+     * Start the eviction timer
+     */
+    private startEvictionTimer;
+    /**
+     * Stop the eviction timer
+     */
+    private stopEvictionTimer;
+    /**
+     * Evict idle connections that have exceeded the timeout
+     */
+    private evictIdleConnections;
+    /**
+     * Record acquire time for statistics
+     */
+    private recordAcquireTime;
+    /**
+     * Get all connections (for debugging/monitoring)
+     */
+    getConnections(): PooledConnection[];
+    /**
+     * Check if pool is healthy
+     */
+    isHealthy(): boolean;
+}
+/**
+ * Create a connection pool with default settings
+ */
+export declare function createConnectionPool(config: Partial<ConnectionPoolConfig> | undefined, logger: ILogger, transportType?: TransportType): ConnectionPool;
+//# sourceMappingURL=connection-pool.d.ts.map