@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.27

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

@@ -3,13 +3,14 @@
  *
  * Encapsulates Claude CLI process spawning with comprehensive error handling,
  * logging, and timeout management for reliable AI agent execution.
+ *
+ * Uses spawn() with stream-json output format for real-time progress reporting.
  */
-import { exec } from 'node:child_process';
+import { spawn } 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 { createInterface } from 'node:readline';
 import { PROVIDER_CONFIGS } from '../../models/provider.js';
 /**
  * Track active child processes for cleanup on SIGINT
@@ -47,70 +48,91 @@ const registerSigintHandler = (logger) => {
     });
     sigintHandlerRegistered = true;
 };
+/**
+ * Parse a stream-json line and extract a human-readable summary.
+ * Returns null for events that aren't meaningful to display.
+ */
+function parseStreamLine(line) {
+    try {
+        const event = JSON.parse(line);
+        const type = event.type;
+        if (type === 'assistant') {
+            const message = event.message;
+            if (!message)
+                return { summary: null, type, verboseText: null };
+            const content = message.content;
+            if (!content || content.length === 0)
+                return { summary: null, type, verboseText: null };
+            // Collect all text for verbose output
+            const verboseParts = [];
+            let summary = null;
+            for (const block of content) {
+                if (block.type === 'tool_use') {
+                    const toolName = block.name;
+                    const input = block.input;
+                    const filePath = input?.file_path || input?.path || input?.pattern || input?.command;
+                    if (filePath) {
+                        const shortPath = String(filePath).length > 60
+                            ? '...' + String(filePath).slice(-57)
+                            : String(filePath);
+                        summary = summary ?? `🔧 ${toolName}: ${shortPath}`;
+                    }
+                    else {
+                        summary = summary ?? `🔧 ${toolName}`;
+                    }
+                    // Verbose: show tool name + full input as JSON
+                    verboseParts.push(`[tool_use] ${toolName}: ${JSON.stringify(input, null, 2)}`);
+                }
+                else if (block.type === 'tool_result') {
+                    const resultContent = block.content;
+                    if (resultContent) {
+                        verboseParts.push(resultContent);
+                    }
+                }
+                else if (block.type === 'text') {
+                    const text = (block.text || '').trim();
+                    if (text.length > 0) {
+                        summary = summary ?? `💬 ${text.split('\n')[0].slice(0, 80)}`;
+                        verboseParts.push(text);
+                    }
+                }
+            }
+            return {
+                summary,
+                type,
+                verboseText: verboseParts.length > 0 ? verboseParts.join('\n') : null,
+            };
+        }
+        if (type === 'result') {
+            const resultText = event.result;
+            return { finalOutput: resultText ?? '', summary: null, type, verboseText: null };
+        }
+        // system, rate_limit_event, etc. — skip
+        return { summary: null, type, verboseText: null };
+    }
+    catch {
+        // Unparseable line — skip
+        return { summary: null, type: 'unknown', verboseText: null };
+    }
+}
 /**
  * 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
- * })
- * ```
+ * Uses stream-json output format for real-time progress reporting.
  */
 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
@@ -123,6 +145,7 @@ export class ClaudeAgentRunner {
                 exitCode: -1,
                 output: '',
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
         // Log execution start with metadata
@@ -135,127 +158,79 @@ export class ClaudeAgentRunner {
         // 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;
+                const { onPrompt, onResponse, onStream, ...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');
+            const tempFile = join(tempDir, 'prompt.txt');
             await writeFile(tempFile, prompt, 'utf8');
-            // Write system prompt to temp file if provided (Claude-only feature)
-            // Uses --system-prompt (full replacement) instead of --append-system-prompt
-            // to prevent the default Claude Code system prompt from competing with
-            // our output format instructions (e.g., YAML-only output).
-            let systemPromptArg = '';
+            // Write system prompt to temp file if provided
+            let systemPromptArg = [];
             if (options.systemPrompt) {
                 const systemPromptFile = join(tempDir, 'system-prompt.txt');
                 await writeFile(systemPromptFile, options.systemPrompt, 'utf8');
-                systemPromptArg = `--system-prompt "$(cat '${systemPromptFile}')"`;
+                systemPromptArg = ['--system-prompt', options.systemPrompt];
+            }
+            // Build command args
+            const args = [...this.config.flags];
+            if (options.model) {
+                args.push(this.config.modelFlag, options.model);
+            }
+            if (options.flags) {
+                args.push(...options.flags);
             }
-            // Build command with temp file
-            const flags = this.config.flags.join(' ');
-            const modelArg = options.model ? `${this.config.modelFlag} ${options.model}` : '';
-            const extraFlags = options.flags ? options.flags.join(' ') : '';
-            const command = `${this.config.command} ${flags} ${modelArg} ${extraFlags} ${systemPromptArg} < "${tempFile}"`.replace(/\s+/g, ' ').trim();
+            if (options.sessionName) {
+                args.push('--name', options.sessionName);
+            }
+            args.push(...systemPromptArg);
             // Log the command being executed
             this.logger.info({
+                args: args.join(' '),
                 promptLength: prompt.length,
                 tempFile,
-            }, 'Executing command with temp file');
-            // Use exec instead of spawn for better shell compatibility
-            // Note: setting CLAUDECODE to undefined in a spread does NOT remove it —
-            // Node coerces undefined to the string "undefined", which is still truthy.
-            // We must delete the key from the env object to fully unset it.
+            }, 'Spawning Claude process with stream-json output');
+            // Spawn the process
             const env = { ...process.env };
             delete env.CLAUDECODE;
-            const execOptions = {
+            const result = await this.spawnAndStream({
+                args,
+                cwd: options.cwd,
                 env,
-                maxBuffer: 10 * 1024 * 1024, // 10MB buffer
-                shell: process.env.SHELL || '/bin/bash',
+                onStream: options.onStream,
+                onStreamVerbose: options.onStreamVerbose,
+                startTime,
+                stdinFile: tempFile,
                 timeout,
-            };
-            if (options.cwd) {
-                execOptions.cwd = options.cwd;
-                this.logger.info({ cwd: options.cwd }, 'Setting working directory for agent');
-            }
-            const { stderr, stdout } = await execAsync(command, execOptions);
-            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 = {
+            });
+            return this.returnWithCallback({
                 agentType: options.agentType,
-                duration,
-                errors: stderrData,
-                exitCode: 0,
-                output: stdoutData,
-                success: true,
-            };
-            return this.returnWithCallback(result, options.onResponse);
+                ...result,
+                transport: 'subprocess',
+            }, 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');
+            const err = error;
+            this.logger.error({ duration, error: err.message }, 'Claude agent execution error');
             return this.returnWithCallback({
                 agentType: options.agentType,
                 duration,
-                errors: errorContext,
-                exitCode: isTimeout ? 124 : exitCode,
-                output: stdoutData,
+                errors: err.message,
+                exitCode: -1,
+                output: '',
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
         finally {
-            // Clean up temp file and directory
             if (tempDir) {
                 try {
                     await rm(tempDir, { force: true, recursive: true });
@@ -268,73 +243,110 @@ export class ClaudeAgentRunner {
         }
     }
     /**
-     * Build detailed error context for debugging process failures
-     * @private
+     * Spawn Claude process and stream output in real-time
      */
-    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;
+    async spawnAndStream(opts) {
+        const { args, cwd, env, onStream, onStreamVerbose, startTime, stdinFile, timeout } = opts;
+        return new Promise((resolve) => {
+            // Use shell to handle stdin redirection from file
+            const shellCommand = `${this.config.command} ${args.map((a) => this.shellEscape(a)).join(' ')} < "${stdinFile}"`;
+            const child = spawn(shellCommand, [], {
+                cwd,
+                env,
+                shell: process.env.SHELL || '/bin/bash',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            activeProcesses.add(child);
+            let stderrData = '';
+            let finalOutput = '';
+            let timedOut = false;
+            // Set up timeout
+            const timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, timeout);
+            // Read stderr
+            child.stderr?.on('data', (chunk) => {
+                stderrData += chunk.toString();
+            });
+            // Parse stdout line by line (stream-json = JSONL)
+            const rl = createInterface({ input: child.stdout });
+            rl.on('line', (line) => {
+                if (!line.trim())
+                    return;
+                const parsed = parseStreamLine(line);
+                // If this is the final result, capture it
+                if (parsed.finalOutput !== undefined) {
+                    finalOutput = parsed.finalOutput;
                 }
-                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;
+                // Fire verbose callback with raw text (everything Claude says)
+                if (parsed.verboseText && onStreamVerbose) {
+                    try {
+                        onStreamVerbose(parsed.verboseText);
+                    }
+                    catch {
+                        // Never let callback errors kill the stream
+                    }
                 }
-                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;
+                // Fire summary callback for meaningful events (spinner updates)
+                if (parsed.summary && onStream) {
+                    try {
+                        onStream(parsed.summary);
+                    }
+                    catch {
+                        // Never let callback errors kill the stream
+                    }
                 }
-                // 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');
+            });
+            child.on('close', (code, signal) => {
+                clearTimeout(timeoutHandle);
+                activeProcesses.delete(child);
+                const duration = Date.now() - startTime;
+                const exitCode = code ?? -1;
+                const wasKilled = signal !== null;
+                const isTimeout = timedOut;
+                if (isTimeout) {
+                    this.logger.error({ duration, timeout }, 'Claude CLI process timeout');
+                }
+                else if (exitCode !== 0) {
+                    this.logger.error({ duration, exitCode, signal, wasKilled }, 'Claude CLI process error');
+                }
+                else {
+                    this.logger.info({ duration, outputLength: finalOutput.length, stderrLength: stderrData.length }, 'Claude CLI process completed successfully');
+                }
+                // Build error context for failures
+                let errors = stderrData;
+                if (isTimeout) {
+                    errors = `Process timeout after ${duration}ms\n${stderrData}`;
+                }
+                else if (wasKilled) {
+                    errors = `Process killed by signal ${signal} (exit code ${exitCode})\n${stderrData}`;
+                }
+                else if (exitCode !== 0) {
+                    errors = `Process exited with code ${exitCode}\n${stderrData}`;
+                }
+                resolve({
+                    duration,
+                    errors,
+                    exitCode: isTimeout ? 124 : exitCode,
+                    output: finalOutput,
+                    success: exitCode === 0 && !isTimeout,
+                });
+            });
+            child.on('error', (err) => {
+                clearTimeout(timeoutHandle);
+                activeProcesses.delete(child);
+                const duration = Date.now() - startTime;
+                this.logger.error({ duration, error: err.message }, 'Failed to spawn Claude process');
+                resolve({
+                    duration,
+                    errors: `Spawn error: ${err.message}`,
+                    exitCode: -1,
+                    output: finalOutput,
+                    success: false,
+                });
+            });
+        });
     }
     /**
      * Invoke onResponse callback and return result
@@ -351,4 +363,14 @@ export class ClaudeAgentRunner {
         }
         return result;
     }
+    /**
+     * Shell-escape a single argument
+     */
+    shellEscape(arg) {
+        // If arg contains no special characters, return as-is
+        if (/^[\w./:=@-]+$/.test(arg))
+            return arg;
+        // Otherwise wrap in single quotes, escaping existing single quotes
+        return `'${arg.replace(/'/g, "'\\''")}'`;
+    }
 }

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

@@ -117,6 +117,7 @@ export class GeminiAgentRunner {
                 exitCode: -1,
                 output: '',
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
         // Preprocess prompt to inline @file references
@@ -187,6 +188,7 @@ export class GeminiAgentRunner {
                 exitCode: 0,
                 output: stdoutData,
                 success: true,
+                transport: 'subprocess',
             };
             return this.returnWithCallback(result, options.onResponse);
         }
@@ -232,6 +234,7 @@ export class GeminiAgentRunner {
                 exitCode: isTimeout ? 124 : exitCode,
                 output: stdoutData,
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
     }

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

@@ -3,6 +3,7 @@
  */
 export * from './agent-runner-factory.js';
 export * from './agent-runner.js';
+export * from './channel-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

@@ -3,6 +3,7 @@
  */
 export * from './agent-runner-factory.js';
 export * from './agent-runner.js';
+export * from './channel-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.js

@@ -123,6 +123,7 @@ export class OpenCodeAgentRunner {
                 exitCode: -1,
                 output: '',
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
         // Log execution start with metadata
@@ -195,6 +196,7 @@ export class OpenCodeAgentRunner {
                 exitCode: 0,
                 output: parsedOutput,
                 success: true,
+                transport: 'subprocess',
             };
             return this.returnWithCallback(result, options.onResponse);
         }
@@ -240,6 +242,7 @@ export class OpenCodeAgentRunner {
                 exitCode: isTimeout ? 124 : exitCode,
                 output: stdoutData,
                 success: false,
+                transport: 'subprocess',
             }, options.onResponse);
         }
         finally {

package/dist/services/file-system/file-manager.d.ts

@@ -109,6 +109,17 @@ export declare class FileManager {
      * await fileManager.writeFile('docs/epics/epic-1.md', epicContent)
      */
     writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Delete a file from disk
+     *
+     * Uses fs.remove which is idempotent — safe to call if file doesn't exist.
+     *
+     * @param path - Path to the file to delete
+     * @throws {FileSystemError} If file cannot be deleted (permission denied, etc.)
+     * @example
+     * await fileManager.deleteFile('docs/stories/story.md.lock')
+     */
+    deleteFile(path: string): Promise<void>;
     /**
      * Match a file name against a simple glob pattern
      *

package/dist/services/file-system/file-manager.js

@@ -233,6 +233,32 @@ export class FileManager {
             });
         }
     }
+    /**
+     * Delete a file from disk
+     *
+     * Uses fs.remove which is idempotent — safe to call if file doesn't exist.
+     *
+     * @param path - Path to the file to delete
+     * @throws {FileSystemError} If file cannot be deleted (permission denied, etc.)
+     * @example
+     * await fileManager.deleteFile('docs/stories/story.md.lock')
+     */
+    async deleteFile(path) {
+        this.logger.debug('Deleting file: %s', path);
+        try {
+            await fs.remove(path);
+            this.logger.debug('File deleted successfully: %s', path);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error deleting file %s: %O', path, err);
+            throw new FileSystemError(`Failed to delete file: ${path}: ${err.message}`, {
+                operation: 'deleteFile',
+                originalError: err.message,
+                path,
+            });
+        }
+    }
     /**
      * Match a file name against a simple glob pattern
      *