@xyne/workflow-sdk 1.0.0

package/dist/engine/workflow-executor.js

@@ -0,0 +1,837 @@
+import { CONTROL_FLOW_STEP_TYPES } from '../types/known-types.js';
+import { BaseActionStep, BaseControlFlowStep, StepKind, createPauseFunction, } from '../steps/base-step.js';
+import { VariableResolver, stripNullForOptionalKeys } from './variable-resolver.js';
+import { PauseStep } from './pause-step.js';
+const noopLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+// ─── WorkflowExecutor ───
+/**
+ * Core runtime engine for executing workflows.
+ *
+ * Orchestrates: step execution, variable resolution, pause/resume
+ * (including inside branches), error handling (onError: continue),
+ * retry, timeout, credential resolution, and state persistence.
+ *
+ * Host provides: PersistenceAdapter, StepRegistry, TriggerRegistry,
+ * ServiceRegistry, and an optional logger.
+ */
+export class WorkflowExecutor {
+    persistence;
+    stepRegistry;
+    triggerRegistry;
+    services;
+    resolver;
+    log;
+    eventBus;
+    baseUrl;
+    constructor(persistence, stepRegistry, triggerRegistry, services, options) {
+        this.persistence = persistence;
+        this.stepRegistry = stepRegistry;
+        this.triggerRegistry = triggerRegistry;
+        this.services = services;
+        this.resolver = options?.variableResolver ?? new VariableResolver();
+        this.log = options?.logger ?? noopLogger;
+        this.eventBus = options?.eventBus;
+        this.baseUrl = options?.baseUrl ?? '';
+    }
+    /** Emit an execution stream event (no-op if no eventBus). */
+    emitEvent(executionId, event) {
+        this.eventBus?.emit(executionId, event);
+    }
+    // ─── Public API ───
+    /**
+     * Run or resume an execution by ID.
+     *
+     * Loads the execution from persistence, determines if it's a fresh start
+     * or a resume, then walks through the steps.
+     */
+    async runExecution(executionId) {
+        const exec = await this.persistence.getExecution(executionId);
+        if (!exec) {
+            this.log.warn(`runExecution: execution ${executionId} not found`);
+            return;
+        }
+        const isResume = exec.status === 'EXTERNAL_WAIT';
+        const isFresh = exec.status === 'PENDING' || exec.status === 'SCHEDULED';
+        if (!isFresh && !isResume) {
+            this.log.warn(`runExecution: execution ${executionId} status=${exec.status} — skipping`);
+            return;
+        }
+        const workflow = await this.persistence.getWorkflow(exec.workflowId);
+        if (!workflow) {
+            await this.persistence.updateExecutionStatus(executionId, 'CANCELLED');
+            this.log.warn(`runExecution: workflow ${exec.workflowId} not found — CANCELLED`);
+            return;
+        }
+        const config = JSON.parse(workflow.config ?? '{}');
+        const state = await this.persistence.getExecutionState(executionId);
+        if (!state?.context) {
+            if (isResume) {
+                throw new Error(`runExecution: pause state missing for resume of ${executionId}`);
+            }
+            await this.persistence.updateExecutionStatus(executionId, 'FAILED');
+            this.log.error(`runExecution: state.context missing for ${executionId} — FAILED`);
+            return;
+        }
+        let context;
+        try {
+            context = JSON.parse(state.context);
+        }
+        catch {
+            if (isResume) {
+                throw new Error(`runExecution: state.context unparseable for resume of ${executionId}`);
+            }
+            await this.persistence.updateExecutionStatus(executionId, 'FAILED');
+            this.log.error(`runExecution: state.context unparseable for ${executionId} — FAILED`);
+            return;
+        }
+        // Hydrate trigger data if fresh run
+        if (!isResume && this.triggerRegistry.has(config.trigger.type)) {
+            const triggerImpl = this.triggerRegistry.get(config.trigger.type);
+            if (typeof triggerImpl.hydratePayload === 'function') {
+                try {
+                    const triggerData = context.trigger;
+                    const hydrated = await triggerImpl.hydratePayload(triggerData);
+                    context.trigger = {
+                        ...context.trigger,
+                        ...hydrated,
+                    };
+                }
+                catch (err) {
+                    this.log.warn(`runExecution: hydratePayload failed for ${executionId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Filter check
+            const filterConfig = (config.trigger.config ?? {});
+            if (!triggerImpl.matchFilters(filterConfig, context.trigger)) {
+                await this.persistence.updateExecutionStatus(executionId, 'SKIPPED');
+                await this.persistence.persistState(executionId, {
+                    context: JSON.stringify(context),
+                });
+                this.log.info(`runExecution: filter mismatch for ${executionId} — SKIPPED`);
+                return;
+            }
+        }
+        // Resume: hydrate step context from persisted step rows
+        let startIndex = 0;
+        let resumeAtIndex;
+        let branchResumePath;
+        if (isResume) {
+            const stepRows = await this.persistence.getStepRows(executionId);
+            for (const row of stepRows) {
+                const idx = parseStepIndex(row.stepName);
+                if (idx === null)
+                    continue;
+                const stepConfig = config.steps[idx];
+                if (!stepConfig || !row.data)
+                    continue;
+                const parsed = safeParseJson(row.data);
+                if (parsed) {
+                    context.steps[stepConfig.id] = {
+                        type: parsed.type ?? stepConfig.type,
+                        ...(parsed.input !== undefined ? { input: parsed.input } : {}),
+                        output: parsed.output ?? {},
+                    };
+                }
+            }
+            if (state.pauseType === 'review') {
+                // ─── Review-gate resume ───
+                const reviewedIdx = state.currentStepIndex;
+                const reviewedStep = config.steps[reviewedIdx];
+                const resumePayload = await this.persistence.getResumePayload(executionId);
+                const action = resumePayload?.action ?? 'approve';
+                if (action === 'abort') {
+                    await this.persistence.updateExecutionStatus(executionId, 'CANCELLED');
+                    this.emitEvent(executionId, { event: 'execution_cancelled', data: {} });
+                    this.log.info(`run ${executionId} review-gate ABORTED`);
+                    return;
+                }
+                if (action === 'retry' && reviewedStep) {
+                    // Re-execute the reviewed step fresh, with priorState + feedback overrides.
+                    startIndex = reviewedIdx;
+                    const priorRow = await this.persistence.getStep(executionId, `step_${String(reviewedIdx)}`);
+                    const priorState = priorRow?.data
+                        ? safeParseJson(priorRow.data) ?? undefined
+                        : undefined;
+                    context.__meta = {
+                        ...context.__meta,
+                        ...(priorState ? { __priorStepState: priorState } : {}),
+                        __configOverrides: extractConfigOverrides(resumePayload),
+                    };
+                    // Clear the entry so it re-executes (and downstream resolvers don't see stale output)
+                    delete context.steps[reviewedStep.id];
+                }
+                else {
+                    // approve: advance past the reviewed step
+                    startIndex = reviewedIdx + 1;
+                }
+            }
+            else {
+                // ─── Step-level pause resume (existing PausePath logic) ───
+                const savedPausePath = state.pausePath
+                    ? safeParseJson(state.pausePath)
+                    : null;
+                if (savedPausePath && savedPausePath.length > 0) {
+                    const first = savedPausePath[0];
+                    startIndex = first.stepIndex;
+                    resumeAtIndex = first.stepIndex;
+                    branchResumePath =
+                        savedPausePath.length > 1 ? savedPausePath.slice(1) : undefined;
+                }
+                else {
+                    startIndex = state.currentStepIndex;
+                    resumeAtIndex = state.currentStepIndex;
+                }
+            }
+        }
+        else {
+            // ─── Fresh-run path: check for rerunFromStep seed ───
+            const rerun = context.__meta?.rerunSource;
+            if (rerun) {
+                startIndex = rerun.fromStepIndex;
+            }
+        }
+        // Run — preserve transient seed fields (priorState, configOverrides, rerunSource)
+        // that the resume/rerun paths populated above.
+        const prevMeta = context.__meta ?? {};
+        context.__meta = {
+            ...prevMeta,
+            error: null,
+            chain: prevMeta.chain ?? [],
+        };
+        await this.persistence.updateExecutionStatus(executionId, 'RUNNING');
+        await this.persistence.persistState(executionId, {
+            context: JSON.stringify(context),
+        });
+        this.log.info(`run ${isResume ? 'RESUMED' : 'STARTED'} execId=${executionId} workflow=${workflow.id} startIndex=${startIndex}`);
+        await this.runSteps(executionId, context, config.steps, startIndex, resumeAtIndex, branchResumePath, config.settings);
+    }
+    /**
+     * Start a fresh execution for a workflow.
+     *
+     * Creates the execution record + initial state, then runs it.
+     * Returns the execution ID.
+     */
+    async startExecution(workflowId, context) {
+        const executionId = await this.persistence.createExecution({
+            workflowId,
+            status: 'PENDING',
+            context: JSON.stringify(context),
+        });
+        await this.runExecution(executionId);
+        return executionId;
+    }
+    /**
+     * Create a new execution that reruns from `fromStepId`, using the source
+     * execution's cached outputs for all prior steps as the resolved context.
+     *
+     * The new execution starts at `fromStepIndex` (not 0). Steps before that
+     * are pre-populated in `context.steps` so variable resolution finds them.
+     * The step at `fromStepIndex` receives the source row's data as
+     * `ctx.priorState` (when `inheritStepState` is true, the default), enabling
+     * agents and other stateful steps to continue from where they left off.
+     *
+     * Returns the new execution ID. Caller is responsible for enqueueing it.
+     */
+    async rerunFromStep(sourceExecutionId, fromStepId, options) {
+        const inheritStepState = options?.inheritStepState ?? true;
+        const source = await this.persistence.getExecution(sourceExecutionId);
+        if (!source) {
+            throw new Error(`Source execution ${sourceExecutionId} not found`);
+        }
+        const terminal = ['COMPLETED', 'FAILED', 'CANCELLED'];
+        if (!terminal.includes(source.status)) {
+            throw new Error(`Cannot rerun from non-terminal execution ${sourceExecutionId} (status: ${source.status})`);
+        }
+        const workflow = await this.persistence.getWorkflow(source.workflowId);
+        if (!workflow) {
+            throw new Error(`Workflow ${source.workflowId} not found`);
+        }
+        const config = JSON.parse(workflow.config ?? '{}');
+        const fromStepIndex = config.steps.findIndex((s) => s.id === fromStepId);
+        if (fromStepIndex < 0) {
+            throw new Error(`Step "${fromStepId}" not found in workflow ${source.workflowId}`);
+        }
+        const sourceState = await this.persistence.getExecutionState(sourceExecutionId);
+        if (!sourceState?.context) {
+            throw new Error(`Source execution ${sourceExecutionId} has no persisted context`);
+        }
+        const sourceContext = JSON.parse(sourceState.context);
+        // Seed the new context with the source's trigger + steps 0..N-1 outputs.
+        const seededSteps = {};
+        const stepRows = await this.persistence.getStepRows(sourceExecutionId);
+        const rowByName = new Map();
+        for (const row of stepRows) {
+            rowByName.set(row.stepName, row);
+        }
+        for (let i = 0; i < fromStepIndex; i++) {
+            const stepCfg = config.steps[i];
+            const row = rowByName.get(`step_${String(i)}`);
+            if (!row?.data)
+                continue;
+            const parsed = safeParseJson(row.data);
+            if (parsed) {
+                seededSteps[stepCfg.id] = {
+                    type: parsed.type ?? stepCfg.type,
+                    ...(parsed.input !== undefined ? { input: parsed.input } : {}),
+                    output: parsed.output ?? {},
+                };
+            }
+        }
+        // Priorstate for the entry step (the one being re-executed)
+        let priorStepState;
+        if (inheritStepState) {
+            const entryRow = rowByName.get(`step_${String(fromStepIndex)}`);
+            if (entryRow?.data) {
+                priorStepState =
+                    safeParseJson(entryRow.data) ?? undefined;
+            }
+        }
+        const newContext = {
+            workflow: sourceContext.workflow,
+            trigger: sourceContext.trigger,
+            steps: seededSteps,
+            __meta: {
+                error: null,
+                chain: sourceContext.__meta?.chain ?? [],
+                rerunSource: {
+                    executionId: sourceExecutionId,
+                    fromStepIndex,
+                    fromStepId,
+                },
+                ...(priorStepState ? { __priorStepState: priorStepState } : {}),
+                ...(options?.configOverrides
+                    ? { __configOverrides: options.configOverrides }
+                    : {}),
+            },
+        };
+        const newExecutionId = await this.persistence.createExecution({
+            workflowId: source.workflowId,
+            status: 'PENDING',
+            context: JSON.stringify(newContext),
+            sourceExecutionId,
+        });
+        this.log.info(`rerun created exec=${newExecutionId} from=${sourceExecutionId} step=${fromStepId}`);
+        return newExecutionId;
+    }
+    // ─── Internal: run loop ───
+    async runSteps(executionId, context, steps, startIndex, resumeAtIndex, branchResumePath, settings) {
+        try {
+            const walkResult = await this.walkSteps(steps, context, executionId, startIndex, resumeAtIndex, branchResumePath, settings);
+            if (walkResult.kind === 'paused') {
+                this.log.info(`run ${executionId} PAUSED at path=${JSON.stringify(walkResult.pausePath)}`);
+                return;
+            }
+            await this.persistence.updateExecutionStatus(executionId, 'COMPLETED');
+            context.__meta = { ...context.__meta, error: null };
+            await this.persistence.persistState(executionId, {
+                context: JSON.stringify(context),
+                currentStepIndex: steps.length,
+            });
+            this.emitEvent(executionId, { event: 'execution_completed', data: { status: 'COMPLETED' } });
+            this.log.info(`run ${executionId} COMPLETED`);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            await this.persistence.updateExecutionStatus(executionId, 'FAILED');
+            context.__meta = { ...context.__meta, error: errMsg };
+            await this.persistence.persistState(executionId, {
+                context: JSON.stringify(context),
+            });
+            this.emitEvent(executionId, { event: 'execution_failed', data: { error: errMsg } });
+            this.log.error(`run ${executionId} FAILED: ${errMsg}`);
+            throw err;
+        }
+    }
+    async walkSteps(steps, context, executionId, startIndex = 0, resumeAtIndex, branchResumePath, settings) {
+        const onError = settings?.onError ?? 'stop';
+        const retry = settings?.retry;
+        for (let i = startIndex; i < steps.length; i++) {
+            const step = steps[i];
+            const stepName = `step_${String(i)}`;
+            const isResuming = resumeAtIndex === i;
+            // Only pass branchResumePath for the step being resumed
+            const stepBranchResumePath = isResuming ? branchResumePath : undefined;
+            if (!isResuming) {
+                const executorType = CONTROL_FLOW_STEP_TYPES.has(step.type)
+                    ? 'conditional'
+                    : 'deterministic';
+                await this.persistence.upsertStep(executionId, stepName, {
+                    status: 'RUNNING',
+                    executorType,
+                });
+                this.emitEvent(executionId, {
+                    event: 'step_started',
+                    data: { stepName: step.id, stepType: step.type },
+                });
+            }
+            // Consume entry-step extras (priorState + configOverrides) on the first
+            // iteration only. These come from review-gate retry or rerunFromStep.
+            const isEntryStep = i === startIndex && !isResuming;
+            const entryPriorState = isEntryStep
+                ? context.__meta?.__priorStepState
+                : undefined;
+            const entryConfigOverrides = isEntryStep
+                ? context.__meta?.__configOverrides
+                : undefined;
+            if (isEntryStep && context.__meta) {
+                // Single-use — clear so subsequent steps don't see them.
+                delete context.__meta.__priorStepState;
+                delete context.__meta.__configOverrides;
+            }
+            try {
+                await this.executeStepWithRetry(step, context, { executionId, stepName, isResuming, priorState: entryPriorState, configOverrides: entryConfigOverrides }, stepBranchResumePath, retry);
+                const ctxEntry = context.steps[step.id];
+                await this.persistence.upsertStep(executionId, stepName, {
+                    status: 'COMPLETED',
+                    executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
+                        ? 'conditional'
+                        : 'deterministic',
+                    data: JSON.stringify(ctxEntry ?? { output: null }),
+                });
+                this.emitEvent(executionId, {
+                    event: 'step_completed',
+                    data: {
+                        stepName: step.id,
+                        output: (ctxEntry?.output ?? {}),
+                    },
+                });
+                // ─── Review gate: pause after step completes if onComplete === 'review' ───
+                if (step.onComplete === 'review') {
+                    const reviewPauseState = {
+                        reason: `Review output of "${step.id}"`,
+                        category: 'review',
+                        display: ctxEntry?.output
+                            ? [{ label: 'Output', value: ctxEntry.output }]
+                            : undefined,
+                        actions: [
+                            { key: 'approve', label: 'Approve', style: 'primary' },
+                            { key: 'retry', label: 'Retry with Feedback', style: 'default', submitsForm: true },
+                            { key: 'abort', label: 'Reject', style: 'danger', abort: true },
+                        ],
+                        form: {
+                            fields: [
+                                {
+                                    type: 'textarea',
+                                    name: 'feedback',
+                                    label: 'Feedback',
+                                    placeholder: 'Optional instructions for retry...',
+                                },
+                            ],
+                        },
+                    };
+                    await this.persistence.persistState(executionId, {
+                        context: JSON.stringify(context),
+                        currentStepIndex: i,
+                        pauseType: 'review',
+                    });
+                    await this.persistence.updateExecutionStatus(executionId, 'EXTERNAL_WAIT');
+                    this.emitEvent(executionId, {
+                        event: 'execution_paused',
+                        data: { stepName: step.id, pauseState: reviewPauseState },
+                    });
+                    this.log.info(`run ${executionId} REVIEW-GATE paused at step=${step.id}`);
+                    return { kind: 'paused', pausePath: [], externalRef: undefined };
+                }
+            }
+            catch (err) {
+                if (PauseStep.is(err)) {
+                    const pe = err;
+                    const fullPath = [
+                        { stepIndex: i },
+                        ...(pe._pausePath ?? []),
+                    ];
+                    const ctxEntry = context.steps[step.id];
+                    const base = ctxEntry ?? { type: step.type, output: {} };
+                    const merged = pe.statePatch
+                        ? { ...base, ...pe.statePatch }
+                        : base;
+                    await this.persistence.upsertStep(executionId, stepName, {
+                        status: 'EXTERNAL_WAIT',
+                        executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
+                            ? 'conditional'
+                            : 'deterministic',
+                        data: JSON.stringify(merged),
+                    });
+                    await this.persistence.persistState(executionId, {
+                        context: JSON.stringify(context),
+                        currentStepIndex: i,
+                        pausePath: JSON.stringify(fullPath),
+                    });
+                    await this.persistence.updateExecutionStatus(executionId, 'EXTERNAL_WAIT');
+                    this.emitEvent(executionId, {
+                        event: 'execution_paused',
+                        data: {
+                            stepName: step.id,
+                            pauseState: merged['pauseState'] ?? { reason: pe.message },
+                        },
+                    });
+                    return {
+                        kind: 'paused',
+                        pausePath: fullPath,
+                        externalRef: pe.externalRef,
+                    };
+                }
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const ctxEntry = context.steps[step.id];
+                if (onError === 'continue') {
+                    context.steps[step.id] = {
+                        type: step.type,
+                        ...(ctxEntry?.input !== undefined
+                            ? { input: ctxEntry.input }
+                            : {}),
+                        output: ctxEntry?.output ?? {},
+                        error: errMsg,
+                    };
+                    await this.persistence.upsertStep(executionId, stepName, {
+                        status: 'FAILED',
+                        executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
+                            ? 'conditional'
+                            : 'deterministic',
+                        data: JSON.stringify({ ...(ctxEntry ?? {}), error: errMsg }),
+                    });
+                    this.emitEvent(executionId, {
+                        event: 'step_failed',
+                        data: { stepName: step.id, error: errMsg },
+                    });
+                    this.log.warn(`step ${step.id} failed but continuing: ${errMsg}`);
+                    continue;
+                }
+                await this.persistence.upsertStep(executionId, stepName, {
+                    status: 'FAILED',
+                    executorType: CONTROL_FLOW_STEP_TYPES.has(step.type)
+                        ? 'conditional'
+                        : 'deterministic',
+                    data: JSON.stringify({ ...(ctxEntry ?? {}), error: errMsg }),
+                });
+                this.emitEvent(executionId, {
+                    event: 'step_failed',
+                    data: { stepName: step.id, error: errMsg },
+                });
+                throw err;
+            }
+        }
+        return { kind: 'completed' };
+    }
+    async executeStepWithRetry(step, context, callCtx, branchResumePath, retry) {
+        if (!retry || callCtx.isResuming) {
+            await this.executeStep(step, context, callCtx, branchResumePath);
+            return;
+        }
+        let lastError;
+        for (let attempt = 1; attempt <= retry.maxAttempts; attempt++) {
+            try {
+                await this.executeStep(step, context, callCtx, branchResumePath);
+                return;
+            }
+            catch (err) {
+                if (PauseStep.is(err))
+                    throw err;
+                lastError = err;
+                this.log.warn(`step ${step.id} attempt ${String(attempt)}/${String(retry.maxAttempts)} failed: ${err instanceof Error ? err.message : String(err)}`);
+                if (attempt < retry.maxAttempts) {
+                    await delay(retry.intervalMs);
+                }
+            }
+        }
+        throw lastError;
+    }
+    async executeStep(step, context, callCtx, branchResumePath) {
+        const stepImpl = this.stepRegistry.get(step.type);
+        if (stepImpl.kind === StepKind.CONTROL) {
+            const controlImpl = stepImpl;
+            const parsed = controlImpl.configSchema.safeParse(step.config);
+            if (!parsed.success) {
+                throw new Error(`Step "${step.id}" (${step.type}) config validation failed:\n${formatZodErrors(parsed.error)}`);
+            }
+            this.log.info(`step ${callCtx.isResuming ? 'RESUME' : 'START'} id=${step.id} type=${step.type}`);
+            const t0 = Date.now();
+            const stepCtx = await this.buildStepContext(context, { ...callCtx, stepId: step.id }, stepImpl);
+            const output = await controlImpl.execute(parsed.data, {
+                ...stepCtx,
+                walkBranch: (branchSteps, ctx, branchKey) => this.walkBranchSteps(branchSteps, ctx, callCtx.executionId, step.id, branchKey, branchResumePath),
+            });
+            context.steps[step.id] = { type: step.type, output };
+            this.log.info(`step OK id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms`);
+            return;
+        }
+        // Action step: merge configOverrides → resolve variables → validate → execute
+        const baseConfig = callCtx.configOverrides
+            ? { ...step.config, ...callCtx.configOverrides }
+            : step.config;
+        const resolvedConfig = stripNullForOptionalKeys(this.resolver.resolve(baseConfig, context), stepImpl.configSchema);
+        const parsed = stepImpl.configSchema.safeParse(resolvedConfig);
+        if (!parsed.success) {
+            throw new Error(`Step "${step.id}" (${step.type}) config validation failed after variable resolution:\n${formatZodErrors(parsed.error)}`);
+        }
+        const resolvedInput = parsed.data;
+        const persistedInput = stepImpl.redactInput
+            ? stepImpl.redactInput(resolvedInput)
+            : resolvedInput;
+        context.steps[step.id] = {
+            type: step.type,
+            input: persistedInput,
+            output: {},
+        };
+        const actionImpl = stepImpl;
+        const stepCtx = await this.buildStepContext(context, { ...callCtx, stepId: step.id }, stepImpl);
+        this.log.info(`step ${callCtx.isResuming ? 'RESUME' : 'START'} id=${step.id} type=${step.type}`);
+        const t0 = Date.now();
+        try {
+            let output;
+            if (callCtx.isResuming) {
+                output = await this.invokeResume(actionImpl, callCtx.executionId, callCtx.stepName, resolvedInput, stepCtx);
+            }
+            else {
+                output = await actionImpl.execute(resolvedInput, stepCtx);
+            }
+            context.steps[step.id] = {
+                type: step.type,
+                input: persistedInput,
+                output,
+            };
+            this.log.info(`step OK id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms`);
+        }
+        catch (err) {
+            if (!PauseStep.is(err)) {
+                this.log.error(`step FAIL id=${step.id} type=${step.type} elapsed=${String(Date.now() - t0)}ms err=${err instanceof Error ? err.message : String(err)}`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Walk steps inside a control-flow branch. Supports nested pause.
+     *
+     * Each sub-step is persisted as its own row (keyed by config `id`) and
+     * emits SSE events, mirroring the top-level `walkSteps` behavior.
+     *
+     * When a step pauses inside a branch, the PauseStep error is enriched
+     * with branch path information and re-thrown so the top-level walkSteps
+     * can persist the full PausePath.
+     */
+    async walkBranchSteps(steps, context, executionId, controlStepId, branchKey, branchResumePath) {
+        const resolvedBranchKey = branchKey ?? 'default';
+        // Determine start position for resume within this branch
+        let startIndex = 0;
+        let innerResuming = false;
+        let deeperResumePath;
+        if (branchResumePath && branchResumePath.length > 0) {
+            const segment = branchResumePath[0];
+            if (segment.branch?.stepId === controlStepId &&
+                segment.branch.branchKey === resolvedBranchKey) {
+                startIndex = segment.stepIndex;
+                innerResuming = true;
+                deeperResumePath =
+                    branchResumePath.length > 1
+                        ? branchResumePath.slice(1)
+                        : undefined;
+            }
+        }
+        for (let j = startIndex; j < steps.length; j++) {
+            const bStep = steps[j];
+            const isResuming = innerResuming && j === startIndex;
+            const executorType = CONTROL_FLOW_STEP_TYPES.has(bStep.type)
+                ? 'conditional'
+                : 'deterministic';
+            // Persist RUNNING + emit event (skip for resuming steps)
+            if (!isResuming && executionId) {
+                await this.persistence.upsertStep(executionId, bStep.id, {
+                    status: 'RUNNING',
+                    executorType,
+                });
+                this.emitEvent(executionId, {
+                    event: 'step_started',
+                    data: { stepName: bStep.id, stepType: bStep.type },
+                });
+            }
+            try {
+                await this.executeStep(bStep, context, {
+                    executionId,
+                    stepName: bStep.id,
+                    isResuming,
+                }, isResuming ? deeperResumePath : undefined);
+                // Persist COMPLETED + emit event
+                if (executionId) {
+                    const ctxEntry = context.steps[bStep.id];
+                    await this.persistence.upsertStep(executionId, bStep.id, {
+                        status: 'COMPLETED',
+                        executorType,
+                        data: JSON.stringify(ctxEntry ?? { output: null }),
+                    });
+                    this.emitEvent(executionId, {
+                        event: 'step_completed',
+                        data: {
+                            stepName: bStep.id,
+                            output: (ctxEntry?.output ?? {}),
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                if (PauseStep.is(err)) {
+                    const pe = err;
+                    // Persist EXTERNAL_WAIT for the sub-step
+                    if (executionId) {
+                        const ctxEntry = context.steps[bStep.id];
+                        const base = ctxEntry ?? { type: bStep.type, output: {} };
+                        const merged = pe.statePatch
+                            ? { ...base, ...pe.statePatch }
+                            : base;
+                        await this.persistence.upsertStep(executionId, bStep.id, {
+                            status: 'EXTERNAL_WAIT',
+                            executorType,
+                            data: JSON.stringify(merged),
+                        });
+                    }
+                    pe._pausePath = [
+                        {
+                            stepIndex: j,
+                            branch: {
+                                stepId: controlStepId,
+                                branchKey: resolvedBranchKey,
+                            },
+                        },
+                        ...(pe._pausePath ?? []),
+                    ];
+                    throw pe;
+                }
+                // Persist FAILED + emit event
+                if (executionId) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    await this.persistence.upsertStep(executionId, bStep.id, {
+                        status: 'FAILED',
+                        executorType,
+                        data: JSON.stringify({ error: errMsg }),
+                    });
+                    this.emitEvent(executionId, {
+                        event: 'step_failed',
+                        data: { stepName: bStep.id, error: errMsg },
+                    });
+                }
+                throw err;
+            }
+        }
+    }
+    async invokeResume(actionImpl, executionId, stepName, resolvedInput, ctx) {
+        const row = await this.persistence.getStep(executionId, stepName);
+        let rowData = row?.data
+            ? (safeParseJson(row.data) ?? {})
+            : {};
+        // Merge user's resume payload (approve/reject/form data) into rowData
+        const resumePayload = await this.persistence.getResumePayload(executionId);
+        if (resumePayload) {
+            rowData = { ...rowData, resumePayload };
+        }
+        if (typeof actionImpl.onResume === 'function') {
+            return actionImpl.onResume(rowData, resolvedInput, ctx);
+        }
+        const fallback = rowData['output'];
+        return fallback &&
+            typeof fallback === 'object' &&
+            !Array.isArray(fallback)
+            ? fallback
+            : {};
+    }
+    async buildStepContext(context, callCtx, stepImpl) {
+        // Resolve credentials if step declares credentialSlots
+        let credentials = {};
+        if (stepImpl.credentialSlots && stepImpl.credentialSlots.length > 0) {
+            for (const slot of stepImpl.credentialSlots) {
+                const resolved = await this.persistence.resolveCredential(context.workflow.metadata, slot.name);
+                if (resolved) {
+                    credentials[slot.name] = resolved;
+                }
+                else if (slot.required) {
+                    throw new Error(`Required credential "${slot.name}" not found`);
+                }
+            }
+        }
+        return {
+            workflow: context,
+            runtime: {
+                executionId: callCtx.executionId,
+                stepId: callCtx.stepId,
+                stepName: callCtx.stepName,
+                isResuming: callCtx.isResuming,
+                metadata: context.workflow.metadata,
+                baseUrl: this.baseUrl,
+            },
+            ...(callCtx.priorState ? { priorState: callCtx.priorState } : {}),
+            services: this.services,
+            credentials,
+            staticData: {
+                get: (key) => this.persistence.getStaticData(context.workflow.id, key),
+                set: (key, value) => this.persistence.setStaticData(context.workflow.id, key, value),
+                delete: (key) => this.persistence.deleteStaticData(context.workflow.id, key),
+            },
+            pause: createPauseFunction(),
+            emit: (event) => {
+                const normalized = {
+                    type: event.type,
+                    data: JSON.stringify(event.data),
+                };
+                // Fire-and-forget — never blocks step execution
+                this.persistence
+                    .appendStepEvent(callCtx.executionId, callCtx.stepName, normalized)
+                    .catch((err) => {
+                    this.log.warn(`Failed to persist step event: ${err instanceof Error ? err.message : String(err)}`);
+                });
+                // Also forward to the SSE event bus
+                this.emitEvent(callCtx.executionId, {
+                    event: 'step_progress',
+                    data: { stepName: callCtx.stepId, ...event.data },
+                });
+            },
+            log: this.log,
+        };
+    }
+}
+// ─── Helpers ───
+function safeParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function parseStepIndex(name) {
+    const m = /^step_(\d+)$/.exec(name);
+    if (!m?.[1])
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isInteger(n) ? n : null;
+}
+function formatZodErrors(error) {
+    return error.issues
+        .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+        .join('\n');
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Convert a review-gate retry's resume payload into config overrides
+ * the entry step will see. Surfaces `feedback` + `attachments` as top-level
+ * keys (so steps can read them without unwrapping), then merges the opaque
+ * `data` blob underneath.
+ */
+function extractConfigOverrides(payload) {
+    if (!payload)
+        return {};
+    const overrides = {};
+    if (payload.data) {
+        Object.assign(overrides, payload.data);
+    }
+    if (payload.feedback !== undefined)
+        overrides['feedback'] = payload.feedback;
+    if (payload.attachments !== undefined)
+        overrides['attachments'] = payload.attachments;
+    return overrides;
+}
+//# sourceMappingURL=workflow-executor.js.map