@renseiai/agentfactory 0.8.7 → 0.8.9

package/dist/src/workflow/gates/webhook-gate.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Webhook Gate Executor
+ *
+ * Pure logic for webhook gate evaluation, token generation, and callback URL
+ * management. Webhook gates pause workflow execution until an external HTTP
+ * callback is received, enabling integration with external approval systems,
+ * CI/CD pipelines, and other services.
+ *
+ * This module handles the evaluation and state management logic only.
+ * The actual HTTP endpoint registration happens in the server layer (SUP-1299).
+ */
+import type { GateState } from '../gate-state.js';
+import type { GateDefinition, WorkflowDefinition } from '../workflow-types.js';
+/**
+ * Trigger configuration for a webhook gate.
+ * Defines the base endpoint path for webhook callbacks.
+ */
+export interface WebhookGateTrigger {
+    /** Base path for webhook callbacks (e.g., "/api/gates") */
+    endpoint: string;
+}
+/**
+ * Result of evaluating a webhook gate's current status.
+ */
+export interface WebhookGateResult {
+    /** Whether the gate condition has been satisfied */
+    satisfied: boolean;
+    /** The callback URL for an active webhook gate */
+    callbackUrl?: string;
+    /** Whether the gate has timed out */
+    timedOut?: boolean;
+}
+/**
+ * Activation data for a webhook gate, including the authentication token,
+ * callback URL, and optional expiration timestamp.
+ */
+export interface WebhookGateActivation {
+    /** Cryptographically random token for webhook authentication */
+    token: string;
+    /** Full callback URL including token query parameter */
+    callbackUrl: string;
+    /** When the gate activation expires, epoch ms */
+    expiresAt?: number;
+}
+/**
+ * Generate a cryptographically random token for webhook authentication.
+ *
+ * Uses Node.js `crypto.randomBytes()` to generate a 32-byte hex token.
+ * This token is stored in gate state and verified on callback receipt
+ * to ensure only authorized callers can satisfy the gate.
+ *
+ * @returns A 64-character hex string token
+ */
+export declare function generateWebhookToken(): string;
+/**
+ * Build the callback URL for an activated webhook gate.
+ *
+ * The URL follows the format:
+ *   `{baseUrl}/api/gates/{issueId}/{gateName}?token={token}`
+ *
+ * @param baseUrl - The base URL of the server (e.g., "https://api.example.com")
+ * @param issueId - The issue identifier this gate is associated with
+ * @param gateName - The unique gate name from the gate definition
+ * @param token - The authentication token for this gate activation
+ * @returns The fully-qualified callback URL
+ */
+export declare function buildCallbackUrl(baseUrl: string, issueId: string, gateName: string, token: string): string;
+/**
+ * Validate that a webhook callback's token matches the expected token.
+ *
+ * Uses timing-safe comparison via `crypto.timingSafeEqual` to prevent
+ * timing attacks that could leak token information through response times.
+ *
+ * @param token - The token received in the webhook callback
+ * @param expectedToken - The expected token stored in gate state
+ * @returns `true` if the tokens match, `false` otherwise
+ */
+export declare function validateWebhookCallback(token: string, expectedToken: string): boolean;
+/**
+ * Pure function to evaluate a webhook gate's current status based on its
+ * definition and persisted state.
+ *
+ * Evaluation logic:
+ * - If gate state is `satisfied` -> return `{ satisfied: true }`
+ * - If gate state is `timed-out` -> return `{ satisfied: false, timedOut: true }`
+ * - If gate state is `active` and has a timeout deadline that has passed ->
+ *   return `{ satisfied: false, timedOut: true }`
+ * - If gate state is `active` -> return `{ satisfied: false, callbackUrl }`
+ *   where callbackUrl is reconstructed from state's signalSource if available
+ * - If gate state is `null` (not yet activated) -> return `{ satisfied: false }`
+ *
+ * @param gate - The gate definition from the workflow
+ * @param gateState - The persisted gate state, or null if the gate has not been activated
+ * @returns The evaluated webhook gate result
+ */
+export declare function evaluateWebhookGate(gate: GateDefinition, gateState: GateState | null): WebhookGateResult;
+/**
+ * Type guard to check if a gate trigger configuration is a webhook trigger.
+ *
+ * A valid webhook trigger must have an `endpoint` property of type string.
+ *
+ * @param trigger - The trigger configuration to check
+ * @returns `true` if the trigger is a WebhookGateTrigger
+ */
+export declare function isWebhookGateTrigger(trigger: Record<string, unknown>): trigger is Record<string, unknown> & WebhookGateTrigger;
+/**
+ * Get all webhook gates that apply to a given workflow phase.
+ *
+ * Filters the workflow's gate definitions to return only those that:
+ * 1. Have type `webhook`
+ * 2. Either have no `appliesTo` restriction, or include the specified phase
+ *
+ * @param workflow - The workflow definition containing gate configurations
+ * @param phase - The phase name to filter gates for
+ * @returns Array of gate definitions that are webhook type and apply to the phase
+ */
+export declare function getApplicableWebhookGates(workflow: WorkflowDefinition, phase: string): GateDefinition[];
+/**
+ * Creates the activation data for a webhook gate including a cryptographically
+ * random token, callback URL, and optional expiration timestamp.
+ *
+ * This function generates all the data needed to activate a webhook gate,
+ * but does not persist any state. The caller is responsible for storing the
+ * activation data (token in gate state, URL communicated to external system).
+ *
+ * @param issueId - The issue identifier this gate is associated with
+ * @param gateDef - The gate definition from the workflow
+ * @param baseUrl - The base URL of the server for building callback URLs
+ * @returns The webhook gate activation data
+ */
+export declare function createWebhookGateActivation(issueId: string, gateDef: GateDefinition, baseUrl: string): WebhookGateActivation;
+//# sourceMappingURL=webhook-gate.d.ts.map

package/dist/src/workflow/gates/webhook-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-gate.d.ts","sourceRoot":"","sources":["../../../../src/workflow/gates/webhook-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAa9E;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAA;IAClB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR;AAMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAeT;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,SAAS,GAAG,IAAI,GAC1B,iBAAiB,CAoCnB;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,CAOzD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,GACZ,cAAc,EAAE,CAiBlB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,GACd,qBAAqB,CAuBvB"}

package/dist/src/workflow/gates/webhook-gate.js

@@ -0,0 +1,216 @@
+/**
+ * Webhook Gate Executor
+ *
+ * Pure logic for webhook gate evaluation, token generation, and callback URL
+ * management. Webhook gates pause workflow execution until an external HTTP
+ * callback is received, enabling integration with external approval systems,
+ * CI/CD pipelines, and other services.
+ *
+ * This module handles the evaluation and state management logic only.
+ * The actual HTTP endpoint registration happens in the server layer (SUP-1299).
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { parseDuration } from '../gate-state.js';
+const log = {
+    info: (msg, data) => console.log(`[webhook-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[webhook-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[webhook-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// ============================================
+// Token Generation
+// ============================================
+/**
+ * Generate a cryptographically random token for webhook authentication.
+ *
+ * Uses Node.js `crypto.randomBytes()` to generate a 32-byte hex token.
+ * This token is stored in gate state and verified on callback receipt
+ * to ensure only authorized callers can satisfy the gate.
+ *
+ * @returns A 64-character hex string token
+ */
+export function generateWebhookToken() {
+    return randomBytes(32).toString('hex');
+}
+// ============================================
+// Callback URL
+// ============================================
+/**
+ * Build the callback URL for an activated webhook gate.
+ *
+ * The URL follows the format:
+ *   `{baseUrl}/api/gates/{issueId}/{gateName}?token={token}`
+ *
+ * @param baseUrl - The base URL of the server (e.g., "https://api.example.com")
+ * @param issueId - The issue identifier this gate is associated with
+ * @param gateName - The unique gate name from the gate definition
+ * @param token - The authentication token for this gate activation
+ * @returns The fully-qualified callback URL
+ */
+export function buildCallbackUrl(baseUrl, issueId, gateName, token) {
+    const normalizedBase = baseUrl.replace(/\/+$/, '');
+    const encodedIssueId = encodeURIComponent(issueId);
+    const encodedGateName = encodeURIComponent(gateName);
+    const encodedToken = encodeURIComponent(token);
+    return `${normalizedBase}/api/gates/${encodedIssueId}/${encodedGateName}?token=${encodedToken}`;
+}
+// ============================================
+// Token Validation
+// ============================================
+/**
+ * Validate that a webhook callback's token matches the expected token.
+ *
+ * Uses timing-safe comparison via `crypto.timingSafeEqual` to prevent
+ * timing attacks that could leak token information through response times.
+ *
+ * @param token - The token received in the webhook callback
+ * @param expectedToken - The expected token stored in gate state
+ * @returns `true` if the tokens match, `false` otherwise
+ */
+export function validateWebhookCallback(token, expectedToken) {
+    if (!token || !expectedToken) {
+        log.warn('Token validation failed: empty token provided');
+        return false;
+    }
+    const tokenBuffer = Buffer.from(token, 'utf8');
+    const expectedBuffer = Buffer.from(expectedToken, 'utf8');
+    // timingSafeEqual requires buffers of equal length
+    if (tokenBuffer.length !== expectedBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(tokenBuffer, expectedBuffer);
+}
+// ============================================
+// Gate Evaluation
+// ============================================
+/**
+ * Pure function to evaluate a webhook gate's current status based on its
+ * definition and persisted state.
+ *
+ * Evaluation logic:
+ * - If gate state is `satisfied` -> return `{ satisfied: true }`
+ * - If gate state is `timed-out` -> return `{ satisfied: false, timedOut: true }`
+ * - If gate state is `active` and has a timeout deadline that has passed ->
+ *   return `{ satisfied: false, timedOut: true }`
+ * - If gate state is `active` -> return `{ satisfied: false, callbackUrl }`
+ *   where callbackUrl is reconstructed from state's signalSource if available
+ * - If gate state is `null` (not yet activated) -> return `{ satisfied: false }`
+ *
+ * @param gate - The gate definition from the workflow
+ * @param gateState - The persisted gate state, or null if the gate has not been activated
+ * @returns The evaluated webhook gate result
+ */
+export function evaluateWebhookGate(gate, gateState) {
+    if (!gateState) {
+        log.debug('Webhook gate not yet activated', { gateName: gate.name });
+        return { satisfied: false };
+    }
+    if (gateState.status === 'satisfied') {
+        log.debug('Webhook gate satisfied', { gateName: gate.name });
+        return { satisfied: true };
+    }
+    if (gateState.status === 'timed-out') {
+        log.debug('Webhook gate timed out', { gateName: gate.name });
+        return { satisfied: false, timedOut: true };
+    }
+    if (gateState.status === 'active') {
+        // Check if the gate has exceeded its timeout deadline
+        if (gateState.timeoutDeadline && Date.now() > gateState.timeoutDeadline) {
+            log.info('Webhook gate timeout deadline exceeded', {
+                gateName: gate.name,
+                issueId: gateState.issueId,
+                timeoutDeadline: gateState.timeoutDeadline,
+            });
+            return { satisfied: false, timedOut: true };
+        }
+        // Gate is active and waiting for callback
+        return {
+            satisfied: false,
+            callbackUrl: gateState.signalSource,
+        };
+    }
+    // Pending or unknown status
+    return { satisfied: false };
+}
+// ============================================
+// Type Guards
+// ============================================
+/**
+ * Type guard to check if a gate trigger configuration is a webhook trigger.
+ *
+ * A valid webhook trigger must have an `endpoint` property of type string.
+ *
+ * @param trigger - The trigger configuration to check
+ * @returns `true` if the trigger is a WebhookGateTrigger
+ */
+export function isWebhookGateTrigger(trigger) {
+    return (typeof trigger === 'object' &&
+        trigger !== null &&
+        typeof trigger.endpoint === 'string' &&
+        trigger.endpoint.length > 0);
+}
+// ============================================
+// Gate Filtering
+// ============================================
+/**
+ * Get all webhook gates that apply to a given workflow phase.
+ *
+ * Filters the workflow's gate definitions to return only those that:
+ * 1. Have type `webhook`
+ * 2. Either have no `appliesTo` restriction, or include the specified phase
+ *
+ * @param workflow - The workflow definition containing gate configurations
+ * @param phase - The phase name to filter gates for
+ * @returns Array of gate definitions that are webhook type and apply to the phase
+ */
+export function getApplicableWebhookGates(workflow, phase) {
+    if (!workflow.gates || workflow.gates.length === 0) {
+        return [];
+    }
+    return workflow.gates.filter((gate) => {
+        if (gate.type !== 'webhook') {
+            return false;
+        }
+        // If no appliesTo is specified, the gate applies to all phases
+        if (!gate.appliesTo || gate.appliesTo.length === 0) {
+            return true;
+        }
+        return gate.appliesTo.includes(phase);
+    });
+}
+// ============================================
+// Gate Activation
+// ============================================
+/**
+ * Creates the activation data for a webhook gate including a cryptographically
+ * random token, callback URL, and optional expiration timestamp.
+ *
+ * This function generates all the data needed to activate a webhook gate,
+ * but does not persist any state. The caller is responsible for storing the
+ * activation data (token in gate state, URL communicated to external system).
+ *
+ * @param issueId - The issue identifier this gate is associated with
+ * @param gateDef - The gate definition from the workflow
+ * @param baseUrl - The base URL of the server for building callback URLs
+ * @returns The webhook gate activation data
+ */
+export function createWebhookGateActivation(issueId, gateDef, baseUrl) {
+    const token = generateWebhookToken();
+    const callbackUrl = buildCallbackUrl(baseUrl, issueId, gateDef.name, token);
+    const activation = {
+        token,
+        callbackUrl,
+    };
+    // Compute expiration from gate timeout if configured
+    if (gateDef.timeout) {
+        const durationMs = parseDuration(gateDef.timeout.duration);
+        activation.expiresAt = Date.now() + durationMs;
+    }
+    log.info('Webhook gate activation created', {
+        issueId,
+        gateName: gateDef.name,
+        callbackUrl,
+        expiresAt: activation.expiresAt,
+    });
+    return activation;
+}

package/dist/src/workflow/gates/webhook-gate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhook-gate.test.d.ts.map

package/dist/src/workflow/gates/webhook-gate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-gate.test.d.ts","sourceRoot":"","sources":["../../../../src/workflow/gates/webhook-gate.test.ts"],"names":[],"mappings":""}

package/dist/src/workflow/gates/webhook-gate.test.js

@@ -0,0 +1,182 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { generateWebhookToken, buildCallbackUrl, validateWebhookCallback, evaluateWebhookGate, createWebhookGateActivation, } from './webhook-gate.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeGateDefinition(overrides = {}) {
+    return {
+        name: 'test-webhook',
+        type: 'webhook',
+        trigger: { endpoint: '/api/gates' },
+        ...overrides,
+    };
+}
+function makeGateState(overrides = {}) {
+    return {
+        issueId: 'issue-1',
+        gateName: 'test-webhook',
+        gateType: 'webhook',
+        status: 'active',
+        activatedAt: Date.now(),
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// generateWebhookToken
+// ---------------------------------------------------------------------------
+describe('generateWebhookToken', () => {
+    it('returns a 64-character hex string', () => {
+        const token = generateWebhookToken();
+        expect(token).toHaveLength(64);
+        expect(token).toMatch(/^[a-f0-9]{64}$/);
+    });
+    it('generates unique tokens', () => {
+        const token1 = generateWebhookToken();
+        const token2 = generateWebhookToken();
+        expect(token1).not.toBe(token2);
+    });
+});
+// ---------------------------------------------------------------------------
+// buildCallbackUrl
+// ---------------------------------------------------------------------------
+describe('buildCallbackUrl', () => {
+    it('builds correct URL format', () => {
+        const url = buildCallbackUrl('https://api.example.com', 'issue-1', 'my-gate', 'abc123');
+        expect(url).toBe('https://api.example.com/api/gates/issue-1/my-gate?token=abc123');
+    });
+    it('URI-encodes special characters in issueId', () => {
+        const url = buildCallbackUrl('https://api.example.com', 'issue/1', 'gate', 'token');
+        expect(url).toContain('issue%2F1');
+    });
+    it('URI-encodes special characters in gateName', () => {
+        const url = buildCallbackUrl('https://api.example.com', 'issue-1', 'my gate', 'token');
+        expect(url).toContain('my%20gate');
+    });
+    it('normalizes trailing slashes on base URL', () => {
+        const url = buildCallbackUrl('https://api.example.com/', 'issue-1', 'gate', 'token');
+        expect(url).toBe('https://api.example.com/api/gates/issue-1/gate?token=token');
+    });
+    it('normalizes multiple trailing slashes', () => {
+        const url = buildCallbackUrl('https://api.example.com///', 'issue-1', 'gate', 'token');
+        expect(url).toBe('https://api.example.com/api/gates/issue-1/gate?token=token');
+    });
+});
+// ---------------------------------------------------------------------------
+// validateWebhookCallback
+// ---------------------------------------------------------------------------
+describe('validateWebhookCallback', () => {
+    it('returns true for matching tokens', () => {
+        const token = 'test-webhook-token-value';
+        expect(validateWebhookCallback(token, token)).toBe(true);
+    });
+    it('returns false for mismatched tokens', () => {
+        expect(validateWebhookCallback('token-a', 'token-b')).toBe(false);
+    });
+    it('returns false for empty token', () => {
+        expect(validateWebhookCallback('', 'expected')).toBe(false);
+    });
+    it('returns false for empty expected token', () => {
+        expect(validateWebhookCallback('token', '')).toBe(false);
+    });
+    it('returns false for different length tokens', () => {
+        expect(validateWebhookCallback('short', 'a-much-longer-token')).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// evaluateWebhookGate
+// ---------------------------------------------------------------------------
+describe('evaluateWebhookGate', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2025-06-01T12:00:00Z'));
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('returns not satisfied for null state', () => {
+        const gate = makeGateDefinition();
+        const result = evaluateWebhookGate(gate, null);
+        expect(result.satisfied).toBe(false);
+        expect(result.callbackUrl).toBeUndefined();
+        expect(result.timedOut).toBeUndefined();
+    });
+    it('returns satisfied for satisfied state', () => {
+        const gate = makeGateDefinition();
+        const state = makeGateState({ status: 'satisfied', satisfiedAt: Date.now() });
+        const result = evaluateWebhookGate(gate, state);
+        expect(result.satisfied).toBe(true);
+    });
+    it('returns timedOut for timed-out state', () => {
+        const gate = makeGateDefinition();
+        const state = makeGateState({ status: 'timed-out', timedOutAt: Date.now() });
+        const result = evaluateWebhookGate(gate, state);
+        expect(result.satisfied).toBe(false);
+        expect(result.timedOut).toBe(true);
+    });
+    it('returns callbackUrl for active state', () => {
+        const gate = makeGateDefinition();
+        const state = makeGateState({
+            status: 'active',
+            signalSource: 'https://api.example.com/api/gates/issue-1/test-webhook?token=abc',
+        });
+        const result = evaluateWebhookGate(gate, state);
+        expect(result.satisfied).toBe(false);
+        expect(result.callbackUrl).toBe(state.signalSource);
+    });
+    it('returns timedOut when active gate has expired deadline', () => {
+        const gate = makeGateDefinition();
+        const state = makeGateState({
+            status: 'active',
+            timeoutDeadline: Date.now() - 1000, // deadline in the past
+        });
+        const result = evaluateWebhookGate(gate, state);
+        expect(result.satisfied).toBe(false);
+        expect(result.timedOut).toBe(true);
+    });
+    it('returns not timed out when active gate has future deadline', () => {
+        const gate = makeGateDefinition();
+        const state = makeGateState({
+            status: 'active',
+            timeoutDeadline: Date.now() + 60_000, // deadline in the future
+        });
+        const result = evaluateWebhookGate(gate, state);
+        expect(result.satisfied).toBe(false);
+        expect(result.timedOut).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// createWebhookGateActivation
+// ---------------------------------------------------------------------------
+describe('createWebhookGateActivation', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2025-06-01T12:00:00Z'));
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('generates a token', () => {
+        const gate = makeGateDefinition();
+        const activation = createWebhookGateActivation('issue-1', gate, 'https://api.example.com');
+        expect(activation.token).toHaveLength(64);
+        expect(activation.token).toMatch(/^[a-f0-9]{64}$/);
+    });
+    it('builds a callback URL with the generated token', () => {
+        const gate = makeGateDefinition({ name: 'review-gate' });
+        const activation = createWebhookGateActivation('issue-1', gate, 'https://api.example.com');
+        expect(activation.callbackUrl).toContain('https://api.example.com/api/gates/issue-1/review-gate');
+        expect(activation.callbackUrl).toContain(`token=${activation.token}`);
+    });
+    it('computes expiresAt from timeout duration', () => {
+        const gate = makeGateDefinition({
+            timeout: { duration: '4h', action: 'fail' },
+        });
+        const activation = createWebhookGateActivation('issue-1', gate, 'https://api.example.com');
+        expect(activation.expiresAt).toBe(Date.now() + 14_400_000);
+    });
+    it('does not set expiresAt when no timeout configured', () => {
+        const gate = makeGateDefinition();
+        const activation = createWebhookGateActivation('issue-1', gate, 'https://api.example.com');
+        expect(activation.expiresAt).toBeUndefined();
+    });
+});

package/dist/src/workflow/index.d.ts

@@ -4,11 +4,39 @@
  * Declarative workflow graph definitions using YAML (v1.1 schema extension).
  * Defines phases, transitions, escalation ladder, gates, and parallelism.
  */
-export type { EscalationStrategy, PhaseDefinition, TransitionDefinition, EscalationLadderRung, EscalationConfig, GateDefinition, ParallelismGroupDefinition, WorkflowDefinition, } from './workflow-types.js';
-export { PhaseDefinitionSchema, TransitionDefinitionSchema, EscalationLadderRungSchema, EscalationConfigSchema, GateDefinitionSchema, ParallelismGroupDefinitionSchema, WorkflowDefinitionSchema, validateWorkflowDefinition, } from './workflow-types.js';
+export type { EscalationStrategy, PhaseDefinition, PhaseOutputDeclaration, PhaseInputDeclaration, TransitionDefinition, EscalationLadderRung, EscalationConfig, GateDefinition, ParallelismGroupDefinition, WorkflowDefinition, BranchingDefinition, TemplateRetryConfig, TemplateTimeoutConfig, } from './workflow-types.js';
+export { PhaseDefinitionSchema, PhaseOutputDeclarationSchema, PhaseInputDeclarationSchema, TransitionDefinitionSchema, EscalationLadderRungSchema, EscalationConfigSchema, GateDefinitionSchema, ParallelismGroupDefinitionSchema, WorkflowDefinitionSchema, BranchingDefinitionSchema, TemplateRetryConfigSchema, TemplateTimeoutConfigSchema, validateWorkflowDefinition, } from './workflow-types.js';
 export { loadWorkflowDefinitionFile, getBuiltinWorkflowDir, getBuiltinWorkflowPath, } from './workflow-loader.js';
-export type { WorkflowRegistryConfig } from './workflow-registry.js';
+export type { WorkflowRegistryConfig, WorkflowStoreSource } from './workflow-registry.js';
 export { WorkflowRegistry } from './workflow-registry.js';
 export type { TransitionContext, TransitionResult } from './transition-engine.js';
 export { evaluateTransitions } from './transition-engine.js';
+export type { BranchingResult } from './branching-router.js';
+export { evaluateBranching } from './branching-router.js';
+export { parseDuration, DurationParseError } from './duration.js';
+export type { ResolvedRetryConfig, ResolvedTimeoutConfig } from './retry-resolver.js';
+export { resolveRetryConfig, resolveTimeoutConfig } from './retry-resolver.js';
+export type { EvaluationContext } from './expression/index.js';
+export { buildEvaluationContext, evaluateCondition } from './expression/index.js';
+export type { GateState, GateStorage } from './gate-state.js';
+export { InMemoryGateStorage, initGateStorage, activateGate, satisfyGate, timeoutGate, } from './gate-state.js';
+export { parseDuration as parseGateDuration } from './gate-state.js';
+export type { SignalGateTrigger, SignalGateResult } from './gates/signal-gate.js';
+export { isSignalGateTrigger, evaluateSignalGate, getApplicableSignalGates, createImplicitHoldGate, createImplicitResumeGate, IMPLICIT_HOLD_GATE_NAME, IMPLICIT_RESUME_GATE_NAME, } from './gates/signal-gate.js';
+export type { WebhookGateTrigger, WebhookGateResult, WebhookGateActivation } from './gates/webhook-gate.js';
+export { generateWebhookToken, buildCallbackUrl, validateWebhookCallback, evaluateWebhookGate, isWebhookGateTrigger, getApplicableWebhookGates, createWebhookGateActivation, } from './gates/webhook-gate.js';
+export type { TimeoutCheckResult, TimedOutGate, TimeoutResolution } from './gates/timeout-engine.js';
+export { checkGateTimeout, checkAllGateTimeouts, resolveTimeoutAction, processGateTimeouts, } from './gates/timeout-engine.js';
+export type { TimerGateTrigger, TimerGateResult } from './gates/timer-gate.js';
+export { evaluateTimerGate, computeNextCronFireTime, isTimerGateTrigger, getApplicableTimerGates, parseCronField, parseCronExpression, } from './gates/timer-gate.js';
+export type { GateEvaluationOptions, GateEvaluationResult } from './gates/gate-evaluator.js';
+export { evaluateGatesForPhase, activateGatesForPhase, clearGatesForIssue, getApplicableGates, } from './gates/gate-evaluator.js';
+export { PhaseOutputCollector } from './phase-output-collector.js';
+export { PhaseContextInjector } from './phase-context-injector.js';
+export type { ParallelTask, ParallelTaskResult, ParallelTaskError, ParallelismResult, ParallelismStrategy, ParallelismStrategyOptions, } from './parallelism-types.js';
+export { ConcurrencySemaphore } from './concurrency-semaphore.js';
+export { ParallelismExecutor } from './parallelism-executor.js';
+export type { AgentCancellation } from './agent-cancellation.js';
+export { InMemoryAgentCancellation } from './agent-cancellation.js';
+export { FanOutStrategy, FanInStrategy, RaceStrategy } from './strategies/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/workflow/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,gCAAgC,EAChC,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflow/index.ts"],"names":[],"mappings":"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"}

package/dist/src/workflow/index.js

@@ -4,7 +4,26 @@
  * Declarative workflow graph definitions using YAML (v1.1 schema extension).
  * Defines phases, transitions, escalation ladder, gates, and parallelism.
  */
-export { PhaseDefinitionSchema, TransitionDefinitionSchema, EscalationLadderRungSchema, EscalationConfigSchema, GateDefinitionSchema, ParallelismGroupDefinitionSchema, WorkflowDefinitionSchema, validateWorkflowDefinition, } from './workflow-types.js';
+export { PhaseDefinitionSchema, PhaseOutputDeclarationSchema, PhaseInputDeclarationSchema, TransitionDefinitionSchema, EscalationLadderRungSchema, EscalationConfigSchema, GateDefinitionSchema, ParallelismGroupDefinitionSchema, WorkflowDefinitionSchema, BranchingDefinitionSchema, TemplateRetryConfigSchema, TemplateTimeoutConfigSchema, validateWorkflowDefinition, } from './workflow-types.js';
 export { loadWorkflowDefinitionFile, getBuiltinWorkflowDir, getBuiltinWorkflowPath, } from './workflow-loader.js';
 export { WorkflowRegistry } from './workflow-registry.js';
 export { evaluateTransitions } from './transition-engine.js';
+export { evaluateBranching } from './branching-router.js';
+// Duration parser
+export { parseDuration, DurationParseError } from './duration.js';
+export { resolveRetryConfig, resolveTimeoutConfig } from './retry-resolver.js';
+export { buildEvaluationContext, evaluateCondition } from './expression/index.js';
+export { InMemoryGateStorage, initGateStorage, activateGate, satisfyGate, timeoutGate, } from './gate-state.js';
+export { parseDuration as parseGateDuration } from './gate-state.js';
+export { isSignalGateTrigger, evaluateSignalGate, getApplicableSignalGates, createImplicitHoldGate, createImplicitResumeGate, IMPLICIT_HOLD_GATE_NAME, IMPLICIT_RESUME_GATE_NAME, } from './gates/signal-gate.js';
+export { generateWebhookToken, buildCallbackUrl, validateWebhookCallback, evaluateWebhookGate, isWebhookGateTrigger, getApplicableWebhookGates, createWebhookGateActivation, } from './gates/webhook-gate.js';
+export { checkGateTimeout, checkAllGateTimeouts, resolveTimeoutAction, processGateTimeouts, } from './gates/timeout-engine.js';
+export { evaluateTimerGate, computeNextCronFireTime, isTimerGateTrigger, getApplicableTimerGates, parseCronField, parseCronExpression, } from './gates/timer-gate.js';
+export { evaluateGatesForPhase, activateGatesForPhase, clearGatesForIssue, getApplicableGates, } from './gates/gate-evaluator.js';
+// Phase output/input handling
+export { PhaseOutputCollector } from './phase-output-collector.js';
+export { PhaseContextInjector } from './phase-context-injector.js';
+export { ConcurrencySemaphore } from './concurrency-semaphore.js';
+export { ParallelismExecutor } from './parallelism-executor.js';
+export { InMemoryAgentCancellation } from './agent-cancellation.js';
+export { FanOutStrategy, FanInStrategy, RaceStrategy } from './strategies/index.js';

package/dist/src/workflow/parallelism-executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ParallelismExecutor
+ *
+ * Orchestrates parallel task execution using strategy pattern.
+ * Each parallelism group in the workflow definition is executed
+ * through its configured strategy with concurrency limiting.
+ */
+import type { ParallelismGroupDefinition } from './workflow-types.js';
+import type { ParallelTask, ParallelTaskResult, ParallelismResult, ParallelismStrategy } from './parallelism-types.js';
+export declare class ParallelismExecutor {
+    private readonly strategies;
+    /**
+     * Register a strategy implementation for a strategy name.
+     */
+    registerStrategy(name: string, strategy: ParallelismStrategy): void;
+    /**
+     * Get a registered strategy by name.
+     */
+    getStrategy(name: string): ParallelismStrategy | undefined;
+    /**
+     * Execute a parallelism group with the configured strategy.
+     */
+    execute(group: ParallelismGroupDefinition, tasks: ParallelTask[], dispatch: (task: ParallelTask) => Promise<ParallelTaskResult>): Promise<ParallelismResult>;
+}
+//# sourceMappingURL=parallelism-executor.d.ts.map

package/dist/src/workflow/parallelism-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallelism-executor.d.ts","sourceRoot":"","sources":["../../../src/workflow/parallelism-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,wBAAwB,CAAA;AAG/B,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8C;IAEzE;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAInE;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAI1D;;OAEG;IACG,OAAO,CACX,KAAK,EAAE,0BAA0B,EACjC,KAAK,EAAE,YAAY,EAAE,EACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,kBAAkB,CAAC,GAC5D,OAAO,CAAC,iBAAiB,CAAC;CA8B9B"}