@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/agents/claude-agent-runner.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ClaudeAgentRunner Service
+ *
+ * Encapsulates Claude CLI process spawning with comprehensive error handling,
+ * logging, and timeout management for reliable AI agent execution.
+ */
+import type pino from 'pino';
+import type { AgentOptions, AgentResult } from '../../models/index.js';
+import type { AIProvider } from '../../models/provider.js';
+import type { AIProviderRunner } from './agent-runner.js';
+/**
+ * ClaudeAgentRunner service for executing Claude AI agents
+ *
+ * Spawns Claude CLI processes to execute AI agents with specified prompts.
+ * Handles timeout, error collection, result formatting, and process cleanup.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = new ClaudeAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export declare class ClaudeAgentRunner implements AIProviderRunner {
+    readonly provider: AIProvider;
+    private readonly config;
+    private readonly logger;
+    /**
+     * Create a new ClaudeAgentRunner instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Get the count of active processes
+     * (Useful for testing and monitoring purposes)
+     *
+     * @returns Number of currently active child processes
+     */
+    getActiveProcessCount(): number;
+    /**
+     * Execute a Claude AI agent with the specified prompt and options
+     *
+     * This method spawns a Claude CLI process, captures output, handles errors,
+     * and enforces timeouts. It never throws exceptions - all errors are returned
+     * as typed AgentResult objects.
+     *
+     * @param prompt - The prompt to execute with the agent
+     * @param options - Agent execution options (without prompt)
+     * @returns AgentResult with success status, output, errors, and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await runner.runAgent('@.bmad-core/agents/architect.md Create epic for user auth', {
+     *   agentType: 'architect',
+     *   timeout: 300000
+     * })
+     *
+     * if (result.success) {
+     *   console.log('Output:', result.output)
+     * } else {
+     *   console.error('Error:', result.errors)
+     * }
+     * ```
+     */
+    runAgent(prompt: string, options: Omit<AgentOptions, 'prompt'>): Promise<AgentResult>;
+    /**
+     * Build detailed error context for debugging process failures
+     * @private
+     */
+    private buildErrorContext;
+    /**
+     * Invoke onResponse callback and return result
+     * @private
+     */
+    private returnWithCallback;
+}

package/dist/services/agents/claude-agent-runner.js

@@ -0,0 +1,332 @@
+/**
+ * ClaudeAgentRunner Service
+ *
+ * Encapsulates Claude CLI process spawning with comprehensive error handling,
+ * logging, and timeout management for reliable AI agent execution.
+ */
+import { exec } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+import { PROVIDER_CONFIGS } from '../../models/provider.js';
+/**
+ * Track active child processes for cleanup on SIGINT
+ */
+const activeProcesses = new Set();
+/**
+ * Track if SIGINT handler has been registered
+ */
+let sigintHandlerRegistered = false;
+/**
+ * Register SIGINT handler for graceful process cleanup
+ */
+const registerSigintHandler = (logger) => {
+    if (sigintHandlerRegistered)
+        return;
+    process.on('SIGINT', () => {
+        logger.info({
+            activeProcessCount: activeProcesses.size,
+        }, 'Received SIGINT, cleaning up active processes');
+        // Kill all active child processes
+        for (const childProcess of activeProcesses) {
+            try {
+                childProcess.kill('SIGTERM');
+            }
+            catch (error) {
+                logger.error({
+                    error: error.message,
+                }, 'Error killing child process');
+            }
+        }
+        // Clear the set
+        activeProcesses.clear();
+        // Exit the main process
+        process.exit(130); // 130 = 128 + SIGINT signal number (2)
+    });
+    sigintHandlerRegistered = true;
+};
+/**
+ * ClaudeAgentRunner service for executing Claude AI agents
+ *
+ * Spawns Claude CLI processes to execute AI agents with specified prompts.
+ * Handles timeout, error collection, result formatting, and process cleanup.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = new ClaudeAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export class ClaudeAgentRunner {
+    provider = 'claude';
+    config = PROVIDER_CONFIGS.claude;
+    logger;
+    /**
+     * Create a new ClaudeAgentRunner instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+        registerSigintHandler(logger);
+    }
+    /**
+     * Get the count of active processes
+     * (Useful for testing and monitoring purposes)
+     *
+     * @returns Number of currently active child processes
+     */
+    getActiveProcessCount() {
+        return activeProcesses.size;
+    }
+    /**
+     * Execute a Claude AI agent with the specified prompt and options
+     *
+     * This method spawns a Claude CLI process, captures output, handles errors,
+     * and enforces timeouts. It never throws exceptions - all errors are returned
+     * as typed AgentResult objects.
+     *
+     * @param prompt - The prompt to execute with the agent
+     * @param options - Agent execution options (without prompt)
+     * @returns AgentResult with success status, output, errors, and metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await runner.runAgent('@.bmad-core/agents/architect.md Create epic for user auth', {
+     *   agentType: 'architect',
+     *   timeout: 300000
+     * })
+     *
+     * if (result.success) {
+     *   console.log('Output:', result.output)
+     * } else {
+     *   console.error('Error:', result.errors)
+     * }
+     * ```
+     */
+    async runAgent(prompt, options) {
+        const startTime = Date.now();
+        const timeout = options.timeout ?? 1_800_000; // Default 30 minutes
+        // Input validation
+        if (!prompt || prompt.trim().length === 0) {
+            return this.returnWithCallback({
+                agentType: options.agentType,
+                duration: Date.now() - startTime,
+                errors: 'Prompt is required and cannot be empty',
+                exitCode: -1,
+                output: '',
+                success: false,
+            }, options.onResponse);
+        }
+        // Log execution start with metadata
+        this.logger.info({
+            agentType: options.agentType,
+            promptLength: prompt.length,
+            references: options.references?.length ?? 0,
+            timeout,
+        }, 'Executing Claude agent');
+        // Invoke onPrompt callback if provided
+        if (options.onPrompt) {
+            try {
+                // Create options object without callbacks for the callback
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { onPrompt, onResponse, ...callbackOptions } = options;
+                await onPrompt(prompt, callbackOptions);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message }, 'Error in onPrompt callback');
+            }
+        }
+        // For large prompts or prompts with special characters, use a temp file
+        // This avoids shell escaping issues
+        let tempDir = null;
+        let tempFile = null;
+        let stdoutData = '';
+        let stderrData = '';
+        try {
+            // Create temp directory and file
+            tempDir = await mkdtemp(join(tmpdir(), 'claude-prompt-'));
+            tempFile = join(tempDir, 'prompt.txt');
+            await writeFile(tempFile, prompt, 'utf8');
+            // Build command with temp file
+            const flags = this.config.flags.join(' ');
+            const command = `${this.config.command} ${flags} < "${tempFile}"`;
+            // Log the command being executed
+            this.logger.info({
+                promptLength: prompt.length,
+                tempFile,
+            }, 'Executing command with temp file');
+            // Use exec instead of spawn for better shell compatibility
+            const { stderr, stdout } = await execAsync(command, {
+                env: process.env,
+                maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+                shell: process.env.SHELL || '/bin/bash',
+                timeout,
+            });
+            stdoutData = stdout;
+            stderrData = stderr;
+            const duration = Date.now() - startTime;
+            this.logger.info({
+                duration,
+                stderrLength: stderrData.length,
+                stdoutLength: stdoutData.length,
+            }, 'Claude CLI process completed successfully');
+            const result = {
+                agentType: options.agentType,
+                duration,
+                errors: stderrData,
+                exitCode: 0,
+                output: stdoutData,
+                success: true,
+            };
+            return this.returnWithCallback(result, options.onResponse);
+        }
+        catch (error) {
+            // Handle exec errors (includes timeout, non-zero exit, etc.)
+            const duration = Date.now() - startTime;
+            // Extract stdout/stderr from exec error if available
+            const execError = error;
+            if (execError.stdout)
+                stdoutData = execError.stdout;
+            if (execError.stderr)
+                stderrData = execError.stderr;
+            const exitCode = execError.code ?? -1;
+            const isTimeout = execError.killed === true && execError.signal === 'SIGTERM';
+            const wasKilled = execError.killed === true;
+            const signal = execError.signal ?? null;
+            // Build detailed error context for debugging
+            const errorContext = this.buildErrorContext({
+                cmd: execError.cmd,
+                duration,
+                exitCode,
+                isTimeout,
+                signal,
+                stderrData,
+                stdoutData,
+                wasKilled,
+            });
+            this.logger.error({
+                cmd: execError.cmd,
+                duration,
+                error: execError.message,
+                exitCode,
+                isTimeout,
+                signal,
+                stderrLength: stderrData.length,
+                stdoutLength: stdoutData.length,
+                wasKilled,
+            }, isTimeout ? 'Claude CLI process timeout' : 'Claude CLI process error');
+            return this.returnWithCallback({
+                agentType: options.agentType,
+                duration,
+                errors: errorContext,
+                exitCode: isTimeout ? 124 : exitCode,
+                output: stdoutData,
+                success: false,
+            }, options.onResponse);
+        }
+        finally {
+            // Clean up temp file and directory
+            if (tempDir) {
+                try {
+                    await rm(tempDir, { force: true, recursive: true });
+                    this.logger.debug({ tempDir }, 'Cleaned up temp directory');
+                }
+                catch (cleanupError) {
+                    this.logger.warn({ error: cleanupError.message, tempDir }, 'Failed to clean up temp directory');
+                }
+            }
+        }
+    }
+    /**
+     * Build detailed error context for debugging process failures
+     * @private
+     */
+    buildErrorContext(info) {
+        const lines = [];
+        // Determine the type of failure
+        if (info.isTimeout) {
+            lines.push(`Process timeout after ${info.duration}ms`);
+        }
+        else if (info.wasKilled) {
+            lines.push('Process was killed externally');
+            // Explain common exit codes
+            switch (info.exitCode) {
+                case 130: {
+                    lines.push('Exit code 130 = SIGINT (user interrupt, Ctrl+C)');
+                    break;
+                }
+                case 137: {
+                    lines.push('Exit code 137 = SIGKILL (process forcefully killed)', 'Possible causes:', '  - System OOM killer', '  - Exceeded memory limits', '  - Docker/container killed the process');
+                    break;
+                }
+                case 143: {
+                    lines.push('Exit code 143 = SIGTERM (process terminated)', 'Possible causes:', '  - System OOM killer terminated the process', '  - Another process sent SIGTERM', '  - Parent process cleanup', '  - Docker/container resource limits');
+                    break;
+                }
+                // No default
+            }
+            if (info.signal) {
+                lines.push(`Signal received: ${info.signal}`);
+            }
+            else {
+                lines.push('No signal information available (signal: null)');
+            }
+        }
+        else {
+            lines.push(`Process exited with code ${info.exitCode}`);
+        }
+        // Add duration context
+        lines.push(`Duration: ${(info.duration / 1000).toFixed(2)}s`);
+        // Add output context
+        if (info.stdoutData.length > 0) {
+            lines.push(`Stdout (${info.stdoutData.length} chars):`);
+            // Truncate if too long, show last 500 chars which are often most relevant
+            const truncatedStdout = info.stdoutData.length > 500 ? `...[truncated]...\n${info.stdoutData.slice(-500)}` : info.stdoutData;
+            lines.push(truncatedStdout);
+        }
+        else {
+            lines.push('Stdout: (empty - no output captured)');
+        }
+        if (info.stderrData.length > 0) {
+            lines.push(`Stderr (${info.stderrData.length} chars):`);
+            const truncatedStderr = info.stderrData.length > 500 ? `...[truncated]...\n${info.stderrData.slice(-500)}` : info.stderrData;
+            lines.push(truncatedStderr);
+        }
+        else {
+            lines.push('Stderr: (empty - no error output)');
+        }
+        // Add command for reference (truncate if too long)
+        if (info.cmd) {
+            const truncatedCmd = info.cmd.length > 200 ? `${info.cmd.slice(0, 200)}...[truncated]` : info.cmd;
+            lines.push(`Command: ${truncatedCmd}`);
+        }
+        // Add troubleshooting suggestions for empty output
+        if (info.stdoutData.length === 0 && info.stderrData.length === 0) {
+            lines.push('', 'Troubleshooting (no output captured):', '  1. Check system resources (memory, CPU)', '  2. Verify Claude CLI is properly installed: `claude --version`', '  3. Check for Claude API issues', '  4. Review system logs: `dmesg | tail -50` (for OOM killer)', '  5. Try running the command manually to see output');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Invoke onResponse callback and return result
+     * @private
+     */
+    async returnWithCallback(result, onResponse) {
+        if (onResponse) {
+            try {
+                await onResponse(result);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message }, 'Error in onResponse callback');
+            }
+        }
+        return result;
+    }
+}

package/dist/services/agents/gemini-agent-runner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * GeminiAgentRunner Service
+ *
+ * Encapsulates Gemini CLI process spawning with comprehensive error handling,
+ * logging, and timeout management for reliable AI agent execution.
+ *
+ * Key difference from Claude: Gemini CLI doesn't support @file references natively,
+ * so this runner preprocesses prompts to inline file content before execution.
+ */
+import type pino from 'pino';
+import type { AgentOptions, AgentResult } from '../../models/index.js';
+import type { AIProvider } from '../../models/provider.js';
+import type { AIProviderRunner } from './agent-runner.js';
+/**
+ * GeminiAgentRunner service for executing Gemini AI agents
+ *
+ * Spawns Gemini CLI processes to execute AI agents with specified prompts.
+ * Preprocesses @file references to inline file content since Gemini CLI
+ * doesn't support native file references like Claude.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'agent-runner' })
+ * const runner = new GeminiAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export declare class GeminiAgentRunner implements AIProviderRunner {
+    readonly provider: AIProvider;
+    private readonly config;
+    private readonly logger;
+    /**
+     * Create a new GeminiAgentRunner instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Get the count of active processes
+     * (Useful for testing and monitoring purposes)
+     *
+     * @returns Number of currently active child processes
+     */
+    getActiveProcessCount(): number;
+    /**
+     * Execute a Gemini AI agent with the specified prompt and options
+     *
+     * This method spawns a Gemini CLI process, captures output, handles errors,
+     * and enforces timeouts. It preprocesses @file references to inline content
+     * since Gemini CLI doesn't support native file references.
+     *
+     * @param prompt - The prompt to execute with the agent
+     * @param options - Agent execution options (without prompt)
+     * @returns AgentResult with success status, output, errors, and metadata
+     */
+    runAgent(prompt: string, options: Omit<AgentOptions, 'prompt'>): Promise<AgentResult>;
+    /**
+     * Build detailed error context for debugging process failures
+     * @private
+     */
+    private buildErrorContext;
+    /**
+     * Preprocess prompt to inline @file references
+     *
+     * Since Gemini CLI doesn't support @file syntax natively, this method
+     * finds all @file references and replaces them with the actual file content.
+     *
+     * @param prompt - The original prompt with @file references
+     * @param basePath - Base path for resolving relative file paths
+     * @returns Preprocessed prompt with inlined file content
+     */
+    private preprocessPrompt;
+    /**
+     * Invoke onResponse callback and return result
+     * @private
+     */
+    private returnWithCallback;
+}