claude-flow-novice 1.6.3 → 1.6.5

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/completion/swarm-shutdown.js

@@ -0,0 +1,366 @@
+/**
+ * Agent Coordination V2 - Swarm Shutdown Manager
+ *
+ * Graceful shutdown coordinator with cascading termination and checkpoint creation.
+ * Performance targets:
+ * - Shutdown latency: <500ms for swarms with 20 agents
+ * - Checkpoint creation: <50ms per agent
+ * - Background process cleanup: 100% coverage
+ *
+ * Features:
+ * - Pause all agents before shutdown (prevent token waste)
+ * - Create final completion checkpoint
+ * - Cascade shutdown (root → leaves DFS traversal)
+ * - Clean up background processes
+ * - Close SDK sessions gracefully
+ * - Emergency shutdown for critical errors
+ *
+ * @module coordination/v2/completion/swarm-shutdown
+ */ import { EventEmitter } from 'events';
+/**
+ * SwarmShutdown - Graceful swarm shutdown coordinator
+ *
+ * Manages orderly shutdown of multi-agent swarms with the following sequence:
+ * 1. Pause all active agents (zero token cost)
+ * 2. Create final completion checkpoint (optional)
+ * 3. Cascade shutdown from root to leaves (DFS)
+ * 4. Clean up background processes
+ * 5. Close SDK sessions
+ *
+ * @example
+ * ```typescript
+ * const shutdown = new SwarmShutdown(queryController, backgroundOrchestrator, {
+ *   maxShutdownTimeMs: 10000,
+ *   createFinalCheckpoint: true,
+ *   cascadeShutdown: true
+ * });
+ *
+ * // Graceful shutdown
+ * const result = await shutdown.shutdownSwarm(['agent-1', 'agent-2', 'agent-3']);
+ *
+ * // Emergency shutdown (no checkpoints, immediate)
+ * await shutdown.emergencyShutdown('Critical error detected');
+ * ```
+ */ export class SwarmShutdown extends EventEmitter {
+    queryController;
+    backgroundOrchestrator;
+    config;
+    shutdownInProgress = false;
+    shutdownStartTime = 0;
+    constructor(queryController, backgroundOrchestrator, config){
+        super();
+        this.queryController = queryController;
+        this.backgroundOrchestrator = backgroundOrchestrator;
+        this.config = {
+            maxShutdownTimeMs: 10000,
+            createFinalCheckpoint: true,
+            cascadeShutdown: true,
+            agentGracePeriodMs: 500,
+            cleanupBackgroundProcesses: true,
+            perAgentTimeoutMs: 1000,
+            ...config
+        };
+    }
+    /**
+   * Graceful shutdown of entire swarm
+   *
+   * Performance target: <500ms for 20 agents
+   *
+   * @param agentIds - Array of agent IDs to shutdown
+   * @param reason - Shutdown reason for logging
+   * @returns Promise resolving to SwarmShutdownResult
+   */ async shutdownSwarm(agentIds, reason = 'Graceful swarm shutdown') {
+        if (this.shutdownInProgress) {
+            throw new Error('Shutdown already in progress');
+        }
+        this.shutdownInProgress = true;
+        this.shutdownStartTime = Date.now();
+        const shutdownResult = {
+            success: true,
+            totalAgents: agentIds.length,
+            successfulShutdowns: 0,
+            failedShutdowns: 0,
+            totalLatencyMs: 0,
+            agentResults: [],
+            backgroundProcessesCleaned: 0,
+            shutdownAt: new Date()
+        };
+        this.emit('shutdown:started', {
+            agentCount: agentIds.length,
+            reason,
+            config: this.config
+        });
+        try {
+            // Step 1: Pause all active agents (prevents token waste)
+            await this.pauseAllAgents(agentIds, reason);
+            // Step 2: Shutdown agents in cascade order (root → leaves DFS)
+            if (this.config.cascadeShutdown && this.backgroundOrchestrator) {
+                shutdownResult.agentResults = await this.cascadeShutdown(agentIds, reason);
+            } else {
+                shutdownResult.agentResults = await this.parallelShutdown(agentIds, reason);
+            }
+            // Calculate metrics
+            shutdownResult.successfulShutdowns = shutdownResult.agentResults.filter((r)=>r.success).length;
+            shutdownResult.failedShutdowns = shutdownResult.agentResults.filter((r)=>!r.success).length;
+            shutdownResult.backgroundProcessesCleaned = shutdownResult.agentResults.reduce((sum, r)=>sum + r.backgroundProcessesTerminated, 0);
+            shutdownResult.success = shutdownResult.failedShutdowns === 0;
+            shutdownResult.totalLatencyMs = Date.now() - this.shutdownStartTime;
+            // Performance warning if exceeds target
+            if (shutdownResult.totalLatencyMs > 500 && agentIds.length <= 20) {
+                console.warn(`[SwarmShutdown] Shutdown latency ${shutdownResult.totalLatencyMs}ms exceeds 500ms target for ${agentIds.length} agents`);
+            }
+            this.emit('shutdown:completed', shutdownResult);
+            return shutdownResult;
+        } catch (error) {
+            shutdownResult.success = false;
+            shutdownResult.totalLatencyMs = Date.now() - this.shutdownStartTime;
+            this.emit('shutdown:failed', {
+                error: error instanceof Error ? error.message : String(error),
+                result: shutdownResult
+            });
+            throw error;
+        } finally{
+            this.shutdownInProgress = false;
+        }
+    }
+    /**
+   * Emergency shutdown - immediate termination without checkpoints
+   *
+   * Used for critical errors or forced shutdown.
+   *
+   * @param reason - Emergency shutdown reason
+   * @returns Promise resolving when shutdown complete
+   */ async emergencyShutdown(reason) {
+        this.emit('shutdown:emergency', {
+            reason
+        });
+        const activeAgents = this.queryController.getActiveAgents();
+        const agentIds = activeAgents.map((a)=>a.agentId);
+        // Force shutdown without checkpoints
+        const originalCheckpointConfig = this.config.createFinalCheckpoint;
+        this.config.createFinalCheckpoint = false;
+        try {
+            await this.shutdownSwarm(agentIds, `EMERGENCY: ${reason}`);
+        } finally{
+            this.config.createFinalCheckpoint = originalCheckpointConfig;
+        }
+        // Cleanup all resources
+        await this.queryController.cleanup();
+        if (this.backgroundOrchestrator) {
+            await this.backgroundOrchestrator.cleanup();
+        }
+    }
+    /**
+   * Pause all agents before shutdown (prevent token waste)
+   *
+   * @param agentIds - Agent IDs to pause
+   * @param reason - Pause reason
+   */ async pauseAllAgents(agentIds, reason) {
+        const pauseStartTime = Date.now();
+        const pausePromises = agentIds.map(async (agentId)=>{
+            try {
+                const agent = this.queryController.getActiveAgents().find((a)=>a.agentId === agentId);
+                if (agent && !agent.isPaused) {
+                    await this.queryController.pauseAgent(agentId, `Pre-shutdown pause: ${reason}`);
+                }
+            } catch (error) {
+                // Ignore pause errors - agent may already be paused or terminated
+                console.debug(`[SwarmShutdown] Failed to pause agent ${agentId}:`, error);
+            }
+        });
+        await Promise.all(pausePromises);
+        const pauseLatency = Date.now() - pauseStartTime;
+        this.emit('shutdown:agents-paused', {
+            agentCount: agentIds.length,
+            latencyMs: pauseLatency
+        });
+    }
+    /**
+   * Cascade shutdown (root → leaves DFS traversal)
+   *
+   * Shuts down agents in dependency order to prevent orphaned processes.
+   *
+   * @param agentIds - Agent IDs to shutdown
+   * @param reason - Shutdown reason
+   * @returns Array of AgentShutdownResult
+   */ async cascadeShutdown(agentIds, reason) {
+        const results = [];
+        // Build agent hierarchy from background orchestrator
+        const agentHierarchy = this.buildAgentHierarchy(agentIds);
+        // Shutdown in reverse order (deepest first - DFS)
+        const shutdownOrder = this.getShutdownOrder(agentHierarchy);
+        for (const agentId of shutdownOrder){
+            const result = await this.shutdownSingleAgent(agentId, reason);
+            results.push(result);
+            // Check if we've exceeded max shutdown time
+            if (Date.now() - this.shutdownStartTime > this.config.maxShutdownTimeMs) {
+                console.warn(`[SwarmShutdown] Max shutdown time ${this.config.maxShutdownTimeMs}ms exceeded, forcing remaining terminations`);
+                // Force shutdown remaining agents
+                const remaining = agentIds.filter((id)=>!results.some((r)=>r.agentId === id));
+                for (const remainingId of remaining){
+                    results.push(await this.forceTerminateAgent(remainingId));
+                }
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+   * Parallel shutdown (no dependency ordering)
+   *
+   * @param agentIds - Agent IDs to shutdown
+   * @param reason - Shutdown reason
+   * @returns Array of AgentShutdownResult
+   */ async parallelShutdown(agentIds, reason) {
+        const shutdownPromises = agentIds.map((agentId)=>this.shutdownSingleAgent(agentId, reason));
+        return Promise.all(shutdownPromises);
+    }
+    /**
+   * Shutdown single agent with checkpoint creation
+   *
+   * Performance target: <50ms per agent
+   *
+   * @param agentId - Agent to shutdown
+   * @param reason - Shutdown reason
+   * @returns AgentShutdownResult
+   */ async shutdownSingleAgent(agentId, reason) {
+        const startTime = Date.now();
+        const result = {
+            agentId,
+            success: false,
+            latencyMs: 0,
+            backgroundProcessesTerminated: 0
+        };
+        try {
+            // Create final checkpoint if enabled
+            if (this.config.createFinalCheckpoint) {
+                const checkpoint = await this.queryController.createCheckpoint(agentId, reason, {
+                    shutdownTimestamp: Date.now(),
+                    shutdownReason: reason
+                });
+                result.checkpoint = checkpoint;
+            }
+            // Terminate background processes for this agent
+            if (this.config.cleanupBackgroundProcesses && this.backgroundOrchestrator) {
+                const processes = this.backgroundOrchestrator.getAllProcesses().filter((p)=>p.agentId === agentId);
+                for (const process of processes){
+                    await this.backgroundOrchestrator.terminateProcess(process.id);
+                    result.backgroundProcessesTerminated++;
+                }
+            }
+            // Terminate agent session
+            await this.queryController.terminateAgent(agentId, reason);
+            result.success = true;
+            result.latencyMs = Date.now() - startTime;
+            // Performance warning if exceeds target
+            if (result.latencyMs > 50) {
+                console.warn(`[SwarmShutdown] Agent shutdown ${result.latencyMs}ms exceeds 50ms target for agent ${agentId}`);
+            }
+            this.emit('shutdown:agent-complete', result);
+        } catch (error) {
+            result.success = false;
+            result.error = error instanceof Error ? error.message : String(error);
+            result.latencyMs = Date.now() - startTime;
+            this.emit('shutdown:agent-failed', result);
+        }
+        return result;
+    }
+    /**
+   * Force terminate agent without checkpoints (emergency)
+   *
+   * @param agentId - Agent to force terminate
+   * @returns AgentShutdownResult
+   */ async forceTerminateAgent(agentId) {
+        const startTime = Date.now();
+        try {
+            await this.queryController.terminateAgent(agentId, 'Forced termination');
+            return {
+                agentId,
+                success: true,
+                latencyMs: Date.now() - startTime,
+                backgroundProcessesTerminated: 0
+            };
+        } catch (error) {
+            return {
+                agentId,
+                success: false,
+                latencyMs: Date.now() - startTime,
+                backgroundProcessesTerminated: 0,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /**
+   * Build agent hierarchy from background orchestrator
+   *
+   * @param agentIds - Agent IDs to organize
+   * @returns Map of parent → children relationships
+   */ buildAgentHierarchy(agentIds) {
+        const hierarchy = new Map();
+        if (!this.backgroundOrchestrator) {
+            return hierarchy;
+        }
+        const processes = this.backgroundOrchestrator.getAllProcesses();
+        for (const agentId of agentIds){
+            const agentProcesses = processes.filter((p)=>p.agentId === agentId);
+            for (const process of agentProcesses){
+                const children = this.backgroundOrchestrator.getChildProcesses(process.id);
+                if (children.length > 0) {
+                    const childAgentIds = children.map((c)=>c.agentId).filter((id)=>agentIds.includes(id));
+                    if (childAgentIds.length > 0) {
+                        hierarchy.set(agentId, childAgentIds);
+                    }
+                }
+            }
+        }
+        return hierarchy;
+    }
+    /**
+   * Get shutdown order using DFS (deepest first)
+   *
+   * @param hierarchy - Agent hierarchy map
+   * @returns Array of agent IDs in shutdown order
+   */ getShutdownOrder(hierarchy) {
+        const visited = new Set();
+        const order = [];
+        const dfs = (agentId)=>{
+            if (visited.has(agentId)) {
+                return;
+            }
+            visited.add(agentId);
+            const children = hierarchy.get(agentId) || [];
+            for (const child of children){
+                dfs(child);
+            }
+            order.push(agentId);
+        };
+        // Find root agents (no parents)
+        const allAgents = new Set([
+            ...hierarchy.keys(),
+            ...Array.from(hierarchy.values()).flat()
+        ]);
+        const childrenArrays = Array.from(hierarchy.values());
+        const children = new Set(childrenArrays.flat());
+        const roots = Array.from(allAgents).filter((id)=>!children.has(id));
+        // DFS from each root
+        for (const root of roots){
+            dfs(root);
+        }
+        // Reverse for deepest-first order
+        return order.reverse();
+    }
+    /**
+   * Check if shutdown is in progress
+   */ isShutdownInProgress() {
+        return this.shutdownInProgress;
+    }
+    /**
+   * Get shutdown configuration
+   */ getConfig() {
+        return {
+            ...this.config
+        };
+    }
+}
+
+//# sourceMappingURL=swarm-shutdown.js.map

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/completion/swarm-shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../src/coordination/archives/v2-sdk-typescript/v2/completion/swarm-shutdown.ts"],"names":["EventEmitter","SwarmShutdown","queryController","backgroundOrchestrator","config","shutdownInProgress","shutdownStartTime","maxShutdownTimeMs","createFinalCheckpoint","cascadeShutdown","agentGracePeriodMs","cleanupBackgroundProcesses","perAgentTimeoutMs","shutdownSwarm","agentIds","reason","Error","Date","now","shutdownResult","success","totalAgents","length","successfulShutdowns","failedShutdowns","totalLatencyMs","agentResults","backgroundProcessesCleaned","shutdownAt","emit","agentCount","pauseAllAgents","parallelShutdown","filter","r","reduce","sum","backgroundProcessesTerminated","console","warn","error","message","String","result","emergencyShutdown","activeAgents","getActiveAgents","map","a","agentId","originalCheckpointConfig","cleanup","pauseStartTime","pausePromises","agent","find","isPaused","pauseAgent","debug","Promise","all","pauseLatency","latencyMs","results","agentHierarchy","buildAgentHierarchy","shutdownOrder","getShutdownOrder","shutdownSingleAgent","push","remaining","id","some","remainingId","forceTerminateAgent","shutdownPromises","startTime","checkpoint","createCheckpoint","shutdownTimestamp","shutdownReason","processes","getAllProcesses","p","process","terminateProcess","terminateAgent","hierarchy","Map","agentProcesses","children","getChildProcesses","childAgentIds","c","includes","set","visited","Set","order","dfs","has","add","get","child","allAgents","keys","Array","from","values","flat","childrenArrays","roots","root","reverse","isShutdownInProgress","getConfig"],"mappings":"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"}

package/.claude-flow-novice/dist/src/coordination/archives/v2-sdk-typescript/v2/coordinator-factory.js

@@ -0,0 +1,287 @@
+/**
+ * Agent Coordination V2 - CoordinatorFactory
+ *
+ * Factory pattern for auto-detecting and instantiating coordination modes (CLI/SDK/Hybrid).
+ * Enables seamless switching between coordination strategies based on environment.
+ *
+ * @module coordination/v2/coordinator-factory
+ */ import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { QueryController } from './sdk/query-controller.js';
+import { Logger } from '../../core/logger.js';
+/**
+ * CoordinatorFactory - Auto-detects coordination mode and instantiates coordinators
+ *
+ * Features:
+ * - Automatic mode detection based on environment
+ * - Validation of mode compatibility
+ * - Graceful degradation when capabilities missing
+ * - Polymorphic coordinator creation (returns ICoordinator)
+ *
+ * Coordination Modes:
+ * - **SDK**: Direct Anthropic SDK usage (requires ANTHROPIC_API_KEY)
+ * - **CLI**: Claude Code CLI execution (requires claude-code CLI)
+ * - **Hybrid**: Mixed CLI/SDK with seamless transitions (Week 2 feature)
+ * - **Auto**: Automatic detection (default)
+ *
+ * Mode Selection Priority:
+ * 1. Explicit mode from options.mode
+ * 2. Auto-detection: SDK > CLI > Hybrid
+ * 3. Fallback to SDK if no valid mode found
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect mode
+ * const coordinator = await CoordinatorFactory.create();
+ *
+ * // Explicit SDK mode
+ * const sdkCoordinator = await CoordinatorFactory.create({
+ *   mode: 'sdk',
+ *   apiKey: process.env.ANTHROPIC_API_KEY
+ * });
+ *
+ * // Validate environment before creation
+ * const capabilities = CoordinatorFactory.detectEnvironment();
+ * if (capabilities.validationErrors.length === 0) {
+ *   const coordinator = await CoordinatorFactory.create({
+ *     mode: capabilities.suggestedMode
+ *   });
+ * }
+ * ```
+ */ export class CoordinatorFactory {
+    static logger = new Logger({
+        level: 'info',
+        format: 'text',
+        destination: 'console'
+    });
+    /**
+   * Detect environment capabilities and suggest coordination mode
+   *
+   * Checks for:
+   * - ANTHROPIC_API_KEY environment variable
+   * - Claude Code CLI binary presence
+   * - CLI path validity
+   *
+   * @returns Environment capabilities and suggested mode
+   */ static detectEnvironment() {
+        const capabilities = {
+            hasSDKCredentials: false,
+            hasCLI: false,
+            suggestedMode: 'sdk',
+            validationErrors: []
+        };
+        // Check for SDK credentials
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (apiKey && apiKey.trim().length > 0) {
+            capabilities.hasSDKCredentials = true;
+            // Validate API key format (starts with sk-ant-)
+            if (!apiKey.startsWith('sk-ant-')) {
+                capabilities.validationErrors.push('ANTHROPIC_API_KEY does not match expected format (should start with sk-ant-)');
+            }
+        }
+        // Check for Claude Code CLI
+        const cliPathEnv = process.env.CLAUDE_CODE_CLI;
+        if (cliPathEnv && existsSync(cliPathEnv)) {
+            capabilities.hasCLI = true;
+            capabilities.cliPath = cliPathEnv;
+        } else {
+            // Try to find claude-code in PATH
+            try {
+                const whichResult = execSync('which claude-code 2>/dev/null || where claude-code 2>NUL', {
+                    encoding: 'utf-8',
+                    stdio: [
+                        'ignore',
+                        'pipe',
+                        'ignore'
+                    ]
+                }).trim();
+                if (whichResult) {
+                    capabilities.hasCLI = true;
+                    capabilities.cliPath = whichResult.split('\n')[0]; // Take first match
+                }
+            } catch  {
+            // CLI not found in PATH
+            }
+        }
+        // Determine suggested mode based on capabilities
+        if (capabilities.hasSDKCredentials && !capabilities.hasCLI) {
+            capabilities.suggestedMode = 'sdk';
+        } else if (!capabilities.hasSDKCredentials && capabilities.hasCLI) {
+            capabilities.suggestedMode = 'cli';
+        } else if (capabilities.hasSDKCredentials && capabilities.hasCLI) {
+            capabilities.suggestedMode = 'hybrid';
+        } else {
+            capabilities.suggestedMode = 'sdk'; // Default fallback
+            capabilities.validationErrors.push('No coordination mode available: Missing both ANTHROPIC_API_KEY and Claude Code CLI');
+        }
+        return capabilities;
+    }
+    /**
+   * Auto-detect coordination mode based on environment
+   *
+   * Priority:
+   * 1. SDK (if ANTHROPIC_API_KEY present)
+   * 2. CLI (if Claude Code CLI available)
+   * 3. Hybrid (if both available)
+   * 4. SDK (default fallback)
+   *
+   * @returns Detected coordination mode
+   */ static detectMode() {
+        const capabilities = this.detectEnvironment();
+        return capabilities.suggestedMode;
+    }
+    /**
+   * Validate mode compatibility with current environment
+   *
+   * Checks if requested mode can be used based on available credentials/tools.
+   *
+   * @param mode - Coordination mode to validate
+   * @returns True if mode is compatible, false otherwise
+   */ static validateMode(mode) {
+        if (mode === 'auto') {
+            return true; // Auto mode always valid (falls back)
+        }
+        const capabilities = this.detectEnvironment();
+        switch(mode){
+            case 'sdk':
+                return capabilities.hasSDKCredentials;
+            case 'cli':
+                return capabilities.hasCLI;
+            case 'hybrid':
+                return capabilities.hasSDKCredentials && capabilities.hasCLI;
+            default:
+                return false;
+        }
+    }
+    /**
+   * Create coordinator instance based on mode
+   *
+   * Instantiates appropriate coordinator implementation:
+   * - SDK mode: QueryController (Anthropic SDK)
+   * - CLI mode: CLICoordinator (Week 1 implementation)
+   * - Hybrid mode: HybridCoordinator (Week 2 implementation)
+   * - Auto mode: Detects and creates appropriate coordinator
+   *
+   * @param options - Factory configuration options
+   * @returns Promise resolving to ICoordinator instance
+   * @throws Error if mode not implemented or environment incompatible
+   *
+   * @example
+   * ```typescript
+   * // Auto-detect mode
+   * const coordinator = await CoordinatorFactory.create();
+   *
+   * // Explicit SDK mode
+   * const coordinator = await CoordinatorFactory.create({
+   *   mode: 'sdk',
+   *   apiKey: 'sk-ant-...',
+   *   maxConcurrentAgents: 5
+   * });
+   * ```
+   */ static async create(options = {}) {
+        const startTime = Date.now();
+        // Determine effective mode
+        const requestedMode = options.mode === 'auto' || !options.mode ? this.detectMode() : options.mode;
+        this.logger.info('Creating coordinator', {
+            requestedMode: options.mode ?? 'auto',
+            detectedMode: requestedMode
+        });
+        // Validate mode compatibility
+        if (!this.validateMode(requestedMode)) {
+            const capabilities = this.detectEnvironment();
+            throw new Error(`Coordination mode '${requestedMode}' not available in current environment.\n` + `Validation errors: ${capabilities.validationErrors.join(', ')}\n` + `Suggested mode: ${capabilities.suggestedMode}`);
+        }
+        // Create coordinator based on mode
+        let coordinator;
+        switch(requestedMode){
+            case 'sdk':
+                coordinator = await this.createSDKCoordinator(options);
+                break;
+            case 'cli':
+                // CLICoordinator implementation scheduled for Week 1
+                throw new Error('CLI mode not yet implemented (Week 1 roadmap).\n' + 'Use SDK mode for now: CoordinatorFactory.create({ mode: "sdk" })');
+            case 'hybrid':
+                // HybridCoordinator implementation scheduled for Week 2
+                throw new Error('Hybrid mode not yet implemented (Week 2 roadmap).\n' + 'Use SDK mode for now: CoordinatorFactory.create({ mode: "sdk" })');
+            default:
+                throw new Error(`Unknown coordination mode: ${requestedMode}`);
+        }
+        // Initialize coordinator
+        await coordinator.initialize();
+        const initTime = Date.now() - startTime;
+        this.logger.info('Coordinator initialized', {
+            mode: requestedMode,
+            initTimeMs: initTime
+        });
+        return coordinator;
+    }
+    /**
+   * Create SDK coordinator instance (QueryController)
+   *
+   * @private
+   * @param options - Factory options
+   * @returns Promise resolving to QueryController instance
+   */ static async createSDKCoordinator(options) {
+        // Get API key from options or environment
+        const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new Error('SDK mode requires ANTHROPIC_API_KEY.\n' + 'Set environment variable: export ANTHROPIC_API_KEY=sk-ant-...\n' + 'Or pass via options: { apiKey: "sk-ant-..." }');
+        }
+        // Validate API key format
+        if (!apiKey.startsWith('sk-ant-')) {
+            throw new Error(`Invalid API key format. Expected format: sk-ant-..., got: ${apiKey.substring(0, 10)}...`);
+        }
+        // Configure QueryController
+        const config = {
+            maxConcurrentAgents: options.maxConcurrentAgents,
+            defaultTokenBudget: options.defaultTokenBudget,
+            enableDynamicAllocation: options.enableDynamicAllocation
+        };
+        this.logger.debug('Creating SDK coordinator (QueryController)', config);
+        return new QueryController(config);
+    }
+    /**
+   * Get capabilities summary for current environment
+   *
+   * Useful for debugging and environment validation.
+   *
+   * @returns Human-readable capabilities summary
+   *
+   * @example
+   * ```typescript
+   * console.log(CoordinatorFactory.getCapabilitiesSummary());
+   * // Output:
+   * // Environment Capabilities:
+   * // - SDK Credentials: ✓ (ANTHROPIC_API_KEY set)
+   * // - Claude Code CLI: ✗ (not found in PATH)
+   * // - Suggested Mode: sdk
+   * ```
+   */ static getCapabilitiesSummary() {
+        const capabilities = this.detectEnvironment();
+        const lines = [
+            'Environment Capabilities:',
+            `- SDK Credentials: ${capabilities.hasSDKCredentials ? '✓' : '✗'} ${capabilities.hasSDKCredentials ? '(ANTHROPIC_API_KEY set)' : '(ANTHROPIC_API_KEY not set)'}`,
+            `- Claude Code CLI: ${capabilities.hasCLI ? '✓' : '✗'} ${capabilities.hasCLI ? `(found at ${capabilities.cliPath})` : '(not found in PATH)'}`,
+            `- Suggested Mode: ${capabilities.suggestedMode}`
+        ];
+        if (capabilities.validationErrors.length > 0) {
+            lines.push('- Validation Errors:');
+            capabilities.validationErrors.forEach((err)=>{
+                lines.push(`  * ${err}`);
+            });
+        }
+        return lines.join('\n');
+    }
+    /**
+   * Check if factory is ready to create coordinators
+   *
+   * Validates that at least one coordination mode is available.
+   *
+   * @returns True if factory can create coordinators
+   */ static isReady() {
+        const capabilities = this.detectEnvironment();
+        return capabilities.hasSDKCredentials || capabilities.hasCLI;
+    }
+}
+
+//# sourceMappingURL=coordinator-factory.js.map