@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.27

package/dist/services/agents/channel-session-manager.js

@@ -0,0 +1,260 @@
+/**
+ * ChannelSessionManager — Agent Lifecycle Manager
+ *
+ * Manages the lifecycle of Channel-connected Claude Code agent sessions:
+ * start (with discovery polling), health check (ping/pong), stop, and cleanup.
+ *
+ * Used by the orchestrator to pre-provision agent sessions before workflow runs
+ * and guarantee clean shutdown on errors or SIGINT.
+ */
+import { randomUUID } from 'node:crypto';
+import { spawn as nodeSpawn } from 'node:child_process';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _discoveryModule = null;
+function loadDiscovery() {
+    if (!_discoveryModule) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _discoveryModule = require('@hyperdrive.bot/claude-channels/dist/services/discovery.js');
+    }
+    return _discoveryModule;
+}
+const defaultListAgents = () => loadDiscovery().listAgents();
+const defaultDeregister = (sessionId) => loadDiscovery().deregisterAgent(sessionId);
+/**
+ * Error thrown when agent session start times out waiting for discovery registration
+ */
+export class SessionStartTimeoutError extends Error {
+    agentType;
+    timeoutMs;
+    constructor(agentType, timeoutMs) {
+        super(`Agent session '${agentType}' failed to register within ${timeoutMs}ms`);
+        this.name = 'SessionStartTimeoutError';
+        this.agentType = agentType;
+        this.timeoutMs = timeoutMs;
+    }
+}
+const DEFAULT_START_TIMEOUT = 30_000;
+const DEFAULT_HEALTH_TIMEOUT = 2_000;
+const POLL_INTERVAL = 500;
+/**
+ * Manages Channel-connected Claude Code agent session lifecycles.
+ *
+ * Handles spawning, discovery polling, health checks, graceful shutdown,
+ * and SIGINT cleanup for multiple concurrent agent sessions.
+ */
+export class ChannelSessionManager {
+    static sigintRegistered = false;
+    sessions = new Map();
+    logger;
+    listAgentsFn;
+    deregisterAgentFn;
+    spawnFn;
+    constructor(logger, deps = {}) {
+        this.logger = logger;
+        this.listAgentsFn = deps.listAgents ?? defaultListAgents;
+        this.deregisterAgentFn = deps.deregisterAgent ?? defaultDeregister;
+        this.spawnFn = deps.spawn ?? nodeSpawn;
+        this.registerSigintHandler();
+    }
+    /**
+     * Start a new agent session and wait for it to register via discovery.
+     *
+     * Spawns a Claude Code subprocess with --channel flag, then polls listAgents()
+     * at 500ms intervals until a new AgentRegistration appears. Returns a SessionHandle
+     * on success, throws SessionStartTimeoutError if discovery times out.
+     *
+     * @param agentType - Agent type identifier (used to match discovery registration)
+     * @param config - Session configuration
+     * @returns SessionHandle with session details
+     * @throws SessionStartTimeoutError if agent doesn't register within startTimeout
+     */
+    async startAgentSession(agentType, config = {}) {
+        const startTimeout = config.startTimeout ?? DEFAULT_START_TIMEOUT;
+        this.logger.info({ agentType, startTimeout }, 'Starting agent session');
+        // Snapshot existing agent session IDs before spawning
+        const existingIds = new Set(this.listAgentsFn().map((a) => a.sessionId));
+        // Spawn Claude Code with --channel flag
+        const command = config.command ?? 'claude';
+        const args = ['--channel'];
+        if (config.model) {
+            args.push('--model', config.model);
+        }
+        const env = { ...process.env };
+        delete env.CLAUDECODE;
+        const child = this.spawnFn(command, args, {
+            cwd: config.cwd,
+            env,
+            stdio: 'pipe',
+        });
+        const pid = child.pid;
+        this.logger.info({ agentType, pid }, 'Spawned Claude Code process');
+        // Register exit listener for unexpected process death
+        child.on('exit', (code, signal) => {
+            for (const [sessionId, handle] of this.sessions.entries()) {
+                if (handle.pid === pid) {
+                    this.logger.warn({ agentType, code, pid, sessionId, signal }, 'Agent process exited unexpectedly');
+                    this.sessions.delete(sessionId);
+                    break;
+                }
+            }
+        });
+        // Poll for new discovery registration
+        const startTime = Date.now();
+        return new Promise((resolve, reject) => {
+            const poll = () => {
+                if (Date.now() - startTime > startTimeout) {
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch {
+                        // Process may already be dead
+                    }
+                    reject(new SessionStartTimeoutError(agentType, startTimeout));
+                    return;
+                }
+                try {
+                    const agents = this.listAgentsFn();
+                    const newAgent = agents.find((a) => !existingIds.has(a.sessionId));
+                    if (newAgent) {
+                        const handle = {
+                            agentType,
+                            pid,
+                            port: newAgent.port ?? 0,
+                            process: child,
+                            sessionId: newAgent.sessionId,
+                        };
+                        this.sessions.set(newAgent.sessionId, handle);
+                        this.logger.info({ agentType, pid, port: newAgent.port, sessionId: newAgent.sessionId }, 'Agent session registered via discovery');
+                        resolve(handle);
+                        return;
+                    }
+                }
+                catch (error) {
+                    this.logger.debug({ error: error.message }, 'Discovery poll error (retrying)');
+                }
+                setTimeout(poll, POLL_INTERVAL);
+            };
+            poll();
+        });
+    }
+    /**
+     * Send a ping envelope to the agent and check for pong response.
+     *
+     * @param handle - Session handle to health-check
+     * @param config - Optional config for health timeout override
+     * @returns true if agent responds with pong, false otherwise
+     */
+    async checkHealth(handle, config = {}) {
+        const healthTimeout = config.healthTimeout ?? DEFAULT_HEALTH_TIMEOUT;
+        const envelope = {
+            from: 'bmad-session-manager',
+            id: randomUUID(),
+            payload: {},
+            timestamp: new Date().toISOString(),
+            to: handle.sessionId,
+            type: 'ping',
+        };
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), healthTimeout);
+            const response = await fetch(`http://localhost:${handle.port}/webhook`, {
+                body: JSON.stringify(envelope),
+                headers: { 'Content-Type': 'application/json' },
+                method: 'POST',
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.status !== 200) {
+                this.logger.debug({ sessionId: handle.sessionId, status: response.status }, 'Health check: non-200 status');
+                return false;
+            }
+            const body = (await response.json());
+            return body.type === 'pong';
+        }
+        catch {
+            this.logger.debug({ sessionId: handle.sessionId }, 'Health check failed (timeout or connection error)');
+            return false;
+        }
+    }
+    /**
+     * Stop a single agent session: SIGTERM + deregister + remove from map.
+     *
+     * @param handle - Session handle to stop
+     */
+    async stopSession(handle) {
+        try {
+            this.logger.info({ pid: handle.pid, sessionId: handle.sessionId }, 'Stopping agent session');
+            try {
+                process.kill(handle.pid, 'SIGTERM');
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message, pid: handle.pid }, 'Failed to send SIGTERM (process may already be dead)');
+            }
+            try {
+                this.deregisterAgentFn(handle.sessionId);
+            }
+            catch (error) {
+                this.logger.warn({ error: error.message, sessionId: handle.sessionId }, 'Failed to deregister agent (file may already be removed)');
+            }
+            this.sessions.delete(handle.sessionId);
+        }
+        catch (error) {
+            this.logger.error({ error: error.message, sessionId: handle.sessionId }, 'Error stopping session');
+        }
+    }
+    /**
+     * Stop all managed sessions. Best-effort: errors per session are logged, never thrown.
+     */
+    async stopAll() {
+        const handles = Array.from(this.sessions.values());
+        this.logger.info({ sessionCount: handles.length }, 'Stopping all agent sessions');
+        const results = await Promise.allSettled(handles.map((h) => this.stopSession(h)));
+        for (const result of results) {
+            if (result.status === 'rejected') {
+                this.logger.error({ error: result.reason.message }, 'Error during stopAll session cleanup');
+            }
+        }
+        this.sessions.clear();
+    }
+    /**
+     * Shutdown method for orchestrator integration.
+     * Call this in the orchestrator's finally block.
+     */
+    async shutdown() {
+        await this.stopAll();
+    }
+    /**
+     * Get the number of currently managed sessions.
+     */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Get a session handle by sessionId.
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Register SIGINT handler for graceful cleanup.
+     * Uses a static flag to prevent duplicate registration.
+     */
+    registerSigintHandler() {
+        if (ChannelSessionManager.sigintRegistered)
+            return;
+        ChannelSessionManager.sigintRegistered = true;
+        process.on('SIGINT', async () => {
+            this.logger.info('Received SIGINT — cleaning up channel sessions');
+            await this.stopAll();
+            process.exit(130);
+        });
+    }
+    /**
+     * Reset the static SIGINT registration flag.
+     * Only for testing — do not use in production.
+     * @internal
+     */
+    static resetSigintFlag() {
+        ChannelSessionManager.sigintRegistered = false;
+    }
+}

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

@@ -3,6 +3,8 @@
  *
  * 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 type pino from 'pino';
 import type { AgentOptions, AgentResult } from '../../models/index.js';
@@ -13,69 +15,26 @@ import type { AIProviderRunner } from './agent-runner.js';
  *
  * 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 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
+     * Spawn Claude process and stream output in real-time
      */
-    private buildErrorContext;
+    private spawnAndStream;
     /**
      * Invoke onResponse callback and return result
      * @private
      */
     private returnWithCallback;
+    /**
+     * Shell-escape a single argument
+     */
+    private shellEscape;
 }