@sensigo/realm 0.1.0

package/dist/engine/execution-loop.js

@@ -0,0 +1,1156 @@
+import { WorkflowError } from '../types/workflow-error.js';
+import { captureEvidence } from '../evidence/snapshot.js';
+import { validateInputSchema, validateOutputSchema, validateTraceSchema, } from '../validation/input-schema.js';
+import { normalizeTrace } from './trace-normalizer.js';
+import { TERMINAL_PHASES } from './lifecycle.js';
+import { checkPreconditions, evaluateAllPreconditions } from './precondition.js';
+import { ExtensionRegistry } from '../extensions/registry.js';
+import { createDefaultRegistry } from '../extensions/default-registry.js';
+import { resolveSecret } from '../config/secrets.js';
+import { renderTemplate, resolvePath, UnknownFilterError } from './render-template.js';
+import { generateSchemaSkeleton } from '../utils/schema-skeleton.js';
+import { loadWorkflowContext } from './workflow-context-loader.js';
+import { findEligibleSteps, isWorkflowComplete, buildEvidenceByStep, propagateSkips, } from './eligibility.js';
+import { resolvePreExecutionAgentAction, resolvePostDispatchAgentAction, } from './error-resolution.js';
+function delayMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Executes `dispatch` with a cancellation signal. If `dispatch` does not complete within `ms`
+ * milliseconds, the signal is aborted and a STEP_TIMEOUT WorkflowError is thrown.
+ */
+function withTimeout(dispatch, ms, stepName) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new WorkflowError(`Step '${stepName}' timed out after ${ms}ms`, {
+                code: 'STEP_TIMEOUT',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { stepName, timeout_ms: ms },
+            }));
+        }, ms);
+    });
+    return Promise.race([dispatch(controller.signal), timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Resolves an input_map declaration into a concrete params object.
+ * Falls back to options.input when input_map is absent.
+ */
+function resolveInputMap(inputMap, options, pendingRun) {
+    if (inputMap === undefined)
+        return options.input;
+    const evidenceByStep = buildEvidenceByStep(pendingRun);
+    const root = {
+        run: { params: pendingRun.params },
+        context: { resources: evidenceByStep },
+    };
+    const result = {};
+    for (const [key, path] of Object.entries(inputMap)) {
+        result[key] = resolvePath(path, root);
+    }
+    return result;
+}
+/** Computes the delay (ms) before a retry attempt based on the configured backoff strategy. */
+function computeBackoff(config, attemptNum) {
+    const backoff = config.backoff ?? 'fixed';
+    const base = config.base_delay_ms ?? 0;
+    let delay;
+    switch (backoff) {
+        case 'linear':
+            delay = base * attemptNum;
+            break;
+        case 'exponential':
+            delay = base * Math.pow(2, attemptNum - 1);
+            break;
+        default: // 'fixed'
+            delay = base;
+    }
+    return config.max_delay_ms !== undefined ? Math.min(delay, config.max_delay_ms) : delay;
+}
+/**
+ * Resolves and calls the service adapter for an auto step with `uses_service`.
+ *
+ * @param rateLimiterRegistry - Stable registry for rate-limiter state. Must be the same
+ *   instance across all retry attempts of this step so that pause/resume coordination
+ *   is preserved. Created once per executeStep() invocation and shared here.
+ */
+async function callAdapter(stepDef, definition, options, pendingRun, rateLimiterRegistry, signal) {
+    const serviceName = stepDef.uses_service;
+    const serviceDef = definition.services?.[serviceName];
+    if (serviceDef === undefined) {
+        throw new WorkflowError(`Service '${serviceName}' not found in workflow definition`, {
+            code: 'ENGINE_ADAPTER_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+            stepId: options.command,
+        });
+    }
+    // Adapter lookup: use the caller-provided registry for custom adapters; fall back to
+    // the built-in default registry (FileSystemAdapter etc.) when none is provided.
+    const adapter = (options.registry ?? createDefaultRegistry()).getAdapter(serviceDef.adapter);
+    if (adapter === undefined) {
+        throw new WorkflowError(`Adapter '${serviceDef.adapter}' for service '${serviceName}' is not registered`, {
+            code: 'ENGINE_ADAPTER_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+            stepId: options.command,
+        });
+    }
+    const secrets = options.secrets ?? {};
+    const config = { adapter: serviceDef.adapter, trust: serviceDef.trust };
+    if (serviceDef.auth?.token_from !== undefined) {
+        config['auth'] = { token: resolveSecret(serviceDef.auth.token_from, secrets) };
+    }
+    const method = stepDef.service_method ?? 'fetch';
+    const operation = stepDef.operation ?? options.command;
+    const adapterParams = resolveInputMap(stepDef.input_map, options, pendingRun);
+    // Guard: `delete` is optional on ServiceAdapter. If the adapter omits it, surface
+    // ADAPTER_OP_UNSUPPORTED rather than allowing a TypeError from an undefined call.
+    const adapterMethod = adapter[method];
+    if (typeof adapterMethod !== 'function') {
+        throw new WorkflowError(`Adapter '${serviceDef.adapter}' does not support service_method '${method}'`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+    // Proactive rate limiting: acquire a token before calling the service.
+    // rateLimiterRegistry is always defined (step-scoped; see executeStep).
+    if (serviceDef.rate_limit?.requests_per_second !== undefined) {
+        await rateLimiterRegistry
+            .getOrCreateRateLimiter(serviceName, serviceDef.rate_limit)
+            .acquire(signal);
+    }
+    let response;
+    try {
+        response = await adapterMethod.call(adapter, operation, adapterParams, config, signal);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError) {
+            if (err.code === 'SERVICE_RATE_LIMITED') {
+                // Resolve retry_after through the three-tier fallback chain:
+                //   1. Header value (already on err.retry_after from the adapter)
+                //   2. rate_limit.fallback_retry_seconds from YAML
+                //   3. adapter.defaultRetryAfterSeconds constant
+                const resolvedRetryAfter = err.retry_after ??
+                    serviceDef.rate_limit?.fallback_retry_seconds ??
+                    adapter?.defaultRetryAfterSeconds;
+                // Pause the token bucket for the resolved retry window.
+                // The cap (Math.min with max_retry_seconds) is applied before calling pause() so
+                // that concurrent callers are never held longer than max_retry_seconds. The pause
+                // fires before the fail-fast throw below — this is intentional: even when the
+                // current step exits immediately, the bucket is paused to prevent a burst of
+                // immediate retries from concurrent steps against an already-overloaded service.
+                const maxRetry = serviceDef.rate_limit?.max_retry_seconds;
+                if (serviceDef.rate_limit?.requests_per_second !== undefined &&
+                    resolvedRetryAfter !== undefined) {
+                    const pauseDuration = maxRetry !== undefined ? Math.min(resolvedRetryAfter, maxRetry) : resolvedRetryAfter;
+                    if (pauseDuration > 0) {
+                        rateLimiterRegistry
+                            .getOrCreateRateLimiter(serviceName, serviceDef.rate_limit)
+                            .pause(pauseDuration);
+                    }
+                }
+                // Fail fast when the retry window exceeds max_retry_seconds.
+                // The pause above has already fired with a capped duration — this throw
+                // signals the retry loop to stop rather than wait the full retry window.
+                if (maxRetry !== undefined &&
+                    resolvedRetryAfter !== undefined &&
+                    resolvedRetryAfter > maxRetry) {
+                    throw new WorkflowError(err.message, {
+                        code: 'SERVICE_RATE_LIMITED',
+                        category: 'SERVICE',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                        retry_after: resolvedRetryAfter,
+                        ...(Object.keys(err.details).length > 0 ? { details: err.details } : {}),
+                    });
+                }
+                // Re-throw with the resolved retry_after (may differ from original).
+                if (resolvedRetryAfter !== err.retry_after) {
+                    throw new WorkflowError(err.message, {
+                        code: 'SERVICE_RATE_LIMITED',
+                        category: 'SERVICE',
+                        agentAction: 'wait_and_proceed',
+                        retryable: true,
+                        ...(resolvedRetryAfter !== undefined ? { retry_after: resolvedRetryAfter } : {}),
+                        ...(Object.keys(err.details).length > 0 ? { details: err.details } : {}),
+                    });
+                }
+            }
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new WorkflowError(`Adapter '${serviceDef.adapter}' threw: ${message}`, {
+            code: 'ENGINE_ADAPTER_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+            stepId: options.command,
+        });
+    }
+    const output = typeof response.data === 'object' && response.data !== null
+        ? response.data
+        : { data: response.data, status: response.status };
+    return {
+        output,
+        resolvedParams: stepDef.input_map !== undefined ? adapterParams : undefined,
+    };
+}
+/**
+ * Resolves and calls the step handler for an auto step with a `handler` reference.
+ */
+async function callHandler(stepDef, options, pendingRun, evidenceByStep, signal) {
+    const handlerName = stepDef.handler;
+    const handler = (options.registry ?? createDefaultRegistry()).getHandler(handlerName);
+    if (handler === undefined) {
+        throw new WorkflowError(`Handler '${handlerName}' is not registered`, {
+            code: 'ENGINE_HANDLER_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+            stepId: options.command,
+        });
+    }
+    let result;
+    try {
+        result = await handler.execute({ params: options.input }, {
+            run_id: options.runId,
+            run_params: pendingRun.params,
+            config: stepDef.config ?? {},
+            resources: evidenceByStep,
+        }, signal);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError)
+            throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new WorkflowError(`Handler '${handlerName}' threw: ${message}`, {
+            code: 'ENGINE_HANDLER_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+            stepId: options.command,
+        });
+    }
+    return result.data;
+}
+/**
+ * Builds a NextAction for a single eligible step, resolving prompt templates.
+ */
+function stepToNextAction(stepName, step, context) {
+    const resolvedPrompt = step.prompt !== undefined ? renderTemplate(step.prompt, context) : undefined;
+    return {
+        instruction: step.handler !== undefined
+            ? { tool: step.handler, params: {}, call_with: {} }
+            : step.execution === 'agent'
+                ? {
+                    tool: 'execute_step',
+                    params: { run_id: context.runId, command: stepName },
+                    call_with: {
+                        run_id: context.runId,
+                        command: stepName,
+                        params: step.input_schema !== undefined
+                            ? generateSchemaSkeleton(step.input_schema)
+                            : {},
+                    },
+                }
+                : null,
+        ...(step.execution === 'agent' && step.input_schema !== undefined
+            ? { input_schema: step.input_schema }
+            : {}),
+        human_readable: `Execute step '${stepName}': ${step.description}`,
+        orientation: `Run is active. Next step ready: '${stepName}'.`,
+        ...(step.timeout_seconds !== undefined ? { expected_timeout: `${step.timeout_seconds}s` } : {}),
+        ...(resolvedPrompt !== undefined ? { prompt: resolvedPrompt } : {}),
+    };
+}
+/**
+ * Returns NextAction objects for all agent-executable eligible steps.
+ * Auto steps are excluded — they are executed internally by executeChain.
+ */
+export function buildNextActions(definition, run) {
+    const eligible = findEligibleSteps(definition, run);
+    const evidenceByStep = buildEvidenceByStep(run);
+    const context = {
+        evidenceByStep,
+        runParams: run.params,
+        runId: run.id,
+        ...(run.workflow_context_snapshots !== undefined
+            ? {
+                workflowContext: {
+                    snapshots: run.workflow_context_snapshots,
+                    wrapper: (definition.context_wrapper ?? 'xml'),
+                },
+            }
+            : {}),
+    };
+    return eligible
+        .filter((name) => definition.steps[name]?.execution === 'agent' ||
+        definition.steps[name]?.handler !== undefined)
+        .map((name) => stepToNextAction(name, definition.steps[name], context));
+}
+/**
+ * Merges call-scoped trace-schema warnings with an optional cleanup warning into
+ * a single warnings array. Trace warnings are listed first (deterministic order).
+ */
+function mergeWarnings(traceWarnings, cleanupWarning) {
+    if (traceWarnings.length === 0 && cleanupWarning === undefined)
+        return [];
+    return cleanupWarning !== undefined ? [...traceWarnings, cleanupWarning] : [...traceWarnings];
+}
+/** Builds a minimal error ResponseEnvelope from primitive fields. */
+function errorEnvelope(command, runId, runVersion, err, contextHint) {
+    return {
+        command,
+        run_id: runId,
+        run_version: runVersion,
+        status: 'error',
+        data: {},
+        evidence: [],
+        warnings: [],
+        errors: [err.message],
+        error_code: err.code,
+        ...(Object.keys(err.details).length > 0 ? { error_details: err.details } : {}),
+        agent_action: err.agentAction,
+        ...(err.retry_after !== undefined ? { retry_after: err.retry_after } : {}),
+        context_hint: contextHint ?? `Error during '${command}'.`,
+        next_actions: [],
+    };
+}
+/**
+ * Builds a ResponseEnvelope for errors caught in an MCP tool's outer catch block,
+ * before any step execution has occurred. Translates provide_input and
+ * resolve_precondition agent actions to report_to_user (pre-execution context).
+ */
+export function buildPreExecutionErrorEnvelope(command, runId, runVersion, err, contextHint) {
+    const agentAction = resolvePreExecutionAgentAction(err);
+    return {
+        command,
+        run_id: runId,
+        run_version: runVersion,
+        status: 'error',
+        data: {},
+        evidence: [],
+        warnings: [],
+        errors: [err.message],
+        error_code: err.code,
+        ...(Object.keys(err.details).length > 0 ? { error_details: err.details } : {}),
+        agent_action: agentAction,
+        ...(err.retry_after !== undefined ? { retry_after: err.retry_after } : {}),
+        context_hint: contextHint ?? `Error during '${command}'.`,
+        next_actions: [],
+    };
+}
+function makeErrorEnvelope(options, run, err, definition, extraWarnings) {
+    const hint = run !== null ? `Error during '${options.command}'. Run phase: '${run.run_phase}'.` : undefined;
+    const base = errorEnvelope(options.command, options.runId, run !== null ? run.version : 0, err, hint);
+    // Apply pre-execution translation: provide_input / resolve_precondition cannot
+    // apply before claimStep — translate them to report_to_user.
+    const translatedBase = run === null ? { ...base, agent_action: resolvePreExecutionAgentAction(err) } : base;
+    const baseWithWarnings = extraWarnings !== undefined && extraWarnings.length > 0
+        ? { ...translatedBase, warnings: extraWarnings }
+        : translatedBase;
+    if (run !== null && definition !== undefined && err.agentAction !== 'stop') {
+        return { ...baseWithWarnings, next_actions: buildNextActions(definition, run) };
+    }
+    return baseWithWarnings;
+}
+/**
+ * Validates eligibility, claims the step, executes it through the dispatcher with retry
+ * and timeout support, captures evidence, persists the updated run record, and returns
+ * a ResponseEnvelope containing the outcome and the next eligible actions.
+ */
+export async function executeStep(store, definition, options) {
+    // Step 1: Load run.
+    let run;
+    try {
+        run = await store.get(options.runId);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError) {
+            return makeErrorEnvelope(options, null, err);
+        }
+        const internal = new WorkflowError('Failed to load run from store', {
+            code: 'ENGINE_STORE_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+        });
+        return makeErrorEnvelope(options, null, internal);
+    }
+    // Step 2: Check eligibility.
+    const eligible = findEligibleSteps(definition, run);
+    if (!eligible.includes(options.command)) {
+        const nextActions = buildNextActions(definition, run);
+        return {
+            command: options.command,
+            run_id: options.runId,
+            run_version: run.version,
+            status: 'blocked',
+            data: {},
+            evidence: [],
+            warnings: [],
+            errors: [],
+            agent_action: 'resolve_precondition',
+            context_hint: `Step '${options.command}' is not eligible in the current run state.`,
+            next_actions: nextActions,
+            blocked_reason: nextActions.length > 0
+                ? {
+                    eligible_steps: eligible,
+                    suggestion: `Call one of the steps indicated in next_actions instead.`,
+                }
+                : {
+                    eligible_steps: eligible,
+                    suggestion: `No eligible steps available. Check run_phase and completed_steps.`,
+                },
+        };
+    }
+    const stepDef = definition.steps[options.command];
+    const evidenceByStep = buildEvidenceByStep(run);
+    // Step 2a: Evaluate preconditions.
+    if (stepDef?.preconditions !== undefined && stepDef.preconditions.length > 0) {
+        const failed = checkPreconditions(stepDef.preconditions, evidenceByStep);
+        if (failed !== null) {
+            return {
+                command: options.command,
+                run_id: options.runId,
+                run_version: run.version,
+                status: 'blocked',
+                data: {},
+                evidence: [],
+                warnings: [],
+                errors: [],
+                agent_action: 'stop',
+                context_hint: `Precondition failed for step '${options.command}'.`,
+                next_actions: [],
+                blocked_reason: {
+                    eligible_steps: eligible,
+                    suggestion: `Precondition failed: '${failed.expression}'. Resolved value: ${String(failed.resolved_value)}.`,
+                },
+            };
+        }
+    }
+    const preconditionTrace = evaluateAllPreconditions(stepDef?.preconditions ?? [], evidenceByStep);
+    let inputTokenEstimate = Math.ceil(JSON.stringify(options.input).length / 4);
+    // Step 2b: Validate input schema.
+    if (stepDef?.input_schema !== undefined) {
+        try {
+            validateInputSchema(options.input, stepDef.input_schema, options.command);
+        }
+        catch (err) {
+            return makeErrorEnvelope(options, run, err, definition);
+        }
+    }
+    // Step 2c: Validate output schema (agent steps only).
+    // For agent steps dispatch is a pass-through, so options.input IS the agent's
+    // submitted output. Validating here (pre-claim) is equivalent to
+    // "post-generation, pre-commit" — the standard output guardrail position.
+    if (stepDef?.execution === 'agent' && stepDef.output_schema !== undefined) {
+        try {
+            validateOutputSchema(options.input, stepDef.output_schema, options.command);
+        }
+        catch (err) {
+            return makeErrorEnvelope(options, run, err, definition);
+        }
+    }
+    // Step 2d: Merge WAL buffer + execute_step trace, normalize, validate (agent steps only, pre-claim).
+    // walEntries is declared at this scope so it is in scope at the captureEvidence call site below.
+    const traceWarnings = [];
+    let preNormalizedTrace;
+    let walEntries = [];
+    if (stepDef?.execution === 'agent') {
+        // Read WAL buffer if a buffer store is configured.
+        walEntries =
+            options.traceBufferStore !== undefined
+                ? await options.traceBufferStore.read(options.runId, options.command)
+                : [];
+        const hasAnyTrace = walEntries.length > 0 || (options.trace !== undefined && options.trace.length > 0);
+        if (hasAnyTrace) {
+            // Build merge set: WAL entries carry their _internalTs; execute_step entries
+            // receive Date.now() so they sort after all WAL batches (step conclusion ordering).
+            const finalTs = Date.now();
+            const mergeSet = [
+                ...walEntries, // already have _internalTs from buffer store
+                ...(options.trace ?? []).map((e) => ({ ...e, _internalTs: finalTs })),
+            ];
+            // Sort by _internalTs to produce chronological order, then strip the field before
+            // passing to normalizeTrace (which operates on plain AgentTraceEntry[]).
+            mergeSet.sort((a, b) => a._internalTs - b._internalTs);
+            const sortedEntries = mergeSet.map(({ _internalTs: _, ...rest }) => rest);
+            // Normalize the merged set once. This is the single canonicalization pass.
+            preNormalizedTrace = normalizeTrace(sortedEntries);
+            // Validate trace schema if configured (unchanged call site).
+            if (stepDef.trace_schema !== undefined) {
+                const mode = stepDef.trace_validation_mode ?? 'warn';
+                if (mode === 'enforce') {
+                    try {
+                        validateTraceSchema(preNormalizedTrace.entries, stepDef.trace_schema, options.command, 'enforce');
+                        preNormalizedTrace.summary.schema_applied = true;
+                        preNormalizedTrace.summary.validation_mode = 'enforce';
+                        preNormalizedTrace.summary.validation_errors = 0;
+                    }
+                    catch (err) {
+                        // On enforce rejection: do NOT delete the WAL — agent retries with WAL preserved.
+                        return makeErrorEnvelope(options, run, err, definition);
+                    }
+                }
+                else {
+                    const result = validateTraceSchema(preNormalizedTrace.entries, stepDef.trace_schema, options.command, 'warn');
+                    preNormalizedTrace.summary.schema_applied = true;
+                    preNormalizedTrace.summary.validation_mode = 'warn';
+                    preNormalizedTrace.summary.validation_errors = result.errorCount;
+                    if (result.errorCount > 0) {
+                        traceWarnings.push(result.warning);
+                    }
+                }
+            }
+        }
+    }
+    // Step 3: Claim the step — adds to in_progress_steps under file lock.
+    let pendingRun;
+    try {
+        pendingRun = await store.claimStep(options.runId, options.command, definition);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError) {
+            if (err.code === 'STATE_STEP_ALREADY_CLAIMED') {
+                const freshRun = await store.get(options.runId).catch(() => run);
+                return {
+                    command: options.command,
+                    run_id: options.runId,
+                    run_version: freshRun.version,
+                    status: 'blocked',
+                    data: {},
+                    evidence: [],
+                    warnings: [],
+                    errors: [],
+                    agent_action: 'resolve_precondition',
+                    context_hint: `Step '${options.command}' was already claimed by another process.`,
+                    next_actions: buildNextActions(definition, freshRun),
+                    blocked_reason: {
+                        eligible_steps: findEligibleSteps(definition, freshRun),
+                        suggestion: `Step is already in progress. Wait for it to complete.`,
+                    },
+                };
+            }
+            return makeErrorEnvelope(options, run, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
+        return makeErrorEnvelope(options, run, new WorkflowError('Failed to claim step', {
+            code: 'ENGINE_STORE_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+        }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+    }
+    // Load workflow context once at run start — skip if already populated.
+    if (definition.workflow_context !== undefined &&
+        Object.keys(definition.workflow_context).length > 0 &&
+        pendingRun.workflow_context_snapshots === undefined) {
+        const contextSnapshots = await loadWorkflowContext(definition);
+        pendingRun = await store.update({
+            ...pendingRun,
+            workflow_context_snapshots: contextSnapshots,
+        });
+    }
+    // Step 4: Dispatch with retry and timeout.
+    const retryConfig = stepDef?.retry;
+    const maxAttempts = retryConfig?.max_attempts ?? 1;
+    const timeoutMs = stepDef?.timeout_seconds !== undefined ? stepDef.timeout_seconds * 1000 : undefined;
+    // Create a stable rate-limiter registry for all retry attempts of this step.
+    // Shared state ensures that a pause() triggered on attempt N is still in effect
+    // when the proactive acquire() runs on attempt N+1. When the caller provides an
+    // explicit registry, it is used directly (also enables cross-step coordination);
+    // otherwise a step-scoped fallback is created so rate limiting still works.
+    const rateLimiterRegistry = options.registry ?? new ExtensionRegistry();
+    let output = {};
+    let dispatchError = null;
+    let attemptsUsed = 0;
+    const allEvidence = [];
+    for (let attemptNum = 1; attemptNum <= maxAttempts; attemptNum++) {
+        attemptsUsed = attemptNum;
+        const startedAt = new Date();
+        let attemptOutput = {};
+        let attemptError = null;
+        let resolvedParams;
+        try {
+            const makeCall = (signal) => {
+                if (stepDef?.execution === 'auto' && stepDef.uses_service !== undefined) {
+                    return callAdapter(stepDef, definition, options, pendingRun, rateLimiterRegistry, signal);
+                }
+                else if (stepDef?.execution === 'auto' && stepDef.handler !== undefined) {
+                    return callHandler(stepDef, options, pendingRun, evidenceByStep, signal).then((result) => ({ output: result, resolvedParams: undefined }));
+                }
+                else {
+                    return options
+                        .dispatcher(options.command, options.input, pendingRun, signal)
+                        .then((result) => ({ output: result, resolvedParams: undefined }));
+                }
+            };
+            const callResult = timeoutMs !== undefined
+                ? await withTimeout((signal) => makeCall(signal), timeoutMs, options.command)
+                : await makeCall();
+            attemptOutput = callResult.output;
+            resolvedParams = callResult.resolvedParams;
+            if (resolvedParams !== undefined) {
+                inputTokenEstimate = Math.ceil(JSON.stringify(resolvedParams).length / 4);
+            }
+        }
+        catch (err) {
+            if (err instanceof WorkflowError) {
+                attemptError = err;
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                attemptError = new WorkflowError(`Dispatcher failed: ${message}`, {
+                    code: 'ENGINE_INTERNAL',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                    stepId: options.command,
+                });
+            }
+        }
+        const completedAt = new Date();
+        const profile = stepDef?.agent_profile;
+        const profileData = profile !== undefined ? definition.resolved_profiles?.[profile] : undefined;
+        const baseSnap = captureEvidence({
+            stepId: options.command,
+            startedAt,
+            completedAt,
+            input: options.input,
+            output: attemptOutput,
+            ...(attemptError !== null ? { error: attemptError.message } : {}),
+            diagnostics: {
+                input_token_estimate: inputTokenEstimate,
+                precondition_trace: preconditionTrace,
+            },
+            ...(profileData !== undefined
+                ? { agentProfile: profile, agentProfileHash: profileData.content_hash }
+                : {}),
+            ...(resolvedParams !== undefined ? { resolvedParams } : {}),
+            ...(options.stepMeta?.toolCalls !== undefined
+                ? { toolCalls: options.stepMeta.toolCalls }
+                : {}),
+            // Gate trace to agent steps only — drop silently for auto/adapter/handler steps.
+            // When pre-normalized (WAL merge + schema validation ran), pass the pre-normalized
+            // result to avoid double normalization. Also handle WAL-only case (options.trace may
+            // be undefined while walEntries contributed entries via preNormalizedTrace).
+            ...(stepDef?.execution === 'agent' && (options.trace !== undefined || walEntries.length > 0)
+                ? preNormalizedTrace !== undefined
+                    ? { normalizedTrace: preNormalizedTrace }
+                    : { trace: options.trace ?? [] }
+                : {}),
+        });
+        const snap = retryConfig !== undefined ? { ...baseSnap, attempt: attemptNum } : baseSnap;
+        allEvidence.push(snap);
+        if (attemptError === null) {
+            output = attemptOutput;
+            dispatchError = null;
+            break;
+        }
+        dispatchError = attemptError;
+        const willRetry = retryConfig !== undefined && attemptError.retryable && attemptNum < maxAttempts;
+        if (willRetry) {
+            const baseBackoff = computeBackoff(retryConfig, attemptNum);
+            const retryAfterMs = attemptError instanceof WorkflowError && attemptError.retry_after !== undefined
+                ? attemptError.retry_after * 1000
+                : 0;
+            await delayMs(Math.max(baseBackoff, retryAfterMs));
+        }
+        else {
+            break;
+        }
+    }
+    if (dispatchError !== null && retryConfig !== undefined && attemptsUsed === maxAttempts) {
+        const lastError = dispatchError;
+        dispatchError = new WorkflowError(`Step '${options.command}' failed after ${attemptsUsed} attempts`, {
+            code: 'STEP_RETRY_EXHAUSTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+            details: {
+                stepName: options.command,
+                attempts: attemptsUsed,
+                lastError: lastError.message,
+                ...(lastError.retry_after !== undefined ? { retry_after: lastError.retry_after } : {}),
+            },
+        });
+    }
+    // Step 5: Handle dispatch failure — move step to failed_steps.
+    if (dispatchError !== null) {
+        // Pure in-memory derivations — no I/O, no try required.
+        const afterFail = {
+            ...pendingRun,
+            in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+            failed_steps: [...pendingRun.failed_steps, options.command],
+        };
+        // Propagate skips: mark steps whose trigger_rule can never be satisfied after this failure.
+        const withSkippedFail = {
+            ...afterFail,
+            skipped_steps: propagateSkips(afterFail, definition),
+        };
+        // A run is terminal when all steps are settled OR when no step will ever become
+        // eligible again (safety net for when-condition edge cases not covered by propagateSkips).
+        const isComplete = isWorkflowComplete(withSkippedFail, definition) ||
+            (withSkippedFail.in_progress_steps.length === 0 &&
+                findEligibleSteps(definition, withSkippedFail).length === 0);
+        const failedRun = {
+            ...withSkippedFail,
+            evidence: [...pendingRun.evidence, ...allEvidence],
+            terminal_state: isComplete,
+            ...(isComplete
+                ? { terminal_reason: `Step '${options.command}' failed: ${dispatchError.message}` }
+                : {}),
+        };
+        // Persist run state and WAL cleanup in separate try/catch blocks so a WAL deletion
+        // failure does not mask a successful store.update.
+        let persistedRun;
+        let storeCleanupWarning;
+        try {
+            persistedRun = await store.update(failedRun);
+        }
+        catch (storeErr) {
+            storeCleanupWarning = `Failed to persist step failure: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
+        }
+        let walCleanupWarning;
+        try {
+            // Delete WAL after run state is written for failure — entries are now in evidence.
+            await options.traceBufferStore?.delete(options.runId, options.command);
+        }
+        catch (walErr) {
+            walCleanupWarning = `Failed to clean up trace buffer after step failure: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
+        }
+        // Derive the agent_action from the error semantics and run termination state.
+        //
+        // Non-terminal 'stop' errors (e.g. auth failure with a recovery branch) are surfaced
+        // as 'report_to_user' so the agent knows recovery steps are available. Terminal runs
+        // stay 'stop' — no further progress is possible.
+        //
+        // 'provide_input' and 'resolve_precondition' both imply "retry the same command" which
+        // is impossible once a step is in failed_steps; translate both to 'report_to_user'.
+        const effectiveAction = resolvePostDispatchAgentAction(dispatchError, (persistedRun ?? failedRun).terminal_state);
+        // Mirror makeErrorEnvelope: populate next_actions for any action other than 'stop',
+        // but only when store.update succeeded (inconsistent state → no reliable next_actions).
+        let nextActions = [];
+        if (effectiveAction !== 'stop' && storeCleanupWarning === undefined) {
+            try {
+                nextActions = buildNextActions(definition, persistedRun ?? failedRun);
+            }
+            catch {
+                // buildNextActions can throw for unresolvable template references; fall back to [].
+            }
+        }
+        const contextHint = effectiveAction === 'stop'
+            ? `Step '${options.command}' failed. Run is terminated.`
+            : effectiveAction === 'wait_and_proceed'
+                ? `Step '${options.command}' was rate-limited. Wait ${dispatchError.retry_after !== undefined ? `${dispatchError.retry_after} second(s)` : 'a moment'} then follow next_actions — no human intervention required.`
+                : effectiveAction === 'wait_for_human'
+                    ? `Step '${options.command}' failed due to external service unavailability. Wait for service recovery, then proceed with the steps in next_actions.`
+                    : `Step '${options.command}' failed. ${isComplete ? 'Run is terminated.' : 'Recovery steps are available in next_actions.'}`;
+        return {
+            command: options.command,
+            run_id: options.runId,
+            run_version: (persistedRun ?? failedRun).version,
+            status: 'error',
+            data: {},
+            evidence: allEvidence,
+            warnings: mergeWarnings(traceWarnings, storeCleanupWarning ?? walCleanupWarning),
+            errors: [dispatchError.message],
+            agent_action: effectiveAction,
+            ...(dispatchError.retry_after !== undefined
+                ? { retry_after: dispatchError.retry_after }
+                : {}),
+            context_hint: contextHint,
+            next_actions: nextActions,
+        };
+    }
+    // Step 5b: Gate check — if trust requires human confirmation, open a gate and halt.
+    if (stepDef.trust === 'human_confirmed' || stepDef.trust === 'human_reviewed') {
+        const gate_id = crypto.randomUUID();
+        const choicesRaw = stepDef.gate?.choices ?? stepDef.input_schema?.properties?.['choice']?.enum;
+        const choices = Array.isArray(choicesRaw) ? choicesRaw : ['approve', 'reject'];
+        const step_name = options.command;
+        // Resolve gate.message if configured — fail-fast on unresolvable references.
+        const gateEvidenceCtxEarly = { ...evidenceByStep, [options.command]: output };
+        const wfCtxSpreadEarly = pendingRun.workflow_context_snapshots !== undefined
+            ? {
+                workflowContext: {
+                    snapshots: pendingRun.workflow_context_snapshots,
+                    wrapper: (definition.context_wrapper ?? 'xml'),
+                },
+            }
+            : {};
+        let resolvedGateMessage;
+        if (stepDef.gate?.message !== undefined) {
+            let raw;
+            try {
+                raw = renderTemplate(stepDef.gate.message, {
+                    evidenceByStep: gateEvidenceCtxEarly,
+                    runParams: run.params,
+                    ...wfCtxSpreadEarly,
+                }, { strict: true });
+            }
+            catch (err) {
+                if (err instanceof UnknownFilterError) {
+                    return makeErrorEnvelope(options, pendingRun, new WorkflowError(`gate.message uses unknown filter '${err.filterName}'`, {
+                        code: 'FILTER_UNKNOWN',
+                        category: 'ENGINE',
+                        agentAction: 'stop',
+                        retryable: false,
+                    }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+                }
+                throw err;
+            }
+            const unresolved = [...raw.matchAll(/\{\{\s*([\w.-]+)\s*\}\}/g)].map((m) => m[1]);
+            if (unresolved.length > 0) {
+                return makeErrorEnvelope(options, pendingRun, new WorkflowError(`gate.message has unresolvable references: ${unresolved.join(', ')}`, {
+                    code: 'GATE_MESSAGE_UNRESOLVABLE',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            resolvedGateMessage = raw;
+        }
+        const gateConfig = stepDef.gate;
+        let gateRun;
+        try {
+            gateRun = await store.update({
+                ...pendingRun,
+                // Step stays in in_progress_steps while gate is open — moved to completed on submit.
+                evidence: [...pendingRun.evidence, ...allEvidence],
+                pending_gate: {
+                    gate_id,
+                    step_name,
+                    preview: output,
+                    choices,
+                    opened_at: new Date().toISOString(),
+                    ...(gateConfig?.owner !== undefined ? { owner: gateConfig.owner } : {}),
+                    ...(resolvedGateMessage !== undefined ? { resolved_message: resolvedGateMessage } : {}),
+                    ...(gateConfig?.resolution_messages !== undefined
+                        ? { resolution_messages: gateConfig.resolution_messages }
+                        : {}),
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof WorkflowError) {
+                return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            return makeErrorEnvelope(options, pendingRun, new WorkflowError('Failed to open gate', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
+        // gate.display fallback chain: gate.message resolved → step.prompt resolved → absent
+        const resolvedGateDisplay = resolvedGateMessage !== undefined
+            ? resolvedGateMessage
+            : stepDef.prompt !== undefined
+                ? renderTemplate(stepDef.prompt, {
+                    evidenceByStep: gateEvidenceCtxEarly,
+                    runParams: run.params,
+                    ...wfCtxSpreadEarly,
+                })
+                : undefined;
+        const resolvedGateInstructions = stepDef.instructions !== undefined
+            ? renderTemplate(stepDef.instructions, {
+                evidenceByStep: gateEvidenceCtxEarly,
+                runParams: run.params,
+                ...wfCtxSpreadEarly,
+            })
+            : undefined;
+        const gateNextAction = {
+            instruction: {
+                tool: 'submit_human_response',
+                params: { run_id: options.runId, gate_id },
+                call_with: {
+                    run_id: options.runId,
+                    gate_id,
+                    choice: `<${choices.join('|')}>`,
+                },
+            },
+            human_readable: `Human review required for step '${options.command}'. Present gate.display to the user, wait for their choice from gate.response_spec.choices, then call submit_human_response.`,
+            orientation: `Run is paused at gate '${gate_id}'. Available choices: ${choices.join(', ')}.`,
+        };
+        return {
+            command: options.command,
+            run_id: options.runId,
+            run_version: gateRun.version,
+            status: 'confirm_required',
+            data: output,
+            evidence: allEvidence,
+            warnings: [...traceWarnings],
+            errors: [],
+            context_hint: `Run is paused at gate '${gate_id}'. Available choices: ${choices.join(', ')}.`,
+            next_actions: [gateNextAction],
+            gate: {
+                gate_id,
+                step_name,
+                preview: output,
+                choices,
+                ...(resolvedGateDisplay !== undefined ? { display: resolvedGateDisplay } : {}),
+                ...(resolvedGateInstructions !== undefined ? { agent_hint: resolvedGateInstructions } : {}),
+                response_spec: { choices },
+            },
+        };
+    }
+    // Step 6: Move step from in_progress to completed, compute terminal state.
+    const afterComplete = {
+        ...pendingRun,
+        in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
+        completed_steps: [...pendingRun.completed_steps, options.command],
+        evidence: [...pendingRun.evidence, ...allEvidence],
+    };
+    // Propagate skips: completing this step may make some downstream steps permanently ineligible
+    // (e.g. all_failed steps whose dep just succeeded, one_failed steps whose last unfailed dep just completed).
+    const withSkippedComplete = {
+        ...afterComplete,
+        skipped_steps: propagateSkips(afterComplete, definition),
+    };
+    // A run is terminal when all steps are settled OR when no step will ever become
+    // eligible again (safety net for when-condition routing not fully covered by propagateSkips).
+    const isComplete = isWorkflowComplete(withSkippedComplete, definition) ||
+        (withSkippedComplete.in_progress_steps.length === 0 &&
+            findEligibleSteps(definition, withSkippedComplete).length === 0);
+    const finalRun = {
+        ...withSkippedComplete,
+        terminal_state: isComplete,
+        ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
+    };
+    let savedRun;
+    try {
+        savedRun = await store.update(finalRun);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError) {
+            return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
+        const internal = new WorkflowError('Failed to persist run update', {
+            code: 'ENGINE_STORE_FAILED',
+            category: 'ENGINE',
+            agentAction: 'stop',
+            retryable: false,
+        });
+        return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+    }
+    // Delete WAL after successful run update — entries are now in evidence.
+    await options.traceBufferStore?.delete(options.runId, options.command);
+    // Step 7: Build and return ResponseEnvelope.
+    const nextActions = savedRun.terminal_state ? [] : buildNextActions(definition, savedRun);
+    const orientation = savedRun.terminal_state
+        ? `Run completed (phase: '${savedRun.run_phase}'). Call get_run_state with run_id '${options.runId}' to retrieve the full evidence record.`
+        : nextActions.length > 0
+            ? `Step '${options.command}' completed. ${nextActions.length} step(s) now available.`
+            : `Step '${options.command}' completed. Waiting for other steps to complete.`;
+    return {
+        command: options.command,
+        run_id: options.runId,
+        run_version: savedRun.version,
+        status: 'ok',
+        data: output,
+        evidence: allEvidence,
+        warnings: traceWarnings,
+        errors: [],
+        context_hint: orientation,
+        next_actions: nextActions,
+    };
+}
+/**
+ * Submits a human response for a gate-waiting run.
+ * Validates the gate_id and choice, then moves the step to completed_steps.
+ */
+export async function submitHumanResponse(store, definition, options) {
+    // 1. Load run.
+    let run;
+    try {
+        run = await store.get(options.runId);
+    }
+    catch (err) {
+        const e = err instanceof WorkflowError
+            ? err
+            : new WorkflowError('Failed to load run from store', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        return errorEnvelope('submit_gate', options.runId, 0, e);
+    }
+    // 2. Verify a gate is open.
+    if (run.pending_gate === undefined) {
+        return errorEnvelope('submit_gate', options.runId, run.version, new WorkflowError('Run is not waiting at a gate.', {
+            code: 'STATE_BLOCKED',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        }), `Run '${options.runId}' has no open gate (phase: '${run.run_phase}').`);
+    }
+    // 3. Verify gate_id.
+    if (run.pending_gate.gate_id !== options.gateId) {
+        return errorEnvelope('submit_gate', options.runId, run.version, new WorkflowError('Gate ID mismatch.', {
+            code: 'STATE_BLOCKED',
+            category: 'STATE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        }), `Gate ID mismatch on run '${options.runId}'.`);
+    }
+    // 4. Validate choice.
+    if (!run.pending_gate.choices.includes(options.choice)) {
+        const expected = run.pending_gate.choices.join(', ');
+        return errorEnvelope(run.pending_gate.step_name, options.runId, run.version, new WorkflowError(`Choice '${options.choice}' is not valid. Expected one of: ${expected}`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'report_to_user',
+            retryable: false,
+        }), `Invalid choice '${options.choice}' for gate '${run.pending_gate.step_name}'.`);
+    }
+    // 5. Record gate response evidence and move step to completed_steps.
+    const gateStepName = run.pending_gate.step_name;
+    const respondedAt = new Date();
+    const gateEvidence = captureEvidence({
+        stepId: gateStepName,
+        startedAt: new Date(run.pending_gate.opened_at),
+        completedAt: respondedAt,
+        input: { choice: options.choice },
+        output: { ...run.pending_gate.preview, choice: options.choice },
+    });
+    const gateSnapshot = {
+        ...gateEvidence,
+        kind: 'gate_response',
+        ...(run.pending_gate.resolved_message !== undefined
+            ? { gate_message: run.pending_gate.resolved_message }
+            : {}),
+    };
+    const { pending_gate: _pg, terminal_reason: _tr, ...rest } = run;
+    const afterGate = {
+        ...rest,
+        in_progress_steps: rest.in_progress_steps.filter((s) => s !== gateStepName),
+        completed_steps: [...rest.completed_steps, gateStepName],
+        evidence: [...rest.evidence, gateSnapshot],
+    };
+    // Propagate skips in case resolving the gate completes a dep that makes
+    // some downstream trigger_rules permanently unsatisfiable.
+    const withSkippedGate = {
+        ...afterGate,
+        skipped_steps: propagateSkips(afterGate, definition),
+    };
+    // A run is terminal when all steps are settled OR when no step will ever become
+    // eligible again (safety net for when-condition routing not fully covered by propagateSkips).
+    const isComplete = isWorkflowComplete(withSkippedGate, definition) ||
+        (withSkippedGate.in_progress_steps.length === 0 &&
+            findEligibleSteps(definition, withSkippedGate).length === 0);
+    const finalRun = {
+        ...withSkippedGate,
+        terminal_state: isComplete,
+        ...(isComplete ? { terminal_reason: `Workflow completed.` } : {}),
+    };
+    let savedRun;
+    try {
+        savedRun = await store.update(finalRun);
+    }
+    catch (err) {
+        const e = err instanceof WorkflowError
+            ? err
+            : new WorkflowError('Failed to persist gate response', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        return errorEnvelope(gateStepName, options.runId, run.version, e, `Failed to persist gate response.`);
+    }
+    // 6. Build response.
+    const data = { ...run.pending_gate.preview, choice: options.choice };
+    const nextActions = savedRun.terminal_state ? [] : buildNextActions(definition, savedRun);
+    const orientation = savedRun.terminal_state
+        ? `Run completed (phase: '${savedRun.run_phase}'). Call get_run_state with run_id '${options.runId}' to retrieve the full evidence record.`
+        : `Gate '${gateStepName}' resolved with choice '${options.choice}'. ${nextActions.length} step(s) now available.`;
+    return {
+        command: gateStepName,
+        run_id: options.runId,
+        run_version: savedRun.version,
+        status: 'ok',
+        data,
+        evidence: [],
+        warnings: [],
+        errors: [],
+        context_hint: orientation,
+        next_actions: nextActions,
+    };
+}
+const MAX_CHAIN_DEPTH = 50;
+async function executeChainInternal(store, definition, options, depth, chainedSteps) {
+    if (depth > MAX_CHAIN_DEPTH) {
+        return {
+            command: options.command,
+            run_id: options.runId,
+            run_version: 0,
+            status: 'error',
+            data: {},
+            evidence: [],
+            warnings: [],
+            errors: [
+                'Auto-execution chain exceeded maximum depth (50). Possible cycle in workflow definition.',
+            ],
+            agent_action: 'stop',
+            context_hint: `Auto-step chain exceeded depth limit (50) for run '${options.runId}'.`,
+            next_actions: [],
+        };
+    }
+    const result = await executeStep(store, definition, options);
+    // Stop chaining on any non-ok result.
+    if (result.status !== 'ok') {
+        return result;
+    }
+    // Load the current run to determine what comes next.
+    let run;
+    try {
+        run = await store.get(options.runId);
+    }
+    catch {
+        return result;
+    }
+    // Record this auto step in the accumulator.
+    if (definition.steps[options.command]?.execution === 'auto') {
+        chainedSteps.push({ step: options.command, run_phase: run.run_phase });
+    }
+    if (run.terminal_state || run.pending_gate !== undefined) {
+        return result;
+    }
+    // Find the next eligible auto step and chain into it.
+    const eligible = findEligibleSteps(definition, run);
+    const nextAutoStep = eligible.find((name) => definition.steps[name]?.execution === 'auto');
+    if (nextAutoStep === undefined) {
+        // Only agent steps or nothing — stop chain, return with latest next_actions.
+        return result;
+    }
+    return executeChainInternal(store, definition, { ...options, command: nextAutoStep, input: {} }, depth + 1, chainedSteps);
+}
+/**
+ * Executes a step and automatically chains into subsequent `execution: auto` steps.
+ * Stops at agent steps, gate steps (returning confirm_required), errors, or terminal state.
+ * Returns next_actions containing all eligible agent steps when the auto chain exhausts.
+ */
+export async function executeChain(store, definition, options) {
+    const effectiveOptions = {
+        ...options,
+        registry: options.registry ?? createDefaultRegistry(),
+    };
+    const chained = [];
+    const result = await executeChainInternal(store, definition, effectiveOptions, 0, chained);
+    const envelope = { ...result, command: options.command };
+    return chained.length > 0 ? { ...envelope, chained_auto_steps: chained } : envelope;
+}
+// Re-export TERMINAL_PHASES so existing importers via execution-loop.js still resolve.
+export { TERMINAL_PHASES as TERMINAL_STATES };
+//# sourceMappingURL=execution-loop.js.map