@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.28

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

@@ -2,30 +2,29 @@
  * Agent Runner Factory
  *
  * Creates the appropriate AIProviderRunner based on provider configuration.
+ * Includes both the legacy `createAgentRunner()` function and the new
+ * `AgentRunnerFactory` class with Channel transport discovery.
  */
 import type pino from 'pino';
+import type { WorkflowCallbacks } from '../../models/workflow-callbacks.js';
+import type { WorkflowConfig } from '../../models/workflow-config.js';
 import type { AIProvider } from '../../models/provider.js';
 import type { AIProviderRunner } from './agent-runner.js';
 /**
  * Create an AI provider runner for the specified provider
- *
- * @param provider - The AI provider to create a runner for
- * @param logger - Logger instance for structured logging
- * @returns An AIProviderRunner instance for the specified provider
- * @throws Error if the provider is not supported
- *
- * @example
- * ```typescript
- * const logger = createLogger({ namespace: 'agent-runner' })
- * const runner = createAgentRunner('claude', logger)
- * const result = await runner.runAgent('Hello', { agentType: 'dev' })
- * ```
  */
 export declare function createAgentRunner(provider: AIProvider, logger: pino.Logger): AIProviderRunner;
 /**
  * Check if a provider is supported
- *
- * @param provider - The provider to check
- * @returns true if the provider is supported
  */
 export declare function isProviderSupported(provider: string): provider is AIProvider;
+/**
+ * AgentRunnerFactory — discovery-based runner selection
+ */
+export declare class AgentRunnerFactory {
+    private readonly callbacks?;
+    private readonly logger;
+    constructor(logger: pino.Logger, callbacks?: WorkflowCallbacks);
+    create(agentType: string, config: WorkflowConfig, phaseName?: string): AIProviderRunner;
+    private fireChannelFallback;
+}

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

@@ -2,24 +2,16 @@
  * Agent Runner Factory
  *
  * Creates the appropriate AIProviderRunner based on provider configuration.
+ * Includes both the legacy `createAgentRunner()` function and the new
+ * `AgentRunnerFactory` class with Channel transport discovery.
  */
+import { listAgents } from '@hyperdrive.bot/claude-channels/dist/services/discovery.js';
+import { ChannelAgentRunner } from './channel-agent-runner.js';
 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
- *
- * @param provider - The AI provider to create a runner for
- * @param logger - Logger instance for structured logging
- * @returns An AIProviderRunner instance for the specified provider
- * @throws Error if the provider is not supported
- *
- * @example
- * ```typescript
- * const logger = createLogger({ namespace: 'agent-runner' })
- * const runner = createAgentRunner('claude', logger)
- * const result = await runner.runAgent('Hello', { agentType: 'dev' })
- * ```
  */
 export function createAgentRunner(provider, logger) {
     switch (provider) {
@@ -39,10 +31,59 @@ export function createAgentRunner(provider, logger) {
 }
 /**
  * Check if a provider is supported
- *
- * @param provider - The provider to check
- * @returns true if the provider is supported
  */
 export function isProviderSupported(provider) {
     return provider === 'claude' || provider === 'gemini' || provider === 'opencode';
 }
+/**
+ * AgentRunnerFactory — discovery-based runner selection
+ */
+export class AgentRunnerFactory {
+    callbacks;
+    logger;
+    constructor(logger, callbacks) {
+        this.logger = logger;
+        this.callbacks = callbacks;
+    }
+    create(agentType, config, phaseName) {
+        if (!config.useChannels) {
+            return createAgentRunner(config.provider ?? 'claude', this.logger);
+        }
+        let agents;
+        try {
+            agents = listAgents();
+        }
+        catch (error) {
+            this.logger.warn(`[channel] Discovery failed: ${error.message} — falling back to subprocess`);
+            this.fireChannelFallback(agentType, 'not_discovered', phaseName);
+            return createAgentRunner(config.provider ?? 'claude', this.logger);
+        }
+        const matches = agents.filter((reg) => reg.name.toLowerCase() === agentType.toLowerCase());
+        if (matches.length === 0) {
+            this.logger.info(`[subprocess] Falling back to claude -p for ${agentType} — no Channel agent discovered`);
+            this.fireChannelFallback(agentType, 'not_discovered', phaseName);
+            return createAgentRunner(config.provider ?? 'claude', this.logger);
+        }
+        const matched = matches.length === 1
+            ? matches[0]
+            : matches.sort((a, b) => b.startedAt.localeCompare(a.startedAt))[0];
+        this.logger.info({ agentType, sessionId: matched.sessionId, webhookUrl: matched.webhookUrl }, `[channel] Discovered Channel agent for ${agentType}`);
+        return new ChannelAgentRunner(this.logger, matched.webhookUrl, matched.sessionId, this.callbacks);
+    }
+    fireChannelFallback(agentType, reason, phaseName) {
+        const callback = this.callbacks?.onChannelFallback;
+        if (!callback)
+            return;
+        const context = {
+            agentType,
+            phaseName: phaseName ?? 'unknown',
+            reason,
+        };
+        try {
+            callback(context);
+        }
+        catch (error) {
+            this.logger.warn({ callbackName: 'onChannelFallback', error: error.message }, 'Callback error (ignored to prevent workflow interruption)');
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * ChannelAgentRunner Service
+ *
+ * Sends task envelopes to discovered Channel agent endpoints via HTTP POST
+ * and returns results as AgentResult. Used by the factory to delegate work
+ * to persistent, context-preserving Claude Code sessions.
+ */
+import type pino from 'pino';
+import type { AgentOptions, AgentResult, WorkflowCallbacks } from '../../models/index.js';
+import type { AIProvider } from '../../models/provider.js';
+import type { AIProviderRunner } from './agent-runner.js';
+/**
+ * Error thrown when the channel agent endpoint is unreachable (ECONNREFUSED).
+ * The factory uses this signal to trigger subprocess fallback.
+ */
+export declare class ChannelUnavailableError extends Error {
+    readonly name = "ChannelUnavailableError";
+    readonly webhookUrl: string;
+    constructor(webhookUrl: string, cause?: Error);
+}
+/**
+ * ChannelAgentRunner — sends task envelopes to channel agent endpoints via HTTP POST.
+ *
+ * Never throws on agent errors (returns AgentResult with success: false).
+ * The ONLY exception is ECONNREFUSED → ChannelUnavailableError, because
+ * the factory needs this signal to trigger subprocess fallback.
+ */
+export declare class ChannelAgentRunner implements AIProviderRunner {
+    readonly provider: AIProvider;
+    private activeRequests;
+    private connected;
+    private readonly callbacks?;
+    private readonly logger;
+    private readonly port;
+    private readonly sessionId;
+    private readonly webhookUrl;
+    constructor(logger: pino.Logger, webhookUrl: string, sessionId: string, callbacks?: WorkflowCallbacks);
+    getActiveProcessCount(): number;
+    private fireChannelConnect;
+    /**
+     * Send a task to the Channel agent and return the result.
+     *
+     * **Task envelope structure:**
+     * The prompt is wrapped in a Channel envelope via `EnvelopeFactory.createTask()`:
+     * - `from`: `"bmad-orchestrator"` — identifies the caller
+     * - `to`: the target session ID discovered during factory creation
+     * - `type`: `"task"` — tells the Channel agent this is a work request
+     * - `payload`: `{ prompt, context? }` — the actual prompt plus optional metadata
+     *   (systemPrompt, model) passed via the context field
+     * - `id` / `timestamp`: auto-generated for tracing and deduplication
+     *
+     * **Response parsing:**
+     * - `type: "result"` with `payload.output` (string) and `payload.exitCode` (number)
+     *   → success path. `exitCode === 0` means the agent completed successfully.
+     * - `type: "error"` → the Channel agent encountered an internal error. Returned as
+     *   `AgentResult` with `success: false` (never throws).
+     * - Any other `type` → treated as unexpected and returned as failure.
+     *
+     * **Timeout handling:**
+     * An `AbortController` is created per request with the configured timeout (default
+     * 300s). If the Channel agent doesn't respond within the timeout window, the fetch
+     * is aborted and an `AgentResult` with `success: false` is returned. The timer is
+     * always cleared in `finally` to prevent leaks.
+     *
+     * **Connection errors:**
+     * ECONNREFUSED is the only error that throws (`ChannelUnavailableError`) instead of
+     * returning a failed `AgentResult`. This allows the factory to catch it and trigger
+     * subprocess fallback.
+     *
+     * @param prompt - The task prompt to send to the Channel agent
+     * @param options - Agent options (agentType, timeout, model, systemPrompt, phaseName)
+     * @returns AgentResult with output, exitCode, duration, and transport: "channel"
+     * @throws ChannelUnavailableError when the endpoint is unreachable (ECONNREFUSED)
+     */
+    runAgent(prompt: string, options: Omit<AgentOptions, 'prompt'>): Promise<AgentResult>;
+}

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

@@ -0,0 +1,246 @@
+/**
+ * ChannelAgentRunner Service
+ *
+ * Sends task envelopes to discovered Channel agent endpoints via HTTP POST
+ * and returns results as AgentResult. Used by the factory to delegate work
+ * to persistent, context-preserving Claude Code sessions.
+ */
+import { EnvelopeFactory } from '@hyperdrive.bot/claude-channels/dist/envelope/factory.js';
+/**
+ * Error thrown when the channel agent endpoint is unreachable (ECONNREFUSED).
+ * The factory uses this signal to trigger subprocess fallback.
+ */
+export class ChannelUnavailableError extends Error {
+    name = 'ChannelUnavailableError';
+    webhookUrl;
+    constructor(webhookUrl, cause) {
+        super(`Channel unavailable at ${webhookUrl}`);
+        this.webhookUrl = webhookUrl;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * ChannelAgentRunner — sends task envelopes to channel agent endpoints via HTTP POST.
+ *
+ * Never throws on agent errors (returns AgentResult with success: false).
+ * The ONLY exception is ECONNREFUSED → ChannelUnavailableError, because
+ * the factory needs this signal to trigger subprocess fallback.
+ */
+export class ChannelAgentRunner {
+    provider = 'claude';
+    activeRequests = 0;
+    connected = false;
+    callbacks;
+    logger;
+    port;
+    sessionId;
+    webhookUrl;
+    constructor(logger, webhookUrl, sessionId, callbacks) {
+        this.logger = logger;
+        this.webhookUrl = webhookUrl;
+        this.sessionId = sessionId;
+        this.callbacks = callbacks;
+        // Extract port from webhook URL
+        try {
+            this.port = new URL(webhookUrl).port ? Number.parseInt(new URL(webhookUrl).port, 10) : 0;
+        }
+        catch {
+            this.port = 0;
+        }
+    }
+    getActiveProcessCount() {
+        return this.activeRequests;
+    }
+    fireChannelConnect(agentType, phaseName) {
+        if (this.connected)
+            return;
+        this.connected = true;
+        const callback = this.callbacks?.onChannelConnect;
+        if (!callback)
+            return;
+        const context = {
+            agentType,
+            phaseName,
+            port: this.port,
+            sessionId: this.sessionId,
+        };
+        try {
+            callback(context);
+        }
+        catch (error) {
+            this.logger.warn({ callbackName: 'onChannelConnect', error: error.message }, 'Callback error (ignored to prevent workflow interruption)');
+        }
+    }
+    /**
+     * Send a task to the Channel agent and return the result.
+     *
+     * **Task envelope structure:**
+     * The prompt is wrapped in a Channel envelope via `EnvelopeFactory.createTask()`:
+     * - `from`: `"bmad-orchestrator"` — identifies the caller
+     * - `to`: the target session ID discovered during factory creation
+     * - `type`: `"task"` — tells the Channel agent this is a work request
+     * - `payload`: `{ prompt, context? }` — the actual prompt plus optional metadata
+     *   (systemPrompt, model) passed via the context field
+     * - `id` / `timestamp`: auto-generated for tracing and deduplication
+     *
+     * **Response parsing:**
+     * - `type: "result"` with `payload.output` (string) and `payload.exitCode` (number)
+     *   → success path. `exitCode === 0` means the agent completed successfully.
+     * - `type: "error"` → the Channel agent encountered an internal error. Returned as
+     *   `AgentResult` with `success: false` (never throws).
+     * - Any other `type` → treated as unexpected and returned as failure.
+     *
+     * **Timeout handling:**
+     * An `AbortController` is created per request with the configured timeout (default
+     * 300s). If the Channel agent doesn't respond within the timeout window, the fetch
+     * is aborted and an `AgentResult` with `success: false` is returned. The timer is
+     * always cleared in `finally` to prevent leaks.
+     *
+     * **Connection errors:**
+     * ECONNREFUSED is the only error that throws (`ChannelUnavailableError`) instead of
+     * returning a failed `AgentResult`. This allows the factory to catch it and trigger
+     * subprocess fallback.
+     *
+     * @param prompt - The task prompt to send to the Channel agent
+     * @param options - Agent options (agentType, timeout, model, systemPrompt, phaseName)
+     * @returns AgentResult with output, exitCode, duration, and transport: "channel"
+     * @throws ChannelUnavailableError when the endpoint is unreachable (ECONNREFUSED)
+     */
+    async runAgent(prompt, options) {
+        const startTime = Date.now();
+        const timeout = options.timeout ?? 300_000;
+        // Build task envelope
+        const context = {};
+        if (options.systemPrompt)
+            context.systemPrompt = options.systemPrompt;
+        if (options.model)
+            context.model = options.model;
+        const envelope = EnvelopeFactory.createTask('bmad-orchestrator', this.sessionId, prompt, Object.keys(context).length > 0 ? context : undefined);
+        this.logger.debug({ agentType: options.agentType, envelopeId: envelope.id, sessionId: this.sessionId }, 'Sending task envelope to channel agent');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        this.activeRequests++;
+        try {
+            const response = await fetch(this.webhookUrl, {
+                body: JSON.stringify(envelope),
+                headers: { 'Content-Type': 'application/json' },
+                method: 'POST',
+                signal: controller.signal,
+            });
+            // Parse response JSON
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                this.logger.warn({ envelopeId: envelope.id, status: response.status }, 'Malformed channel response: invalid JSON');
+                return {
+                    agentType: options.agentType,
+                    duration: Date.now() - startTime,
+                    errors: 'Malformed channel response: invalid JSON',
+                    exitCode: 1,
+                    output: '',
+                    success: false,
+                    transport: 'channel',
+                };
+            }
+            // Validate envelope structure
+            const parsed = body;
+            if (!parsed.type || !parsed.payload) {
+                this.logger.warn({ envelopeId: envelope.id, responseType: parsed.type }, 'Malformed channel response: missing type or payload');
+                return {
+                    agentType: options.agentType,
+                    duration: Date.now() - startTime,
+                    errors: `Malformed channel response: missing ${!parsed.type ? 'type' : 'payload'} field`,
+                    exitCode: 1,
+                    output: '',
+                    success: false,
+                    transport: 'channel',
+                };
+            }
+            // Handle result envelope
+            if (parsed.type === 'result') {
+                const payload = parsed.payload;
+                if (typeof payload.output === 'string' && typeof payload.exitCode === 'number') {
+                    const duration = Date.now() - startTime;
+                    const exitCode = payload.exitCode;
+                    // Fire onChannelConnect on first successful exchange
+                    this.fireChannelConnect(options.agentType, options.phaseName ?? 'unknown');
+                    this.logger.debug({ agentType: options.agentType, duration, envelopeId: envelope.id, exitCode }, 'Channel agent completed');
+                    return {
+                        agentType: options.agentType,
+                        duration,
+                        errors: '',
+                        exitCode,
+                        output: payload.output,
+                        success: exitCode === 0,
+                        transport: 'channel',
+                    };
+                }
+                // Result type but malformed payload
+                this.logger.warn({ envelopeId: envelope.id }, 'Malformed channel response: result payload missing output or exitCode');
+                return {
+                    agentType: options.agentType,
+                    duration: Date.now() - startTime,
+                    errors: 'Malformed channel response: result payload missing output or exitCode',
+                    exitCode: 1,
+                    output: '',
+                    success: false,
+                    transport: 'channel',
+                };
+            }
+            // Non-result envelope type (error, status, etc.)
+            const errorDescription = parsed.type === 'error'
+                ? `Channel returned error: ${JSON.stringify(parsed.payload)}`
+                : `Unexpected envelope type: ${parsed.type}`;
+            this.logger.warn({ envelopeId: envelope.id, responseType: parsed.type }, errorDescription);
+            return {
+                agentType: options.agentType,
+                duration: Date.now() - startTime,
+                errors: errorDescription,
+                exitCode: 1,
+                output: '',
+                success: false,
+                transport: 'channel',
+            };
+        }
+        catch (error) {
+            const err = error;
+            // Connection refused — throw ChannelUnavailableError for factory fallback
+            if (err.cause?.code === 'ECONNREFUSED' || (err instanceof TypeError && err.cause?.code === 'ECONNREFUSED')) {
+                this.logger.error({ webhookUrl: this.webhookUrl }, 'Channel agent unreachable (ECONNREFUSED)');
+                throw new ChannelUnavailableError(this.webhookUrl, err);
+            }
+            // Timeout via AbortController
+            if (err.name === 'AbortError') {
+                this.logger.warn({ envelopeId: envelope.id, timeout }, `Channel timeout after ${timeout}ms`);
+                return {
+                    agentType: options.agentType,
+                    duration: Date.now() - startTime,
+                    errors: `Channel timeout after ${timeout}ms`,
+                    exitCode: 1,
+                    output: '',
+                    success: false,
+                    transport: 'channel',
+                };
+            }
+            // Unexpected error
+            this.logger.error({ envelopeId: envelope.id, error: err.message }, 'Unexpected channel error');
+            return {
+                agentType: options.agentType,
+                duration: Date.now() - startTime,
+                errors: `Unexpected channel error: ${err.message}`,
+                exitCode: 1,
+                output: '',
+                success: false,
+                transport: 'channel',
+            };
+        }
+        finally {
+            this.activeRequests--;
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/services/agents/channel-session-manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 { type ChildProcess, spawn as nodeSpawn } from 'node:child_process';
+import type pino from 'pino';
+import type { AgentRegistration } from '@hyperdrive.bot/claude-channels/dist/types/discovery.js';
+/**
+ * Handle to a managed agent session
+ */
+export interface SessionHandle {
+    sessionId: string;
+    port: number;
+    agentType: string;
+    pid: number;
+    process: ChildProcess;
+}
+/**
+ * Configuration for starting an agent session
+ */
+export interface SessionConfig {
+    command?: string;
+    model?: string;
+    systemPrompt?: string;
+    cwd?: string;
+    startTimeout?: number;
+    healthTimeout?: number;
+}
+/**
+ * Injectable dependencies for testing
+ */
+export interface SessionManagerDeps {
+    listAgents?: () => AgentRegistration[];
+    deregisterAgent?: (sessionId: string) => void;
+    spawn?: typeof nodeSpawn;
+}
+/**
+ * Error thrown when agent session start times out waiting for discovery registration
+ */
+export declare class SessionStartTimeoutError extends Error {
+    readonly agentType: string;
+    readonly timeoutMs: number;
+    constructor(agentType: string, timeoutMs: number);
+}
+/**
+ * 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 declare class ChannelSessionManager {
+    private static sigintRegistered;
+    private readonly sessions;
+    private readonly logger;
+    private readonly listAgentsFn;
+    private readonly deregisterAgentFn;
+    private readonly spawnFn;
+    constructor(logger: pino.Logger, deps?: SessionManagerDeps);
+    /**
+     * 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
+     */
+    startAgentSession(agentType: string, config?: SessionConfig): Promise<SessionHandle>;
+    /**
+     * 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
+     */
+    checkHealth(handle: SessionHandle, config?: SessionConfig): Promise<boolean>;
+    /**
+     * Stop a single agent session: SIGTERM + deregister + remove from map.
+     *
+     * @param handle - Session handle to stop
+     */
+    stopSession(handle: SessionHandle): Promise<void>;
+    /**
+     * Stop all managed sessions. Best-effort: errors per session are logged, never thrown.
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Shutdown method for orchestrator integration.
+     * Call this in the orchestrator's finally block.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the number of currently managed sessions.
+     */
+    get sessionCount(): number;
+    /**
+     * Get a session handle by sessionId.
+     */
+    getSession(sessionId: string): SessionHandle | undefined;
+    /**
+     * Register SIGINT handler for graceful cleanup.
+     * Uses a static flag to prevent duplicate registration.
+     */
+    private registerSigintHandler;
+    /**
+     * Reset the static SIGINT registration flag.
+     * Only for testing — do not use in production.
+     * @internal
+     */
+    static resetSigintFlag(): void;
+}