claude-flow 2.0.0-alpha.71 → 2.0.0-alpha.73

package/src/swarm/claude-code-interface.ts

@@ -0,0 +1,1268 @@
+/**
+ * Claude Code Coordination Interface
+ * 
+ * This module provides the interface layer for coordinating with Claude Code
+ * instances, managing agent spawning through the claude CLI, handling process
+ * lifecycle, and enabling seamless communication between the swarm system
+ * and individual Claude agents.
+ */
+
+import { EventEmitter } from 'node:events';
+import { spawn, ChildProcess } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { Logger } from '../core/logger.js';
+import { generateId } from '../utils/helpers.js';
+import { MemoryManager } from '../memory/manager.js';
+import TaskExecutor, { 
+  ClaudeExecutionOptions,
+  ExecutionResult,
+  ExecutionContext
+} from './executor.js';
+import {
+  SwarmAgent,
+  SwarmTask,
+  TaskDefinition,
+  AgentState,
+  AgentCapabilities,
+  TaskResult,
+  SwarmExecutionContext,
+} from './types.js';
+
+export interface ClaudeCodeConfig {
+  claudeExecutablePath: string;
+  defaultModel: string;
+  maxTokens: number;
+  temperature: number;
+  timeout: number;
+  maxConcurrentAgents: number;
+  enableStreaming: boolean;
+  enableLogging: boolean;
+  workingDirectory: string;
+  environmentVariables: Record<string, string>;
+  agentPoolSize: number;
+  processRecycling: boolean;
+  healthCheckInterval: number;
+}
+
+export interface ClaudeAgent {
+  id: string;
+  processId: number;
+  process: ChildProcess;
+  type: string;
+  capabilities: string[];
+  status: 'initializing' | 'idle' | 'busy' | 'error' | 'terminated';
+  currentTask?: string;
+  spawnedAt: Date;
+  lastActivity: Date;
+  totalTasks: number;
+  totalDuration: number;
+  metrics: ClaudeAgentMetrics;
+}
+
+export interface ClaudeAgentMetrics {
+  tasksCompleted: number;
+  tasksFailed: number;
+  averageResponseTime: number;
+  totalTokensUsed: number;
+  memoryUsage: number;
+  cpuUsage: number;
+  errorRate: number;
+  successRate: number;
+}
+
+export interface ClaudeTaskExecution {
+  id: string;
+  taskId: string;
+  agentId: string;
+  startTime: Date;
+  endTime?: Date;
+  status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+  input: any;
+  output?: any;
+  error?: string;
+  duration?: number;
+  tokensUsed?: number;
+  retryCount: number;
+  maxRetries: number;
+}
+
+export interface ClaudeSpawnOptions {
+  type: string;
+  name?: string;
+  capabilities?: string[];
+  systemPrompt?: string;
+  model?: string;
+  maxTokens?: number;
+  temperature?: number;
+  workingDirectory?: string;
+  environment?: Record<string, string>;
+  tools?: string[];
+  priority?: number;
+}
+
+export interface ProcessPool {
+  idle: ClaudeAgent[];
+  busy: ClaudeAgent[];
+  failed: ClaudeAgent[];
+  totalSpawned: number;
+  totalTerminated: number;
+  recyclingEnabled: boolean;
+  maxAge: number;
+  maxTasks: number;
+}
+
+export class ClaudeCodeInterface extends EventEmitter {
+  private logger: Logger;
+  private config: ClaudeCodeConfig;
+  private memoryManager: MemoryManager;
+  private processPool: ProcessPool;
+  private activeExecutions: Map<string, ClaudeTaskExecution> = new Map();
+  private agents: Map<string, ClaudeAgent> = new Map();
+  private taskExecutor: TaskExecutor;
+  private healthCheckInterval?: NodeJS.Timeout;
+  private isInitialized: boolean = false;
+
+  constructor(
+    config: Partial<ClaudeCodeConfig> = {},
+    memoryManager: MemoryManager
+  ) {
+    super();
+    
+    this.logger = new Logger('ClaudeCodeInterface');
+    this.config = this.createDefaultConfig(config);
+    this.memoryManager = memoryManager;
+    this.processPool = this.initializeProcessPool();
+    
+    this.taskExecutor = new TaskExecutor({
+      timeoutMs: this.config.timeout,
+      enableMetrics: true,
+      captureOutput: true,
+      streamOutput: this.config.enableStreaming,
+    });
+
+    this.setupEventHandlers();
+  }
+
+  /**
+   * Initialize the Claude Code interface
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) {
+      this.logger.warn('Claude Code interface already initialized');
+      return;
+    }
+
+    this.logger.info('Initializing Claude Code interface...');
+
+    try {
+      // Verify Claude executable exists
+      await this.verifyClaudeExecutable();
+
+      // Initialize task executor
+      await this.taskExecutor.initialize();
+
+      // Pre-warm agent pool if configured
+      if (this.config.agentPoolSize > 0) {
+        await this.prewarmAgentPool();
+      }
+
+      // Start health checks
+      this.startHealthChecks();
+
+      this.isInitialized = true;
+      this.logger.info('Claude Code interface initialized successfully', {
+        poolSize: this.processPool.idle.length,
+        maxConcurrent: this.config.maxConcurrentAgents,
+      });
+
+      this.emit('initialized');
+
+    } catch (error) {
+      this.logger.error('Failed to initialize Claude Code interface', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Shutdown the interface gracefully
+   */
+  async shutdown(): Promise<void> {
+    if (!this.isInitialized) return;
+
+    this.logger.info('Shutting down Claude Code interface...');
+
+    try {
+      // Stop health checks
+      if (this.healthCheckInterval) {
+        clearInterval(this.healthCheckInterval);
+      }
+
+      // Cancel active executions
+      const cancellationPromises = Array.from(this.activeExecutions.keys())
+        .map(executionId => this.cancelExecution(executionId, 'Interface shutdown'));
+      
+      await Promise.allSettled(cancellationPromises);
+
+      // Terminate all agents
+      await this.terminateAllAgents();
+
+      // Shutdown task executor
+      await this.taskExecutor.shutdown();
+
+      this.isInitialized = false;
+      this.logger.info('Claude Code interface shut down successfully');
+      this.emit('shutdown');
+
+    } catch (error) {
+      this.logger.error('Error during Claude Code interface shutdown', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Spawn a new Claude agent with specified configuration
+   */
+  async spawnAgent(options: ClaudeSpawnOptions): Promise<string> {
+    this.logger.info('Spawning Claude agent', {
+      type: options.type,
+      name: options.name,
+      capabilities: options.capabilities,
+    });
+
+    try {
+      // Check if we can spawn more agents
+      if (this.getTotalActiveAgents() >= this.config.maxConcurrentAgents) {
+        throw new Error('Maximum concurrent agents limit reached');
+      }
+
+      // Build Claude command
+      const command = this.buildClaudeCommand(options);
+      
+      // Spawn process
+      const process = spawn(command.executable, command.args, {
+        cwd: options.workingDirectory || this.config.workingDirectory,
+        env: {
+          ...process.env,
+          ...this.config.environmentVariables,
+          ...options.environment,
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: false,
+      });
+
+      if (!process.pid) {
+        throw new Error('Failed to spawn Claude process');
+      }
+
+      // Create agent record
+      const agentId = generateId('claude-agent');
+      const agent: ClaudeAgent = {
+        id: agentId,
+        processId: process.pid,
+        process,
+        type: options.type,
+        capabilities: options.capabilities || [],
+        status: 'initializing',
+        spawnedAt: new Date(),
+        lastActivity: new Date(),
+        totalTasks: 0,
+        totalDuration: 0,
+        metrics: this.initializeAgentMetrics(),
+      };
+
+      this.agents.set(agentId, agent);
+      this.processPool.idle.push(agent);
+      this.processPool.totalSpawned++;
+
+      // Setup process event handlers
+      this.setupProcessEventHandlers(agent);
+
+      // Wait for agent to be ready
+      await this.waitForAgentReady(agent);
+
+      agent.status = 'idle';
+      agent.lastActivity = new Date();
+
+      this.logger.info('Claude agent spawned successfully', {
+        agentId,
+        processId: process.pid,
+        type: options.type,
+      });
+
+      this.emit('agent:spawned', {
+        agentId,
+        type: options.type,
+        processId: process.pid,
+      });
+
+      return agentId;
+
+    } catch (error) {
+      this.logger.error('Failed to spawn Claude agent', {
+        type: options.type,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a task using a Claude agent
+   */
+  async executeTask(
+    taskDefinition: TaskDefinition,
+    agentId?: string,
+    options: Partial<ClaudeExecutionOptions> = {}
+  ): Promise<ClaudeTaskExecution> {
+    const executionId = generateId('claude-execution');
+    
+    this.logger.info('Executing task with Claude agent', {
+      executionId,
+      taskId: taskDefinition.id.id,
+      agentId,
+    });
+
+    try {
+      // Get or select agent
+      const agent = agentId ? this.agents.get(agentId) : await this.selectOptimalAgent(taskDefinition);
+      
+      if (!agent) {
+        throw new Error(agentId ? `Agent not found: ${agentId}` : 'No suitable agent available');
+      }
+
+      if (agent.status !== 'idle') {
+        throw new Error(`Agent ${agent.id} is not available (status: ${agent.status})`);
+      }
+
+      // Create execution record
+      const execution: ClaudeTaskExecution = {
+        id: executionId,
+        taskId: taskDefinition.id.id,
+        agentId: agent.id,
+        startTime: new Date(),
+        status: 'queued',
+        input: {
+          task: taskDefinition,
+          options,
+        },
+        retryCount: 0,
+        maxRetries: options.maxRetries || 3,
+      };
+
+      this.activeExecutions.set(executionId, execution);
+
+      // Update agent status
+      agent.status = 'busy';
+      agent.currentTask = executionId;
+      agent.lastActivity = new Date();
+
+      // Move agent from idle to busy pool
+      this.moveAgentToBusyPool(agent);
+
+      // Execute task
+      execution.status = 'running';
+      const result = await this.executeTaskWithAgent(agent, taskDefinition, options);
+
+      // Update execution record
+      execution.endTime = new Date();
+      execution.duration = execution.endTime.getTime() - execution.startTime.getTime();
+      execution.output = result.result;
+      execution.tokensUsed = result.metadata?.tokensUsed;
+
+      if (result.success) {
+        execution.status = 'completed';
+        agent.metrics.tasksCompleted++;
+      } else {
+        execution.status = 'failed';
+        execution.error = result.error;
+        agent.metrics.tasksFailed++;
+      }
+
+      // Update agent metrics
+      this.updateAgentMetrics(agent, execution);
+
+      // Return agent to idle pool
+      this.returnAgentToIdlePool(agent);
+
+      this.logger.info('Task execution completed', {
+        executionId,
+        success: result.success,
+        duration: execution.duration,
+        tokensUsed: execution.tokensUsed,
+      });
+
+      this.emit('task:completed', {
+        executionId,
+        taskId: taskDefinition.id.id,
+        agentId: agent.id,
+        success: result.success,
+        duration: execution.duration,
+      });
+
+      return execution;
+
+    } catch (error) {
+      const execution = this.activeExecutions.get(executionId);
+      if (execution) {
+        execution.status = 'failed';
+        execution.error = error instanceof Error ? error.message : String(error);
+        execution.endTime = new Date();
+        execution.duration = execution.endTime.getTime() - execution.startTime.getTime();
+
+        // Return agent to pool if it was assigned
+        const agent = this.agents.get(execution.agentId);
+        if (agent) {
+          this.returnAgentToIdlePool(agent);
+        }
+      }
+
+      this.logger.error('Task execution failed', {
+        executionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      throw error;
+    } finally {
+      this.activeExecutions.delete(executionId);
+    }
+  }
+
+  /**
+   * Cancel a running task execution
+   */
+  async cancelExecution(executionId: string, reason: string): Promise<void> {
+    const execution = this.activeExecutions.get(executionId);
+    if (!execution) {
+      throw new Error(`Execution not found: ${executionId}`);
+    }
+
+    this.logger.info('Cancelling task execution', {
+      executionId,
+      reason,
+      taskId: execution.taskId,
+      agentId: execution.agentId,
+    });
+
+    try {
+      execution.status = 'cancelled';
+      execution.error = reason;
+      execution.endTime = new Date();
+      execution.duration = execution.endTime.getTime() - execution.startTime.getTime();
+
+      // Cancel agent task if running
+      const agent = this.agents.get(execution.agentId);
+      if (agent && agent.currentTask === executionId) {
+        await this.cancelAgentTask(agent);
+        this.returnAgentToIdlePool(agent);
+      }
+
+      this.emit('task:cancelled', {
+        executionId,
+        reason,
+        taskId: execution.taskId,
+        agentId: execution.agentId,
+      });
+
+    } finally {
+      this.activeExecutions.delete(executionId);
+    }
+  }
+
+  /**
+   * Terminate a specific agent
+   */
+  async terminateAgent(agentId: string, reason: string = 'Manual termination'): Promise<void> {
+    const agent = this.agents.get(agentId);
+    if (!agent) {
+      throw new Error(`Agent not found: ${agentId}`);
+    }
+
+    this.logger.info('Terminating Claude agent', {
+      agentId,
+      processId: agent.processId,
+      reason,
+    });
+
+    try {
+      // Cancel current task if any
+      if (agent.currentTask) {
+        await this.cancelExecution(agent.currentTask, 'Agent termination');
+      }
+
+      // Update status
+      agent.status = 'terminated';
+
+      // Terminate process
+      await this.terminateProcess(agent.process);
+
+      // Remove from pools and agents map
+      this.removeAgentFromPools(agent);
+      this.agents.delete(agentId);
+      this.processPool.totalTerminated++;
+
+      this.logger.info('Claude agent terminated successfully', {
+        agentId,
+        reason,
+        totalTasks: agent.totalTasks,
+        totalDuration: agent.totalDuration,
+      });
+
+      this.emit('agent:terminated', {
+        agentId,
+        reason,
+        metrics: agent.metrics,
+      });
+
+    } catch (error) {
+      this.logger.error('Error terminating agent', {
+        agentId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Get agent status and metrics
+   */
+  getAgentStatus(agentId: string): ClaudeAgent | null {
+    return this.agents.get(agentId) || null;
+  }
+
+  /**
+   * Get all active agents
+   */
+  getAllAgents(): ClaudeAgent[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * Get execution status
+   */
+  getExecutionStatus(executionId: string): ClaudeTaskExecution | null {
+    return this.activeExecutions.get(executionId) || null;
+  }
+
+  /**
+   * Get comprehensive interface metrics
+   */
+  getInterfaceMetrics(): {
+    agents: {
+      total: number;
+      idle: number;
+      busy: number;
+      failed: number;
+      terminated: number;
+    };
+    executions: {
+      active: number;
+      completed: number;
+      failed: number;
+      cancelled: number;
+    };
+    performance: {
+      averageResponseTime: number;
+      totalTokensUsed: number;
+      successRate: number;
+      throughput: number;
+    };
+    pool: {
+      totalSpawned: number;
+      totalTerminated: number;
+      recyclingEnabled: boolean;
+      poolUtilization: number;
+    };
+  } {
+    const agents = Array.from(this.agents.values());
+    const executions = Array.from(this.activeExecutions.values());
+
+    const totalCompleted = agents.reduce((sum, a) => sum + a.metrics.tasksCompleted, 0);
+    const totalFailed = agents.reduce((sum, a) => sum + a.metrics.tasksFailed, 0);
+    const totalTokens = agents.reduce((sum, a) => sum + a.metrics.totalTokensUsed, 0);
+    const avgResponseTime = agents.length > 0 
+      ? agents.reduce((sum, a) => sum + a.metrics.averageResponseTime, 0) / agents.length 
+      : 0;
+
+    return {
+      agents: {
+        total: agents.length,
+        idle: this.processPool.idle.length,
+        busy: this.processPool.busy.length,
+        failed: this.processPool.failed.length,
+        terminated: this.processPool.totalTerminated,
+      },
+      executions: {
+        active: executions.filter(e => e.status === 'running').length,
+        completed: totalCompleted,
+        failed: totalFailed,
+        cancelled: executions.filter(e => e.status === 'cancelled').length,
+      },
+      performance: {
+        averageResponseTime: avgResponseTime,
+        totalTokensUsed: totalTokens,
+        successRate: totalCompleted + totalFailed > 0 ? totalCompleted / (totalCompleted + totalFailed) : 0,
+        throughput: this.calculateThroughput(),
+      },
+      pool: {
+        totalSpawned: this.processPool.totalSpawned,
+        totalTerminated: this.processPool.totalTerminated,
+        recyclingEnabled: this.processPool.recyclingEnabled,
+        poolUtilization: this.calculatePoolUtilization(),
+      },
+    };
+  }
+
+  // Private methods
+
+  private async verifyClaudeExecutable(): Promise<void> {
+    try {
+      const { spawn } = await import('node:child_process');
+      const process = spawn(this.config.claudeExecutablePath, ['--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      return new Promise((resolve, reject) => {
+        let output = '';
+        
+        process.stdout?.on('data', (data) => {
+          output += data.toString();
+        });
+
+        process.on('close', (code) => {
+          if (code === 0) {
+            this.logger.info('Claude executable verified', {
+              path: this.config.claudeExecutablePath,
+              version: output.trim(),
+            });
+            resolve();
+          } else {
+            reject(new Error(`Claude executable verification failed with code ${code}`));
+          }
+        });
+
+        process.on('error', reject);
+      });
+
+    } catch (error) {
+      throw new Error(`Claude executable not found: ${this.config.claudeExecutablePath}`);
+    }
+  }
+
+  private async prewarmAgentPool(): Promise<void> {
+    this.logger.info('Pre-warming agent pool', {
+      targetSize: this.config.agentPoolSize,
+    });
+
+    const promises: Promise<string>[] = [];
+    
+    for (let i = 0; i < this.config.agentPoolSize; i++) {
+      promises.push(this.spawnAgent({
+        type: 'general',
+        name: `pool-agent-${i}`,
+        capabilities: ['general'],
+      }));
+    }
+
+    const results = await Promise.allSettled(promises);
+    const successful = results.filter(r => r.status === 'fulfilled').length;
+    const failed = results.filter(r => r.status === 'rejected').length;
+
+    this.logger.info('Agent pool pre-warming completed', {
+      successful,
+      failed,
+      targetSize: this.config.agentPoolSize,
+    });
+  }
+
+  private buildClaudeCommand(options: ClaudeSpawnOptions): {
+    executable: string;
+    args: string[];
+  } {
+    const args: string[] = [];
+
+    // Add model
+    args.push('--model', options.model || this.config.defaultModel);
+
+    // Add max tokens
+    args.push('--max-tokens', String(options.maxTokens || this.config.maxTokens));
+
+    // Add temperature
+    args.push('--temperature', String(options.temperature || this.config.temperature));
+
+    // Add system prompt if provided
+    if (options.systemPrompt) {
+      args.push('--system', options.systemPrompt);
+    }
+
+    // Add tools if specified
+    if (options.tools && options.tools.length > 0) {
+      args.push('--allowedTools', options.tools.join(','));
+    }
+
+    // Enable streaming if configured
+    if (this.config.enableStreaming) {
+      args.push('--stream');
+    }
+
+    // Skip permissions for swarm execution
+    args.push('--dangerously-skip-permissions');
+
+    return {
+      executable: this.config.claudeExecutablePath,
+      args,
+    };
+  }
+
+  private setupProcessEventHandlers(agent: ClaudeAgent): void {
+    const { process } = agent;
+
+    process.on('exit', (code, signal) => {
+      this.logger.info('Claude agent process exited', {
+        agentId: agent.id,
+        processId: agent.processId,
+        code,
+        signal,
+      });
+
+      if (agent.status !== 'terminated') {
+        agent.status = 'error';
+        this.moveAgentToFailedPool(agent);
+      }
+
+      this.emit('agent:exited', {
+        agentId: agent.id,
+        code,
+        signal,
+      });
+    });
+
+    process.on('error', (error) => {
+      this.logger.error('Claude agent process error', {
+        agentId: agent.id,
+        processId: agent.processId,
+        error: error.message,
+      });
+
+      agent.status = 'error';
+      this.moveAgentToFailedPool(agent);
+
+      this.emit('agent:error', {
+        agentId: agent.id,
+        error: error.message,
+      });
+    });
+
+    // Handle stdout/stderr if needed
+    if (this.config.enableLogging) {
+      process.stdout?.on('data', (data) => {
+        this.logger.debug('Agent stdout', {
+          agentId: agent.id,
+          data: data.toString().trim(),
+        });
+      });
+
+      process.stderr?.on('data', (data) => {
+        this.logger.debug('Agent stderr', {
+          agentId: agent.id,
+          data: data.toString().trim(),
+        });
+      });
+    }
+  }
+
+  private async waitForAgentReady(agent: ClaudeAgent, timeout: number = 30000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+      const checkInterval = 1000; // 1 second
+
+      const checkReady = () => {
+        const elapsed = Date.now() - startTime;
+        
+        if (elapsed > timeout) {
+          reject(new Error(`Agent ${agent.id} failed to become ready within ${timeout}ms`));
+          return;
+        }
+
+        // Check if process is still running
+        if (agent.process.killed || agent.process.exitCode !== null) {
+          reject(new Error(`Agent ${agent.id} process terminated during initialization`));
+          return;
+        }
+
+        // For now, assume agent is ready after a short delay
+        // In a real implementation, you might check for specific output or response
+        if (elapsed > 2000) { // 2 seconds
+          resolve();
+        } else {
+          setTimeout(checkReady, checkInterval);
+        }
+      };
+
+      checkReady();
+    });
+  }
+
+  private async selectOptimalAgent(taskDefinition: TaskDefinition): Promise<ClaudeAgent | null> {
+    const availableAgents = this.processPool.idle.filter(agent => agent.status === 'idle');
+    
+    if (availableAgents.length === 0) {
+      // Try to spawn a new agent if under limit
+      if (this.getTotalActiveAgents() < this.config.maxConcurrentAgents) {
+        const agentId = await this.spawnAgent({
+          type: 'task-specific',
+          capabilities: taskDefinition.requirements.capabilities,
+        });
+        return this.agents.get(agentId) || null;
+      }
+      return null;
+    }
+
+    // Select agent based on capabilities and performance
+    const scoredAgents = availableAgents.map(agent => ({
+      agent,
+      score: this.calculateAgentScore(agent, taskDefinition),
+    }));
+
+    scoredAgents.sort((a, b) => b.score - a.score);
+    return scoredAgents[0].agent;
+  }
+
+  private calculateAgentScore(agent: ClaudeAgent, taskDefinition: TaskDefinition): number {
+    let score = 0;
+
+    // Capability match
+    const requiredCapabilities = taskDefinition.requirements.capabilities;
+    const matchingCapabilities = agent.capabilities.filter(cap => 
+      requiredCapabilities.includes(cap)
+    );
+    score += (matchingCapabilities.length / requiredCapabilities.length) * 100;
+
+    // Performance metrics
+    score += agent.metrics.successRate * 50;
+    score += Math.max(0, 50 - agent.metrics.averageResponseTime / 1000) * 10; // Prefer faster agents
+
+    // Load balancing - prefer agents with fewer completed tasks
+    const maxTasks = Math.max(...this.processPool.idle.map(a => a.totalTasks), 1);
+    score += (1 - agent.totalTasks / maxTasks) * 20;
+
+    return score;
+  }
+
+  private async executeTaskWithAgent(
+    agent: ClaudeAgent,
+    taskDefinition: TaskDefinition,
+    options: Partial<ClaudeExecutionOptions>
+  ): Promise<ExecutionResult> {
+    const startTime = performance.now();
+
+    try {
+      // Create execution context for the agent
+      const context: ExecutionContext = {
+        task: taskDefinition,
+        agent: this.convertToAgentState(agent),
+        workingDirectory: options.workingDirectory || this.config.workingDirectory,
+        tempDirectory: path.join(this.config.workingDirectory, 'temp', agent.id),
+        logDirectory: path.join(this.config.workingDirectory, 'logs', agent.id),
+        environment: {
+          ...this.config.environmentVariables,
+          CLAUDE_AGENT_ID: agent.id,
+          CLAUDE_TASK_ID: taskDefinition.id.id,
+        },
+        resources: {
+          maxMemory: taskDefinition.requirements.memoryRequired || 512 * 1024 * 1024,
+          maxCpuTime: taskDefinition.requirements.maxDuration || 300000,
+          maxDiskSpace: 1024 * 1024 * 1024,
+          maxNetworkConnections: 10,
+          maxFileHandles: 100,
+          priority: 1,
+        },
+      };
+
+      // Execute using task executor
+      const result = await this.taskExecutor.executeClaudeTask(
+        taskDefinition,
+        context.agent,
+        {
+          model: options.model || this.config.defaultModel,
+          maxTokens: options.maxTokens || this.config.maxTokens,
+          temperature: options.temperature || this.config.temperature,
+          timeout: options.timeout || this.config.timeout,
+          claudePath: this.config.claudeExecutablePath,
+          ...options,
+        }
+      );
+
+      const duration = performance.now() - startTime;
+      
+      // Update agent activity
+      agent.lastActivity = new Date();
+      agent.totalTasks++;
+      agent.totalDuration += duration;
+
+      return result;
+
+    } catch (error) {
+      const duration = performance.now() - startTime;
+      agent.totalDuration += duration;
+      
+      throw error;
+    }
+  }
+
+  private convertToAgentState(agent: ClaudeAgent): AgentState {
+    // Convert ClaudeAgent to AgentState for compatibility
+    return {
+      id: {
+        id: agent.id,
+        swarmId: 'claude-interface',
+        type: agent.type as any,
+        instance: 1,
+      },
+      name: `Claude-${agent.id}`,
+      type: agent.type as any,
+      status: agent.status as any,
+      capabilities: this.createAgentCapabilities(agent.capabilities),
+      metrics: {
+        tasksCompleted: agent.metrics.tasksCompleted,
+        tasksFailed: agent.metrics.tasksFailed,
+        averageExecutionTime: agent.metrics.averageResponseTime,
+        successRate: agent.metrics.successRate,
+        cpuUsage: agent.metrics.cpuUsage,
+        memoryUsage: agent.metrics.memoryUsage,
+        diskUsage: 0,
+        networkUsage: 0,
+        codeQuality: 0.8,
+        testCoverage: 0.7,
+        bugRate: 0.1,
+        userSatisfaction: 0.9,
+        totalUptime: Date.now() - agent.spawnedAt.getTime(),
+        lastActivity: agent.lastActivity,
+        responseTime: agent.metrics.averageResponseTime,
+      },
+      currentTask: agent.currentTask ? {
+        id: agent.currentTask,
+        swarmId: 'claude-interface',
+        sequence: 0,
+        priority: 1,
+      } : undefined,
+      workload: agent.status === 'busy' ? 1 : 0,
+      health: agent.status === 'error' ? 0 : 1,
+      config: {
+        autonomyLevel: 0.8,
+        learningEnabled: false,
+        adaptationEnabled: false,
+        maxTasksPerHour: 60,
+        maxConcurrentTasks: 1,
+        timeoutThreshold: this.config.timeout,
+        reportingInterval: 10000,
+        heartbeatInterval: 5000,
+        permissions: ['read', 'write', 'execute'],
+        trustedAgents: [],
+        expertise: {},
+        preferences: {},
+      },
+      environment: {
+        runtime: 'claude',
+        version: '1.0.0',
+        workingDirectory: this.config.workingDirectory,
+        tempDirectory: path.join(this.config.workingDirectory, 'temp', agent.id),
+        logDirectory: path.join(this.config.workingDirectory, 'logs', agent.id),
+        apiEndpoints: {},
+        credentials: {},
+        availableTools: agent.capabilities,
+        toolConfigs: {},
+      },
+      endpoints: [],
+      lastHeartbeat: agent.lastActivity,
+      taskHistory: [],
+      errorHistory: [],
+      parentAgent: undefined,
+      childAgents: [],
+      collaborators: [],
+    };
+  }
+
+  private createAgentCapabilities(capabilities: string[]): AgentCapabilities {
+    return {
+      codeGeneration: capabilities.includes('coding') || capabilities.includes('codeGeneration'),
+      codeReview: capabilities.includes('review') || capabilities.includes('codeReview'),
+      testing: capabilities.includes('testing'),
+      documentation: capabilities.includes('documentation'),
+      research: capabilities.includes('research'),
+      analysis: capabilities.includes('analysis'),
+      webSearch: capabilities.includes('webSearch'),
+      apiIntegration: capabilities.includes('apiIntegration'),
+      fileSystem: capabilities.includes('fileSystem'),
+      terminalAccess: capabilities.includes('terminal'),
+      languages: capabilities.filter(c => ['javascript', 'typescript', 'python', 'java'].includes(c)),
+      frameworks: capabilities.filter(c => ['react', 'node', 'express'].includes(c)),
+      domains: capabilities.filter(c => ['web', 'api', 'database'].includes(c)),
+      tools: capabilities.filter(c => ['bash', 'git', 'npm'].includes(c)),
+      maxConcurrentTasks: 1,
+      maxMemoryUsage: 512 * 1024 * 1024,
+      maxExecutionTime: this.config.timeout,
+      reliability: 0.9,
+      speed: 1.0,
+      quality: 0.8,
+    };
+  }
+
+  private async cancelAgentTask(agent: ClaudeAgent): Promise<void> {
+    if (agent.process && !agent.process.killed) {
+      // Send interrupt signal
+      agent.process.kill('SIGINT');
+      
+      // Wait briefly for graceful shutdown
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      
+      // Force kill if still running
+      if (!agent.process.killed) {
+        agent.process.kill('SIGKILL');
+      }
+    }
+
+    agent.currentTask = undefined;
+    agent.status = 'idle';
+    agent.lastActivity = new Date();
+  }
+
+  private async terminateProcess(process: ChildProcess): Promise<void> {
+    if (process.killed || process.exitCode !== null) {
+      return;
+    }
+
+    // Send termination signal
+    process.kill('SIGTERM');
+    
+    // Wait for graceful shutdown
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    // Force kill if still running
+    if (!process.killed && process.exitCode === null) {
+      process.kill('SIGKILL');
+    }
+  }
+
+  private async terminateAllAgents(): Promise<void> {
+    const terminationPromises = Array.from(this.agents.keys())
+      .map(agentId => this.terminateAgent(agentId, 'Interface shutdown'));
+    
+    await Promise.allSettled(terminationPromises);
+  }
+
+  private moveAgentToBusyPool(agent: ClaudeAgent): void {
+    const idleIndex = this.processPool.idle.indexOf(agent);
+    if (idleIndex !== -1) {
+      this.processPool.idle.splice(idleIndex, 1);
+      this.processPool.busy.push(agent);
+    }
+  }
+
+  private returnAgentToIdlePool(agent: ClaudeAgent): void {
+    agent.status = 'idle';
+    agent.currentTask = undefined;
+    agent.lastActivity = new Date();
+
+    const busyIndex = this.processPool.busy.indexOf(agent);
+    if (busyIndex !== -1) {
+      this.processPool.busy.splice(busyIndex, 1);
+      this.processPool.idle.push(agent);
+    }
+  }
+
+  private moveAgentToFailedPool(agent: ClaudeAgent): void {
+    // Remove from other pools
+    this.removeAgentFromPools(agent);
+    this.processPool.failed.push(agent);
+  }
+
+  private removeAgentFromPools(agent: ClaudeAgent): void {
+    const idleIndex = this.processPool.idle.indexOf(agent);
+    if (idleIndex !== -1) {
+      this.processPool.idle.splice(idleIndex, 1);
+    }
+
+    const busyIndex = this.processPool.busy.indexOf(agent);
+    if (busyIndex !== -1) {
+      this.processPool.busy.splice(busyIndex, 1);
+    }
+
+    const failedIndex = this.processPool.failed.indexOf(agent);
+    if (failedIndex !== -1) {
+      this.processPool.failed.splice(failedIndex, 1);
+    }
+  }
+
+  private updateAgentMetrics(agent: ClaudeAgent, execution: ClaudeTaskExecution): void {
+    const metrics = agent.metrics;
+    
+    // Update averages
+    const totalTasks = metrics.tasksCompleted + metrics.tasksFailed;
+    if (execution.duration) {
+      metrics.averageResponseTime = totalTasks > 0 
+        ? ((metrics.averageResponseTime * (totalTasks - 1)) + execution.duration) / totalTasks
+        : execution.duration;
+    }
+
+    // Update success rate
+    metrics.successRate = totalTasks > 0 
+      ? metrics.tasksCompleted / totalTasks 
+      : 0;
+
+    // Update error rate
+    metrics.errorRate = 1 - metrics.successRate;
+
+    // Update token usage if available
+    if (execution.tokensUsed) {
+      metrics.totalTokensUsed += execution.tokensUsed;
+    }
+  }
+
+  private getTotalActiveAgents(): number {
+    return this.processPool.idle.length + this.processPool.busy.length;
+  }
+
+  private calculateThroughput(): number {
+    const agents = Array.from(this.agents.values());
+    const totalTasks = agents.reduce((sum, a) => sum + a.totalTasks, 0);
+    const totalTime = agents.reduce((sum, a) => sum + a.totalDuration, 0);
+    
+    return totalTime > 0 ? (totalTasks / totalTime) * 60000 : 0; // tasks per minute
+  }
+
+  private calculatePoolUtilization(): number {
+    const total = this.getTotalActiveAgents();
+    const busy = this.processPool.busy.length;
+    
+    return total > 0 ? busy / total : 0;
+  }
+
+  private startHealthChecks(): void {
+    this.healthCheckInterval = setInterval(() => {
+      this.performHealthCheck();
+    }, this.config.healthCheckInterval);
+  }
+
+  private performHealthCheck(): void {
+    const now = Date.now();
+    
+    for (const agent of this.agents.values()) {
+      // Check for stalled agents
+      const inactiveTime = now - agent.lastActivity.getTime();
+      
+      if (agent.status === 'busy' && inactiveTime > this.config.timeout * 2) {
+        this.logger.warn('Agent appears stalled', {
+          agentId: agent.id,
+          inactiveTime,
+          currentTask: agent.currentTask,
+        });
+
+        // Try to recover the agent
+        this.recoverStalledAgent(agent);
+      }
+
+      // Check for failed processes
+      if (agent.process.killed || agent.process.exitCode !== null) {
+        if (agent.status !== 'terminated') {
+          this.logger.warn('Agent process died unexpectedly', {
+            agentId: agent.id,
+            exitCode: agent.process.exitCode,
+          });
+          
+          agent.status = 'error';
+          this.moveAgentToFailedPool(agent);
+        }
+      }
+    }
+  }
+
+  private async recoverStalledAgent(agent: ClaudeAgent): Promise<void> {
+    try {
+      if (agent.currentTask) {
+        await this.cancelExecution(agent.currentTask, 'Agent recovery');
+      }
+      
+      this.returnAgentToIdlePool(agent);
+      
+      this.logger.info('Agent recovered from stalled state', {
+        agentId: agent.id,
+      });
+
+    } catch (error) {
+      this.logger.error('Failed to recover stalled agent', {
+        agentId: agent.id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      
+      // Terminate the problematic agent
+      await this.terminateAgent(agent.id, 'Recovery failed');
+    }
+  }
+
+  private initializeProcessPool(): ProcessPool {
+    return {
+      idle: [],
+      busy: [],
+      failed: [],
+      totalSpawned: 0,
+      totalTerminated: 0,
+      recyclingEnabled: this.config.processRecycling,
+      maxAge: 3600000, // 1 hour
+      maxTasks: 100,
+    };
+  }
+
+  private initializeAgentMetrics(): ClaudeAgentMetrics {
+    return {
+      tasksCompleted: 0,
+      tasksFailed: 0,
+      averageResponseTime: 0,
+      totalTokensUsed: 0,
+      memoryUsage: 0,
+      cpuUsage: 0,
+      errorRate: 0,
+      successRate: 0,
+    };
+  }
+
+  private createDefaultConfig(config: Partial<ClaudeCodeConfig>): ClaudeCodeConfig {
+    return {
+      claudeExecutablePath: 'claude',
+      defaultModel: 'claude-3-5-sonnet-20241022',
+      maxTokens: 4096,
+      temperature: 0.7,
+      timeout: 300000, // 5 minutes
+      maxConcurrentAgents: 10,
+      enableStreaming: false,
+      enableLogging: true,
+      workingDirectory: process.cwd(),
+      environmentVariables: {},
+      agentPoolSize: 0,
+      processRecycling: true,
+      healthCheckInterval: 30000, // 30 seconds
+      ...config,
+    };
+  }
+
+  private setupEventHandlers(): void {
+    this.on('agent:spawned', (data) => {
+      this.logger.info('Agent spawned event', data);
+    });
+
+    this.on('agent:terminated', (data) => {
+      this.logger.info('Agent terminated event', data);
+    });
+
+    this.on('task:completed', (data) => {
+      this.logger.info('Task completed event', data);
+    });
+
+    this.on('task:cancelled', (data) => {
+      this.logger.warn('Task cancelled event', data);
+    });
+  }
+}
+
+export default ClaudeCodeInterface;