@hyperdrive.bot/bmad-workflow 1.0.3 → 1.0.6

package/dist/models/provider.d.ts

@@ -4,7 +4,7 @@
 /**
  * Supported AI providers
  */
-export type AIProvider = 'claude' | 'gemini';
+export type AIProvider = 'claude' | 'gemini' | 'opencode';
 /**
  * Provider-specific configuration
  */

package/dist/models/provider.js

@@ -15,4 +15,9 @@ export const PROVIDER_CONFIGS = {
         flags: ['-p', '--yolo'],
         supportsFileReferences: false,
     },
+    opencode: {
+        command: 'opencode',
+        flags: ['run', '--format', 'json'],
+        supportsFileReferences: true,
+    },
 };

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

@@ -5,6 +5,7 @@
  */
 import { ClaudeAgentRunner } from './claude-agent-runner.js';
 import { GeminiAgentRunner } from './gemini-agent-runner.js';
+import { OpenCodeAgentRunner } from './opencode-agent-runner.js';
 /**
  * Create an AI provider runner for the specified provider
  *
@@ -28,6 +29,9 @@ export function createAgentRunner(provider, logger) {
         case 'gemini': {
             return new GeminiAgentRunner(logger);
         }
+        case 'opencode': {
+            return new OpenCodeAgentRunner(logger);
+        }
         default: {
             throw new Error(`Unsupported AI provider: ${provider}`);
         }
@@ -40,5 +44,5 @@ export function createAgentRunner(provider, logger) {
  * @returns true if the provider is supported
  */
 export function isProviderSupported(provider) {
-    return provider === 'claude' || provider === 'gemini';
+    return provider === 'claude' || provider === 'gemini' || provider === 'opencode';
 }

package/dist/services/agents/index.d.ts

@@ -5,3 +5,4 @@ export * from './agent-runner-factory.js';
 export * from './agent-runner.js';
 export * from './claude-agent-runner.js';
 export * from './gemini-agent-runner.js';
+export * from './opencode-agent-runner.js';

package/dist/services/agents/index.js

@@ -5,3 +5,4 @@ export * from './agent-runner-factory.js';
 export * from './agent-runner.js';
 export * from './claude-agent-runner.js';
 export * from './gemini-agent-runner.js';
+export * from './opencode-agent-runner.js';

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

@@ -0,0 +1,92 @@
+/**
+ * OpenCodeAgentRunner Service
+ *
+ * Encapsulates Open Code 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';
+/**
+ * OpenCodeAgentRunner service for executing Open Code AI agents
+ *
+ * Spawns Open Code 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 OpenCodeAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export declare class OpenCodeAgentRunner implements AIProviderRunner {
+    readonly provider: AIProvider;
+    private readonly config;
+    private readonly logger;
+    /**
+     * Create a new OpenCodeAgentRunner 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 an Open Code AI agent with the specified prompt and options
+     *
+     * This method spawns an Open Code 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>;
+    /**
+     * Parse JSON output from Open Code CLI
+     *
+     * Open Code's --format json outputs structured events.
+     * This method extracts the actual response content.
+     *
+     * @param stdoutData - Raw stdout from Open Code CLI
+     * @returns Extracted content string
+     * @private
+     */
+    private parseJsonOutput;
+    /**
+     * Build detailed error context for debugging process failures
+     * @private
+     */
+    private buildErrorContext;
+    /**
+     * Invoke onResponse callback and return result
+     * @private
+     */
+    private returnWithCallback;
+}

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

@@ -0,0 +1,392 @@
+/**
+ * OpenCodeAgentRunner Service
+ *
+ * Encapsulates Open Code 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;
+};
+/**
+ * OpenCodeAgentRunner service for executing Open Code AI agents
+ *
+ * Spawns Open Code 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 OpenCodeAgentRunner(logger)
+ * const result = await runner.runAgent({
+ *   prompt: '@.bmad-core/agents/architect.md Create epic for user auth',
+ *   agentType: 'architect',
+ *   timeout: 300000
+ * })
+ * ```
+ */
+export class OpenCodeAgentRunner {
+    provider = 'opencode';
+    config = PROVIDER_CONFIGS.opencode;
+    logger;
+    /**
+     * Create a new OpenCodeAgentRunner 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 an Open Code AI agent with the specified prompt and options
+     *
+     * This method spawns an Open Code 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 Open Code 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(), 'opencode-prompt-'));
+            tempFile = join(tempDir, 'prompt.txt');
+            await writeFile(tempFile, prompt, 'utf8');
+            // Build command with --file flag (Open Code specific)
+            // Format: opencode run --format json --file "${tempFile}"
+            const flags = this.config.flags.join(' ');
+            const command = `${this.config.command} ${flags} --file "${tempFile}"`;
+            // Log the command being executed
+            this.logger.info({
+                command,
+                promptLength: prompt.length,
+                tempFile,
+            }, 'Executing command with temp file');
+            // Use exec 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,
+            }, 'Open Code CLI process completed successfully');
+            // Parse JSON output from Open Code
+            const parsedOutput = this.parseJsonOutput(stdoutData);
+            const result = {
+                agentType: options.agentType,
+                duration,
+                errors: stderrData,
+                exitCode: 0,
+                output: parsedOutput,
+                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 ? 'Open Code CLI process timeout' : 'Open Code 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');
+                }
+            }
+        }
+    }
+    /**
+     * Parse JSON output from Open Code CLI
+     *
+     * Open Code's --format json outputs structured events.
+     * This method extracts the actual response content.
+     *
+     * @param stdoutData - Raw stdout from Open Code CLI
+     * @returns Extracted content string
+     * @private
+     */
+    parseJsonOutput(stdoutData) {
+        if (!stdoutData || stdoutData.trim().length === 0) {
+            return '';
+        }
+        try {
+            const parsed = JSON.parse(stdoutData);
+            // Try common JSON response structures
+            // Open Code may output different structures depending on version
+            if (typeof parsed === 'string') {
+                return parsed;
+            }
+            if (parsed.content) {
+                return String(parsed.content);
+            }
+            if (parsed.message) {
+                return String(parsed.message);
+            }
+            if (parsed.response) {
+                return String(parsed.response);
+            }
+            if (parsed.output) {
+                return String(parsed.output);
+            }
+            if (parsed.text) {
+                return String(parsed.text);
+            }
+            // If we have a result array, try to extract content
+            if (Array.isArray(parsed)) {
+                const messages = parsed
+                    .filter((item) => item.type === 'message' || item.content || item.text)
+                    .map((item) => item.content || item.text || item.message || '')
+                    .filter(Boolean);
+                if (messages.length > 0) {
+                    return messages.join('\n');
+                }
+            }
+            // Fallback: stringify the parsed object
+            this.logger.debug({ parsedKeys: Object.keys(parsed) }, 'Unknown JSON structure, returning stringified');
+            return JSON.stringify(parsed, null, 2);
+        }
+        catch {
+            // JSON parsing failed, return raw output
+            this.logger.debug({ stdoutLength: stdoutData.length }, 'JSON parsing failed, returning raw output');
+            return stdoutData;
+        }
+    }
+    /**
+     * 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 Open Code CLI is properly installed: `opencode --version`', '  3. Check for Open Code 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;
+    }
+}