claude-flow 2.0.0-alpha.62 → 2.0.0-alpha.63

package/src/api/claude-client.ts

@@ -7,6 +7,19 @@ import { EventEmitter } from 'events';
 import { ILogger } from '../core/logger.js';
 import { ConfigManager } from '../config/config-manager.js';
 import { getErrorMessage } from '../utils/error-handler.js';
+import { 
+  ClaudeAPIError,
+  ClaudeInternalServerError,
+  ClaudeServiceUnavailableError,
+  ClaudeRateLimitError,
+  ClaudeTimeoutError,
+  ClaudeNetworkError,
+  ClaudeAuthenticationError,
+  ClaudeValidationError,
+  HealthCheckResult,
+  getUserFriendlyError,
+} from './claude-api-errors.js';
+import { circuitBreaker, CircuitBreaker } from '../utils/helpers.js';
 
 export interface ClaudeAPIConfig {
   apiKey: string;
@@ -20,6 +33,13 @@ export interface ClaudeAPIConfig {
   timeout?: number;
   retryAttempts?: number;
   retryDelay?: number;
+  // Enhanced error handling options
+  enableHealthCheck?: boolean;
+  healthCheckInterval?: number;
+  circuitBreakerThreshold?: number;
+  circuitBreakerTimeout?: number;
+  circuitBreakerResetTimeout?: number;
+  retryJitter?: boolean;
 }
 
 export type ClaudeModel =
@@ -105,6 +125,9 @@ export class ClaudeAPIClient extends EventEmitter {
   private defaultModel: ClaudeModel = 'claude-3-sonnet-20240229';
   private defaultTemperature: number = 0.7;
   private defaultMaxTokens: number = 4096;
+  private circuitBreaker: CircuitBreaker;
+  private lastHealthCheck?: HealthCheckResult;
+  private healthCheckTimer?: NodeJS.Timeout;
 
   constructor(logger: ILogger, configManager: ConfigManager, config?: Partial<ClaudeAPIConfig>) {
     super();
@@ -113,6 +136,18 @@ export class ClaudeAPIClient extends EventEmitter {
 
     // Load config from environment and merge with provided config
     this.config = this.loadConfiguration(config);
+    
+    // Initialize circuit breaker for API reliability
+    this.circuitBreaker = circuitBreaker('claude-api', {
+      threshold: this.config.circuitBreakerThreshold || 5,
+      timeout: this.config.circuitBreakerTimeout || 60000,
+      resetTimeout: this.config.circuitBreakerResetTimeout || 300000,
+    });
+
+    // Start health check if enabled
+    if (this.config.enableHealthCheck) {
+      this.startHealthCheck();
+    }
   }
 
   /**
@@ -132,6 +167,13 @@ export class ClaudeAPIClient extends EventEmitter {
       timeout: 60000, // 60 seconds
       retryAttempts: 3,
       retryDelay: 1000,
+      // Enhanced error handling defaults
+      enableHealthCheck: false,
+      healthCheckInterval: 300000, // 5 minutes
+      circuitBreakerThreshold: 5,
+      circuitBreakerTimeout: 60000,
+      circuitBreakerResetTimeout: 300000,
+      retryJitter: true,
     };
 
     // Load from environment variables
@@ -173,23 +215,23 @@ export class ClaudeAPIClient extends EventEmitter {
    */
   private validateConfiguration(config: ClaudeAPIConfig): void {
     if (!config.apiKey) {
-      throw new Error('Claude API key is required. Set ANTHROPIC_API_KEY environment variable.');
+      throw new ClaudeAuthenticationError('Claude API key is required. Set ANTHROPIC_API_KEY environment variable.');
     }
 
     if (config.temperature !== undefined) {
       if (config.temperature < 0 || config.temperature > 1) {
-        throw new Error('Temperature must be between 0 and 1');
+        throw new ClaudeValidationError('Temperature must be between 0 and 1');
       }
     }
 
     if (config.topP !== undefined) {
       if (config.topP < 0 || config.topP > 1) {
-        throw new Error('Top-p must be between 0 and 1');
+        throw new ClaudeValidationError('Top-p must be between 0 and 1');
       }
     }
 
     if (config.maxTokens !== undefined && (config.maxTokens < 1 || config.maxTokens > 100000)) {
-      throw new Error('Max tokens must be between 1 and 100000');
+      throw new ClaudeValidationError('Max tokens must be between 1 and 100000');
     }
   }
 
@@ -256,7 +298,7 @@ export class ClaudeAPIClient extends EventEmitter {
    * Send a non-streaming request
    */
   private async sendRequest(request: ClaudeRequest): Promise<ClaudeResponse> {
-    let lastError: Error | undefined;
+    let lastError: ClaudeAPIError | undefined;
 
     for (let attempt = 0; attempt < (this.config.retryAttempts || 3); attempt++) {
       try {
@@ -277,8 +319,16 @@ export class ClaudeAPIClient extends EventEmitter {
         clearTimeout(timeout);
 
         if (!response.ok) {
-          const error = await response.text();
-          throw new Error(`Claude API error (${response.status}): ${error}`);
+          const errorText = await response.text();
+          let errorData: any;
+          
+          try {
+            errorData = JSON.parse(errorText);
+          } catch {
+            errorData = { message: errorText };
+          }
+
+          throw this.createAPIError(response.status, errorData);
         }
 
         const data = (await response.json()) as ClaudeResponse;
@@ -293,21 +343,31 @@ export class ClaudeAPIClient extends EventEmitter {
         this.emit('response', data);
         return data;
       } catch (error) {
-        lastError = error as Error;
+        lastError = this.transformError(error);
+        
+        // Don't retry non-retryable errors
+        if (!lastError.retryable) {
+          this.handleError(lastError);
+          throw lastError;
+        }
+
         this.logger.warn(
           `Claude API request failed (attempt ${attempt + 1}/${this.config.retryAttempts})`,
           {
-            error: getErrorMessage(error),
+            error: lastError.message,
+            statusCode: lastError.statusCode,
+            retryable: lastError.retryable,
           },
         );
 
         if (attempt < (this.config.retryAttempts || 3) - 1) {
-          await this.delay((this.config.retryDelay || 1000) * Math.pow(2, attempt));
+          const delay = this.calculateRetryDelay(attempt, lastError);
+          await this.delay(delay);
         }
       }
     }
 
-    this.emit('error', lastError);
+    this.handleError(lastError!);
     throw lastError;
   }
 
@@ -331,12 +391,20 @@ export class ClaudeAPIClient extends EventEmitter {
       });
 
       if (!response.ok) {
-        const error = await response.text();
-        throw new Error(`Claude API error (${response.status}): ${error}`);
+        const errorText = await response.text();
+        let errorData: any;
+        
+        try {
+          errorData = JSON.parse(errorText);
+        } catch {
+          errorData = { message: errorText };
+        }
+
+        throw this.createAPIError(response.status, errorData);
       }
 
       if (!response.body) {
-        throw new Error('Response body is null');
+        throw new ClaudeAPIError('Response body is null');
       }
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -365,6 +433,18 @@ export class ClaudeAPIClient extends EventEmitter {
           }
         }
       }
+    } catch (error) {
+      clearTimeout(timeout);
+      
+      // Handle abort/timeout
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new ClaudeTimeoutError(
+          'Request timed out',
+          this.config.timeout || 60000,
+        );
+      }
+      
+      throw error;
     } finally {
       clearTimeout(timeout);
     }
@@ -485,4 +565,192 @@ export class ClaudeAPIClient extends EventEmitter {
   private delay(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+
+  /**
+   * Start periodic health checks
+   */
+  private startHealthCheck(): void {
+    this.performHealthCheck(); // Initial check
+    
+    this.healthCheckTimer = setInterval(
+      () => this.performHealthCheck(),
+      this.config.healthCheckInterval || 300000,
+    );
+  }
+
+  /**
+   * Perform a health check on the API
+   */
+  async performHealthCheck(): Promise<HealthCheckResult> {
+    const startTime = Date.now();
+    
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 10000); // 10 second timeout
+
+      const response = await fetch(this.config.apiUrl || '', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'anthropic-version': '2023-06-01',
+          'x-api-key': this.config.apiKey,
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          messages: [{ role: 'user', content: 'Hi' }],
+          max_tokens: 1,
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+      
+      const latency = Date.now() - startTime;
+      const healthy = response.ok || response.status === 429; // Rate limit is still "healthy"
+      
+      this.lastHealthCheck = {
+        healthy,
+        latency,
+        error: healthy ? undefined : `Status: ${response.status}`,
+        timestamp: new Date(),
+      };
+
+      this.logger.debug('Claude API health check completed', this.lastHealthCheck);
+      this.emit('health_check', this.lastHealthCheck);
+      
+      return this.lastHealthCheck;
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      
+      this.lastHealthCheck = {
+        healthy: false,
+        latency,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        timestamp: new Date(),
+      };
+
+      this.logger.warn('Claude API health check failed', this.lastHealthCheck);
+      this.emit('health_check', this.lastHealthCheck);
+      
+      return this.lastHealthCheck;
+    }
+  }
+
+  /**
+   * Get last health check result
+   */
+  getHealthStatus(): HealthCheckResult | undefined {
+    return this.lastHealthCheck;
+  }
+
+  /**
+   * Create appropriate error based on status code
+   */
+  private createAPIError(statusCode: number, errorData: any): ClaudeAPIError {
+    const message = errorData.error?.message || errorData.message || 'Unknown error';
+
+    switch (statusCode) {
+      case 400:
+        return new ClaudeValidationError(message, errorData);
+      case 401:
+      case 403:
+        return new ClaudeAuthenticationError(message, errorData);
+      case 429:
+        const retryAfter = errorData.error?.retry_after;
+        return new ClaudeRateLimitError(message, retryAfter, errorData);
+      case 500:
+        return new ClaudeInternalServerError(message, errorData);
+      case 503:
+        return new ClaudeServiceUnavailableError(message, errorData);
+      default:
+        return new ClaudeAPIError(message, statusCode, statusCode >= 500, errorData);
+    }
+  }
+
+  /**
+   * Transform generic errors to Claude API errors
+   */
+  private transformError(error: unknown): ClaudeAPIError {
+    if (error instanceof ClaudeAPIError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      // Network errors
+      if (error.message.includes('fetch failed') || error.message.includes('ECONNREFUSED')) {
+        return new ClaudeNetworkError(error.message);
+      }
+      
+      // Timeout errors
+      if (error.name === 'AbortError' || error.message.includes('timeout')) {
+        return new ClaudeTimeoutError(error.message, this.config.timeout || 60000);
+      }
+    }
+
+    return new ClaudeAPIError(
+      error instanceof Error ? error.message : String(error),
+      undefined,
+      true, // Assume unknown errors are retryable
+    );
+  }
+
+  /**
+   * Calculate retry delay with exponential backoff and jitter
+   */
+  private calculateRetryDelay(attempt: number, error: ClaudeAPIError): number {
+    // If rate limit error with retry-after header, use that
+    if (error instanceof ClaudeRateLimitError && error.retryAfter) {
+      return error.retryAfter * 1000; // Convert to milliseconds
+    }
+
+    const baseDelay = this.config.retryDelay || 1000;
+    const maxDelay = 30000; // 30 seconds max
+    
+    // Exponential backoff: delay = baseDelay * (2 ^ attempt)
+    let delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+    
+    // Add jitter to prevent thundering herd
+    if (this.config.retryJitter) {
+      const jitter = Math.random() * 0.3 * delay; // Up to 30% jitter
+      delay = delay + jitter;
+    }
+
+    return Math.floor(delay);
+  }
+
+  /**
+   * Handle errors with user-friendly messages and logging
+   */
+  private handleError(error: ClaudeAPIError): void {
+    const errorInfo = getUserFriendlyError(error);
+    
+    this.logger.error(`${errorInfo.title}: ${errorInfo.message}`, {
+      error: error.message,
+      code: error.code,
+      statusCode: error.statusCode,
+      retryable: error.retryable,
+      details: error.details,
+    });
+
+    // Log suggestions in debug mode
+    if (this.logger.level === 'debug' && errorInfo.suggestions.length > 0) {
+      this.logger.debug('Suggestions to resolve the issue:', errorInfo.suggestions);
+    }
+
+    this.emit('error', {
+      error,
+      userFriendly: errorInfo,
+    });
+  }
+
+  /**
+   * Clean up resources
+   */
+  destroy(): void {
+    if (this.healthCheckTimer) {
+      clearInterval(this.healthCheckTimer);
+      this.healthCheckTimer = undefined;
+    }
+    this.removeAllListeners();
+  }
 }

package/src/cli/help-text.js

@@ -458,7 +458,8 @@ SWARM-INIT OPTIONS:
 
 AGENT-SPAWN OPTIONS:
   --type <type>        Agent type (default: general)
-                       Options: coordinator, developer, researcher, analyzer, tester, general
+                       Options: coordinator, coder, developer, researcher, analyst, analyzer, 
+                       tester, architect, reviewer, optimizer, general
   --name <name>        Custom agent name (auto-generated if not provided)
   --swarm-id <id>      Target swarm for agent coordination
   --capabilities <cap> Custom capabilities specification

package/src/cli/simple-commands/coordination.js

@@ -56,69 +56,87 @@ async function swarmInitCommand(subArgs, flags) {
 
   // Check if ruv-swarm is available
   const isAvailable = await checkRuvSwarmAvailable();
+  
+  if (isAvailable) {
+    try {
+      console.log(`\n🔄 Initializing real swarm with ruv-swarm...`);
+
+      // Use real ruv-swarm initialization
+      const swarmResult = await callRuvSwarmMCP('swarm_init', {
+        swarmId: swarmId,
+        topology: topology,
+        maxAgents: maxAgents,
+        strategy: strategy,
+        timestamp: Date.now(),
+      });
+
+      if (swarmResult.success) {
+        printSuccess(`✅ Swarm coordination initialized successfully`);
+
+        console.log(`\n🎯 COORDINATION SETUP COMPLETE:`);
+        console.log(`  🐝 Swarm: ${swarmId}`);
+        console.log(`  🏗️  Topology: ${topology}`);
+        console.log(`  📊 Capacity: ${maxAgents} agents`);
+        console.log(`  💾 Memory: ${swarmResult.memoryStatus || 'Active'}`);
+        console.log(`  🔗 Channels: ${swarmResult.communicationChannels || 'Established'}`);
+        console.log(`  📈 Performance: ${swarmResult.expectedPerformance || 'Optimized'}`);
+      } else {
+        printError(`Swarm initialization failed: ${swarmResult.error || 'Unknown error'}`);
+      }
+    } catch (err) {
+      printError(`Swarm initialization failed: ${err.message}`);
+      console.log('Falling back to local coordination...');
+      isAvailable = false; // Trigger fallback
+    }
+  }
+  
   if (!isAvailable) {
-    printError('ruv-swarm is not available. Please install it with: npm install -g ruv-swarm');
-    return;
+    // Fallback: Initialize coordination without ruv-swarm
+    console.log(`\n🔄 Initializing local swarm coordination...`);
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    printSuccess(`✅ Local swarm coordination initialized successfully`);
+
+    console.log(`\n🎯 COORDINATION SETUP COMPLETE:`);
+    console.log(`  🐝 Swarm: ${swarmId}`);
+    console.log(`  🏗️  Topology: ${topology}`);
+    console.log(`  📊 Capacity: ${maxAgents} agents`);
+    console.log(`  💾 Memory: Local (in-memory)`);
+    console.log(`  🔗 Channels: Local coordination`);
+    console.log(`  📈 Performance: Standard`);
+    console.log(`  ⚠️  Note: Using local coordination (ruv-swarm not available)`);
   }
 
-  try {
-    console.log(`\n🔄 Initializing real swarm with ruv-swarm...`);
-
-    // Use real ruv-swarm initialization
-    const swarmResult = await callRuvSwarmMCP('swarm_init', {
-      swarmId: swarmId,
-      topology: topology,
-      maxAgents: maxAgents,
-      strategy: strategy,
-      timestamp: Date.now(),
-    });
-
-    if (swarmResult.success) {
-      printSuccess(`✅ Swarm coordination initialized successfully`);
-
-      console.log(`\n🎯 COORDINATION SETUP COMPLETE:`);
-      console.log(`  🐝 Swarm: ${swarmId}`);
-      console.log(`  🏗️  Topology: ${topology}`);
-      console.log(`  📊 Capacity: ${maxAgents} agents`);
-      console.log(`  💾 Memory: ${swarmResult.memoryStatus || 'Active'}`);
-      console.log(`  🔗 Channels: ${swarmResult.communicationChannels || 'Established'}`);
-      console.log(`  📈 Performance: ${swarmResult.expectedPerformance || 'Optimized'}`);
-
-      console.log(`\n📋 NEXT STEPS:`);
-      console.log(
-        `  1. Spawn agents: claude-flow coordination agent-spawn --type <type> --swarm-id ${swarmId}`,
-      );
-      console.log(
-        `  2. Orchestrate tasks: claude-flow coordination task-orchestrate --task "<description>" --swarm-id ${swarmId}`,
-      );
-      console.log(`  3. Monitor swarm: claude-flow monitoring swarm-monitor --swarm-id ${swarmId}`);
-    } else {
-      printError(`Swarm initialization failed: ${swarmResult.error || 'Unknown error'}`);
-    }
-  } catch (err) {
-    printError(`Swarm initialization failed: ${err.message}`);
-    console.log('Check ruv-swarm installation and try again.');
-  }
+  console.log(`\n📋 NEXT STEPS:`);
+  console.log(
+    `  1. Spawn agents: claude-flow coordination agent-spawn --type <type> --swarm-id ${swarmId}`,
+  );
+  console.log(
+    `  2. Orchestrate tasks: claude-flow coordination task-orchestrate --task "<description>" --swarm-id ${swarmId}`,
+  );
+  console.log(`  3. Monitor swarm: claude-flow monitoring swarm-monitor --swarm-id ${swarmId}`);
 }
 
 async function agentSpawnCommand(subArgs, flags) {
   const options = flags;
-  const agentType = options.type || subArgs[1] || 'general';
-  const agentName = options.name || `${agentType}-${generateId('agent')}`;
+  let agentType = options.type || subArgs[1] || 'general';
   const swarmId = options['swarm-id'] || options.swarmId;
   const capabilities = options.capabilities || null;
 
-  console.log(`🤖 Spawning coordinated agent...`);
-  console.log(`🏷️  Agent type: ${agentType}`);
-  console.log(`📛 Agent name: ${agentName}`);
-  if (swarmId) console.log(`🐝 Target swarm: ${swarmId}`);
-
   // Validate agent type
-  const validTypes = ['coordinator', 'coder', 'researcher', 'analyst', 'tester', 'general'];
+  const validTypes = ['coordinator', 'coder', 'developer', 'researcher', 'analyst', 'analyzer', 'tester', 'architect', 'reviewer', 'optimizer', 'general'];
   if (!validTypes.includes(agentType)) {
     printWarning(`⚠️  Unknown agent type '${agentType}'. Using 'general' instead.`);
+    agentType = 'general'; // Actually change the type to general
   }
 
+  const agentName = options.name || `${agentType}-${generateId('agent')}`;
+
+  console.log(`🤖 Spawning coordinated agent...`);
+  console.log(`🏷️  Agent type: ${agentType}`);
+  console.log(`📛 Agent name: ${agentName}`);
+  if (swarmId) console.log(`🐝 Target swarm: ${swarmId}`);
+
   // Simulate agent spawning process
   console.log(`\n🔄 Initializing agent coordination protocols...`);
   await new Promise((resolve) => setTimeout(resolve, 800));
@@ -207,10 +225,15 @@ async function taskOrchestrateCommand(subArgs, flags) {
 function getAgentCapabilities(type) {
   const capabilities = {
     coordinator: 'Task orchestration, agent management, workflow coordination',
+    coder: 'Code implementation, debugging, technical development',
     developer: 'Code implementation, debugging, technical development',
     researcher: 'Information gathering, analysis, documentation',
+    analyst: 'Data analysis, performance monitoring, metrics',
     analyzer: 'Data analysis, performance monitoring, metrics',
     tester: 'Quality assurance, test automation, validation',
+    architect: 'System design, architecture planning, technical strategy',
+    reviewer: 'Code review, quality assessment, best practices',
+    optimizer: 'Performance optimization, efficiency improvement, bottleneck analysis',
     general: 'Multi-purpose coordination and development',
   };
   return capabilities[type] || capabilities.general;
@@ -236,7 +259,8 @@ SWARM-INIT OPTIONS:
 
 AGENT-SPAWN OPTIONS:
   --type <type>        Agent type (default: general)
-                       Options: coordinator, developer, researcher, analyzer, tester, general
+                       Options: coordinator, coder, developer, researcher, analyst, analyzer, 
+                       tester, architect, reviewer, optimizer, general
   --name <name>        Custom agent name (auto-generated if not provided)
   --swarm-id <id>      Target swarm for agent coordination
   --capabilities <cap> Custom capabilities specification

package/src/cli/simple-commands/hive-mind/auto-save-middleware.js

@@ -6,10 +6,10 @@
 import { HiveMindSessionManager } from './session-manager.js';
 
 export class AutoSaveMiddleware {
-  constructor(sessionId, saveInterval = 30000) {
+  constructor(sessionId, sessionManager, saveInterval = 30000) {
     this.sessionId = sessionId;
     this.saveInterval = saveInterval;
-    this.sessionManager = new HiveMindSessionManager();
+    this.sessionManager = sessionManager; // Use provided session manager
     this.saveTimer = null;
     this.pendingChanges = [];
     this.isActive = false;
@@ -178,7 +178,7 @@ export class AutoSaveMiddleware {
 
       // Update session progress
       if (completionPercentage > 0) {
-        this.sessionManager.updateSessionProgress(this.sessionId, completionPercentage);
+        await this.sessionManager.updateSessionProgress(this.sessionId, completionPercentage);
       }
 
       // Log all changes as session events
@@ -278,7 +278,7 @@ export class AutoSaveMiddleware {
       this.childProcesses.clear();
 
       // Stop the session if it's still active
-      const session = this.sessionManager.getSession(this.sessionId);
+      const session = await this.sessionManager.getSession(this.sessionId);
       if (session && (session.status === 'active' || session.status === 'paused')) {
         await this.sessionManager.stopSession(this.sessionId);
       }
@@ -296,9 +296,9 @@ export class AutoSaveMiddleware {
 /**
  * Create auto-save middleware for a session
  */
-export function createAutoSaveMiddleware(sessionId, options = {}) {
+export function createAutoSaveMiddleware(sessionId, sessionManager, options = {}) {
   const saveInterval = options.saveInterval || 30000; // Default 30 seconds
-  const middleware = new AutoSaveMiddleware(sessionId, saveInterval);
+  const middleware = new AutoSaveMiddleware(sessionId, sessionManager, saveInterval);
 
   if (options.autoStart !== false) {
     middleware.start();