@marktoflow/core 2.0.2 → 2.0.4

package/dist/engine.js

@@ -1,279 +1,34 @@
 /**
  * Workflow Execution Engine for marktoflow v2.0
  *
- * Executes workflow steps with retry logic, variable resolution,
- * and SDK invocation.
+ * Thin orchestrator that delegates to focused modules:
+ * - engine/control-flow.ts — if, switch, for-each, while, map, filter, reduce, parallel, try, script, wait, merge
+ * - engine/retry.ts — RetryPolicy, CircuitBreaker
+ * - engine/conditions.ts — condition evaluation
+ * - engine/variable-resolution.ts — template and variable resolution
+ * - engine/subworkflow.ts — sub-workflow and sub-agent execution
+ * - engine/types.ts — shared type definitions
+ * - utils/duration.ts — duration parsing
+ * - utils/errors.ts — error conversion utilities
  */
 import { StepStatus, WorkflowStatus, createExecutionContext, createStepResult, isActionStep, isSubWorkflowStep, isIfStep, isSwitchStep, isForEachStep, isWhileStep, isMapStep, isFilterStep, isReduceStep, isParallelStep, isTryStep, isScriptStep, isWaitStep, isMergeStep, } from './models.js';
 import { mergePermissions, toSecurityPolicy, } from './permissions.js';
 import { loadPromptFile, resolvePromptTemplate, validatePromptInputs, } from './prompt-loader.js';
 import { DEFAULT_FAILOVER_CONFIG, AgentHealthTracker, FailoverReason, } from './failover.js';
 import { parseFile } from './parser.js';
-import { resolve, dirname } from 'node:path';
+import { resolve } from 'node:path';
 import { executeBuiltInOperation, isBuiltInOperation } from './built-in-operations.js';
-import { renderTemplate } from './template-engine.js';
-import { executeScriptAsync } from './script-executor.js';
-// ============================================================================
-// Helper Functions
-// ============================================================================
-/**
- * Parse a duration string like "2h", "30m", "5s", "100ms" into milliseconds.
- */
-function parseDuration(duration) {
-    const match = duration.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
-    if (!match) {
-        const asNum = Number(duration);
-        if (!isNaN(asNum))
-            return asNum; // Treat bare numbers as milliseconds
-        throw new Error(`Invalid duration format: "${duration}". Use format like "2h", "30m", "5s", "100ms"`);
-    }
-    const value = parseFloat(match[1]);
-    const unit = match[2].toLowerCase();
-    switch (unit) {
-        case 'ms': return value;
-        case 's': return value * 1000;
-        case 'm': return value * 60 * 1000;
-        case 'h': return value * 60 * 60 * 1000;
-        case 'd': return value * 24 * 60 * 60 * 1000;
-        default: return value;
-    }
-}
-/**
- * Convert error to string for display/logging
- */
-function errorToString(error) {
-    if (!error)
-        return 'Unknown error';
-    if (typeof error === 'string')
-        return error;
-    if (error instanceof Error)
-        return error.message;
-    try {
-        return JSON.stringify(error);
-    }
-    catch {
-        return String(error);
-    }
-}
-/**
- * Get a field value from an object by key path.
- */
-function getField(item, field) {
-    if (!item || typeof item !== 'object')
-        return undefined;
-    const parts = field.split('.');
-    let current = item;
-    for (const part of parts) {
-        if (!current || typeof current !== 'object')
-            return undefined;
-        current = current[part];
-    }
-    return current;
-}
-// ============================================================================
-// Retry Policy
-// ============================================================================
-export class RetryPolicy {
-    maxRetries;
-    baseDelay;
-    maxDelay;
-    exponentialBase;
-    jitter;
-    constructor(maxRetries = 3, baseDelay = 1000, maxDelay = 30000, exponentialBase = 2, jitter = 0.1) {
-        this.maxRetries = maxRetries;
-        this.baseDelay = baseDelay;
-        this.maxDelay = maxDelay;
-        this.exponentialBase = exponentialBase;
-        this.jitter = jitter;
-    }
-    /**
-     * Calculate delay for a given retry attempt.
-     */
-    getDelay(attempt) {
-        const exponentialDelay = this.baseDelay * Math.pow(this.exponentialBase, attempt);
-        const clampedDelay = Math.min(exponentialDelay, this.maxDelay);
-        // Add jitter
-        const jitterAmount = clampedDelay * this.jitter * (Math.random() * 2 - 1);
-        return Math.max(0, clampedDelay + jitterAmount);
-    }
-}
-export class CircuitBreaker {
-    failureThreshold;
-    recoveryTimeout;
-    halfOpenMaxCalls;
-    state = 'CLOSED';
-    failures = 0;
-    lastFailureTime = 0;
-    halfOpenCalls = 0;
-    constructor(failureThreshold = 5, recoveryTimeout = 30000, halfOpenMaxCalls = 3) {
-        this.failureThreshold = failureThreshold;
-        this.recoveryTimeout = recoveryTimeout;
-        this.halfOpenMaxCalls = halfOpenMaxCalls;
-    }
-    canExecute() {
-        if (this.state === 'CLOSED') {
-            return true;
-        }
-        if (this.state === 'OPEN') {
-            const timeSinceFailure = Date.now() - this.lastFailureTime;
-            if (timeSinceFailure >= this.recoveryTimeout) {
-                this.state = 'HALF_OPEN';
-                this.halfOpenCalls = 0;
-                return true;
-            }
-            return false;
-        }
-        // HALF_OPEN
-        return this.halfOpenCalls < this.halfOpenMaxCalls;
-    }
-    recordSuccess() {
-        this.failures = 0;
-        this.state = 'CLOSED';
-    }
-    recordFailure() {
-        this.failures++;
-        this.lastFailureTime = Date.now();
-        if (this.state === 'HALF_OPEN') {
-            this.state = 'OPEN';
-        }
-        else if (this.failures >= this.failureThreshold) {
-            this.state = 'OPEN';
-        }
-    }
-    getState() {
-        return this.state;
-    }
-    reset() {
-        this.state = 'CLOSED';
-        this.failures = 0;
-        this.halfOpenCalls = 0;
-    }
-}
-// ============================================================================
-// Variable Resolution
-// ============================================================================
-/**
- * Resolve template variables in a value.
- * Supports {{variable}}, {{inputs.name}}, and Nunjucks filters.
- *
- * Uses Nunjucks as the template engine with:
- * - Legacy regex operator support (=~, !~, //) converted to filters
- * - Custom filters for string, array, object, date operations
- * - Jinja2-style control flow ({% for %}, {% if %}, etc.)
- */
-export function resolveTemplates(value, context) {
-    if (typeof value === 'string') {
-        // Build the template context with all available variables
-        // Spread inputs first, then variables (variables override inputs if same key)
-        // Also keep inputs accessible via inputs.* for explicit access
-        const templateContext = {
-            ...context.inputs, // Spread inputs at root level for direct access ({{ path }})
-            ...context.variables, // Variables override inputs if same key
-            inputs: context.inputs, // Also keep inputs accessible as inputs.*
-        };
-        // Use the new Nunjucks-based template engine with legacy syntax support
-        return renderTemplate(value, templateContext);
-    }
-    if (Array.isArray(value)) {
-        return value.map((v) => resolveTemplates(v, context));
-    }
-    if (value && typeof value === 'object') {
-        const result = {};
-        for (const [k, v] of Object.entries(value)) {
-            result[k] = resolveTemplates(v, context);
-        }
-        return result;
-    }
-    return value;
-}
-/**
- * Resolve a variable path from context.
- * First checks inputs.*, then variables, then stepMetadata, then direct context properties.
- * Exported to allow access from condition evaluation.
- */
-export function resolveVariablePath(path, context) {
-    // Handle inputs.* prefix
-    if (path.startsWith('inputs.')) {
-        const inputPath = path.slice(7); // Remove 'inputs.'
-        return getNestedValue(context.inputs, inputPath);
-    }
-    // Check variables first (most common case)
-    const fromVars = getNestedValue(context.variables, path);
-    if (fromVars !== undefined) {
-        return fromVars;
-    }
-    // Check inputs (for bare variable names like "value" instead of "inputs.value")
-    const fromInputs = getNestedValue(context.inputs, path);
-    if (fromInputs !== undefined) {
-        return fromInputs;
-    }
-    // Check step metadata (for status checks like: step_id.status)
-    const fromStepMeta = getNestedValue(context.stepMetadata, path);
-    if (fromStepMeta !== undefined) {
-        return fromStepMeta;
-    }
-    // Fall back to direct context access
-    return getNestedValue(context, path);
-}
-/**
- * Get a nested value from an object using dot notation and array indexing.
- * Supports paths like: "user.name", "items[0].name", "data.users[1].email"
- */
-function getNestedValue(obj, path) {
-    if (obj === null || obj === undefined) {
-        return undefined;
-    }
-    // Parse path into parts, handling both dot notation and array indexing
-    // Convert "a.b[0].c[1]" into ["a", "b", "0", "c", "1"]
-    const parts = [];
-    let current = '';
-    for (let i = 0; i < path.length; i++) {
-        const char = path[i];
-        if (char === '.') {
-            if (current) {
-                parts.push(current);
-                current = '';
-            }
-        }
-        else if (char === '[') {
-            if (current) {
-                parts.push(current);
-                current = '';
-            }
-        }
-        else if (char === ']') {
-            if (current) {
-                parts.push(current);
-                current = '';
-            }
-        }
-        else {
-            current += char;
-        }
-    }
-    if (current) {
-        parts.push(current);
-    }
-    // Traverse the object using the parsed parts
-    let result = obj;
-    for (const part of parts) {
-        if (result === null || result === undefined) {
-            return undefined;
-        }
-        // Check if part is a number (array index)
-        const index = Number(part);
-        if (!isNaN(index) && Array.isArray(result)) {
-            result = result[index];
-        }
-        else if (typeof result === 'object') {
-            result = result[part];
-        }
-        else {
-            return undefined;
-        }
-    }
-    return result;
-}
+import { executeParallelOperation, isParallelOperation } from './parallel.js';
+// Engine sub-modules
+import { RetryPolicy, CircuitBreaker } from './engine/retry.js';
+import { evaluateConditions } from './engine/conditions.js';
+import { resolveTemplates } from './engine/variable-resolution.js';
+import { executeIfStep, executeSwitchStep, executeForEachStep, executeWhileStep, executeMapStep, executeFilterStep, executeReduceStep, executeParallelStep, executeTryStep, executeScriptStep, executeWaitStep, executeMergeStep, } from './engine/control-flow.js';
+import { executeSubWorkflow, executeSubWorkflowWithAgent, } from './engine/subworkflow.js';
+import { errorToString } from './utils/errors.js';
+// Re-export types and classes for backward compatibility
+export { RetryPolicy, CircuitBreaker } from './engine/retry.js';
+export { resolveTemplates, resolveVariablePath } from './engine/variable-resolution.js';
 export class WorkflowEngine {
     config;
     retryPolicy;
@@ -284,15 +39,15 @@ export class WorkflowEngine {
     failoverConfig;
     healthTracker;
     failoverEvents = [];
-    workflowPath; // Base path for resolving sub-workflows (public for CLI state tracking)
-    workflowPermissions; // Workflow-level permissions
-    promptCache = new Map(); // Cache for loaded prompts
+    workflowPath;
+    workflowPermissions;
+    promptCache = new Map();
     constructor(config = {}, events = {}, stateStore) {
         this.config = {
-            defaultTimeout: config.defaultTimeout ?? 60000,
-            maxRetries: config.maxRetries ?? 3,
-            retryBaseDelay: config.retryBaseDelay ?? 1000,
-            retryMaxDelay: config.retryMaxDelay ?? 30000,
+            defaultTimeout: config.defaultTimeout ?? (process.env.MARKTOFLOW_TIMEOUT ? parseInt(process.env.MARKTOFLOW_TIMEOUT, 10) : 60000),
+            maxRetries: config.maxRetries ?? (process.env.MARKTOFLOW_MAX_RETRIES ? parseInt(process.env.MARKTOFLOW_MAX_RETRIES, 10) : 3),
+            retryBaseDelay: config.retryBaseDelay ?? (process.env.MARKTOFLOW_RETRY_BASE_DELAY ? parseInt(process.env.MARKTOFLOW_RETRY_BASE_DELAY, 10) : 1000),
+            retryMaxDelay: config.retryMaxDelay ?? (process.env.MARKTOFLOW_RETRY_MAX_DELAY ? parseInt(process.env.MARKTOFLOW_RETRY_MAX_DELAY, 10) : 30000),
             defaultAgent: config.defaultAgent,
             defaultModel: config.defaultModel,
         };
@@ -303,54 +58,62 @@ export class WorkflowEngine {
         this.failoverConfig = { ...DEFAULT_FAILOVER_CONFIG, ...(config.failoverConfig ?? {}) };
         this.healthTracker = config.healthTracker ?? new AgentHealthTracker();
     }
+    // ============================================================================
+    // Step Dispatcher
+    // ============================================================================
     /**
-     * Execute a single step - dispatcher to specialized execution methods.
+     * Execute a single step - dispatches to specialized execution methods.
      */
     async executeStep(step, context, sdkRegistry, stepExecutor) {
         // Check conditions first (applies to all step types)
-        if (step.conditions && !this.evaluateConditions(step.conditions, context)) {
+        if (step.conditions && !evaluateConditions(step.conditions, context)) {
             return createStepResult(step.id, StepStatus.SKIPPED, null, new Date());
         }
+        // Bind the dispatcher for recursive step execution
+        const dispatch = (s, c, sr, se) => this.executeStep(s, c, sr, se);
         // Dispatch to specialized execution method based on step type
         if (isIfStep(step)) {
-            return this.executeIfStep(step, context, sdkRegistry, stepExecutor);
+            return executeIfStep(step, context, sdkRegistry, stepExecutor, dispatch);
         }
         if (isSwitchStep(step)) {
-            return this.executeSwitchStep(step, context, sdkRegistry, stepExecutor);
+            return executeSwitchStep(step, context, sdkRegistry, stepExecutor, dispatch);
         }
         if (isForEachStep(step)) {
-            return this.executeForEachStep(step, context, sdkRegistry, stepExecutor);
+            return executeForEachStep(step, context, sdkRegistry, stepExecutor, dispatch);
         }
         if (isWhileStep(step)) {
-            return this.executeWhileStep(step, context, sdkRegistry, stepExecutor);
+            return executeWhileStep(step, context, sdkRegistry, stepExecutor, dispatch);
         }
         if (isMapStep(step)) {
-            return this.executeMapStep(step, context, sdkRegistry, stepExecutor);
+            return executeMapStep(step, context);
         }
         if (isFilterStep(step)) {
-            return this.executeFilterStep(step, context, sdkRegistry, stepExecutor);
+            return executeFilterStep(step, context);
         }
         if (isReduceStep(step)) {
-            return this.executeReduceStep(step, context, sdkRegistry, stepExecutor);
+            return executeReduceStep(step, context);
         }
         if (isParallelStep(step)) {
-            return this.executeParallelStep(step, context, sdkRegistry, stepExecutor);
+            return executeParallelStep(step, context, sdkRegistry, stepExecutor, dispatch, (c) => this.cloneContext(c), (main, branch, id) => this.mergeContexts(main, branch, id), (promises, limit) => this.executeConcurrentlyWithLimit(promises, limit));
         }
         if (isTryStep(step)) {
-            return this.executeTryStep(step, context, sdkRegistry, stepExecutor);
+            return executeTryStep(step, context, sdkRegistry, stepExecutor, dispatch);
         }
         if (isScriptStep(step)) {
-            return this.executeScriptStep(step, context);
+            return executeScriptStep(step, context);
         }
         if (isWaitStep(step)) {
-            return this.executeWaitStep(step, context);
+            return executeWaitStep(step, context, this.stateStore);
         }
         if (isMergeStep(step)) {
-            return this.executeMergeStep(step, context);
+            return executeMergeStep(step, context);
         }
         // Default: action or workflow step
         return this.executeStepWithFailover(step, context, sdkRegistry, stepExecutor);
     }
+    // ============================================================================
+    // Workflow Execution
+    // ============================================================================
     /**
      * Execute a workflow.
      */
@@ -389,11 +152,9 @@ export class WorkflowEngine {
             for (let i = 0; i < workflow.steps.length; i++) {
                 const step = workflow.steps[i];
                 context.currentStepIndex = i;
-                // Execute step using dispatcher
                 const result = await this.executeStep(step, context, sdkRegistry, stepExecutor);
                 stepResults.push(result);
-                // Store step metadata (status, error, etc.) in separate field for condition evaluation
-                // This allows conditions like: step_id.status == 'failed'
+                // Store step metadata for condition evaluation
                 context.stepMetadata[step.id] = {
                     status: result.status.toLowerCase(),
                     retryCount: result.retryCount,
@@ -414,7 +175,6 @@ export class WorkflowEngine {
                 }
                 // Handle failure
                 if (result.status === StepStatus.FAILED) {
-                    // Get error action from step if it has error handling
                     let errorAction = 'stop';
                     if ('errorHandling' in step && step.errorHandling?.action) {
                         errorAction = step.errorHandling.action;
@@ -426,7 +186,6 @@ export class WorkflowEngine {
                         this.events.onWorkflowComplete?.(workflow, workflowResult);
                         return workflowResult;
                     }
-                    // 'continue' - keep going
                     if (errorAction === 'rollback') {
                         if (this.rollbackRegistry) {
                             await this.rollbackRegistry.rollbackAllAsync({
@@ -443,7 +202,6 @@ export class WorkflowEngine {
                     }
                 }
             }
-            // Determine final status
             context.status = WorkflowStatus.COMPLETED;
         }
         catch (error) {
@@ -472,19 +230,11 @@ export class WorkflowEngine {
     }
     /**
      * Resume a paused execution (e.g., after form submission).
-     *
-     * @param runId - The execution run ID
-     * @param stepId - The step ID that was waiting
-     * @param resumeData - Data from the resume action (e.g., form submission)
-     * @param sdkRegistry - SDK registry for step execution
-     * @param stepExecutor - Step executor function
-     * @returns Workflow result from resumed execution
      */
     async resumeExecution(runId, stepId, resumeData, sdkRegistry, stepExecutor) {
         if (!this.stateStore) {
             throw new Error('Cannot resume execution: StateStore not configured');
         }
-        // Load execution from state store
         const execution = this.stateStore.getExecution(runId);
         if (!execution) {
             throw new Error(`Execution ${runId} not found`);
@@ -492,10 +242,8 @@ export class WorkflowEngine {
         if (execution.status !== WorkflowStatus.RUNNING) {
             throw new Error(`Cannot resume execution ${runId}: status is ${execution.status}`);
         }
-        // Load workflow
         const { workflow } = await parseFile(execution.workflowPath);
         this.workflowPath = execution.workflowPath;
-        // Find the step that was waiting
         const stepIndex = workflow.steps.findIndex(s => s.id === stepId);
         if (stepIndex === -1) {
             throw new Error(`Step ${stepId} not found in workflow`);
@@ -511,16 +259,13 @@ export class WorkflowEngine {
             const checkpoint = checkpoints.find(cp => cp.stepIndex === i);
             if (checkpoint) {
                 const step = workflow.steps[i];
-                // Recreate step result
                 const result = createStepResult(step.id, checkpoint.status, checkpoint.outputs, checkpoint.startedAt, checkpoint.retryCount, checkpoint.error || undefined);
                 stepResults.push(result);
-                // Restore step metadata
                 context.stepMetadata[step.id] = {
                     status: checkpoint.status.toLowerCase(),
                     retryCount: checkpoint.retryCount,
                     ...(checkpoint.error ? { error: checkpoint.error } : {}),
                 };
-                // Restore output variable
                 if (step.outputVariable && checkpoint.status === StepStatus.COMPLETED) {
                     context.variables[step.outputVariable] = checkpoint.outputs;
                 }
@@ -602,273 +347,26 @@ export class WorkflowEngine {
     }
     /**
      * Execute a workflow from a file.
-     * This method automatically sets the workflow path for resolving sub-workflows.
      */
     async executeFile(workflowPath, inputs = {}, sdkRegistry, stepExecutor) {
-        // Parse the workflow file
         const { workflow } = await parseFile(workflowPath);
-        // Set the workflow path for sub-workflow resolution
         this.workflowPath = resolve(workflowPath);
-        // Execute the workflow
         return this.execute(workflow, inputs, sdkRegistry, stepExecutor);
     }
     getFailoverHistory() {
         return [...this.failoverEvents];
     }
-    /**
-     * Execute a sub-workflow.
-     */
-    async executeSubWorkflow(step, context, sdkRegistry, stepExecutor) {
-        if (!isSubWorkflowStep(step)) {
-            throw new Error(`Step ${step.id} is not a workflow step`);
-        }
-        // Resolve the sub-workflow path relative to the parent workflow
-        const subWorkflowPath = this.workflowPath
-            ? resolve(dirname(this.workflowPath), step.workflow)
-            : resolve(step.workflow);
-        // Parse the sub-workflow
-        const { workflow: subWorkflow } = await parseFile(subWorkflowPath);
-        // Resolve inputs for the sub-workflow
-        const resolvedInputs = resolveTemplates(step.inputs, context);
-        // Create a new engine instance for the sub-workflow with the same configuration
-        const subEngineConfig = {
-            defaultTimeout: this.config.defaultTimeout,
-            maxRetries: this.config.maxRetries,
-            retryBaseDelay: this.config.retryBaseDelay,
-            retryMaxDelay: this.config.retryMaxDelay,
-            failoverConfig: this.failoverConfig,
-            healthTracker: this.healthTracker,
-        };
-        if (this.rollbackRegistry) {
-            subEngineConfig.rollbackRegistry = this.rollbackRegistry;
-        }
-        const subEngine = new WorkflowEngine(subEngineConfig, this.events, this.stateStore);
-        // Set the base path for the sub-workflow
-        subEngine.workflowPath = subWorkflowPath;
-        // Execute the sub-workflow
-        const result = await subEngine.execute(subWorkflow, resolvedInputs, sdkRegistry, stepExecutor);
-        // Check if sub-workflow failed
-        if (result.status === WorkflowStatus.FAILED) {
-            throw new Error(result.error || 'Sub-workflow execution failed');
-        }
-        // Return the sub-workflow output
-        return result.output;
-    }
-    /**
-     * Execute a sub-workflow using an AI sub-agent.
-     * The agent interprets the workflow and executes it autonomously.
-     */
-    async executeSubWorkflowWithAgent(step, context, sdkRegistry, stepExecutor) {
-        // Resolve the sub-workflow path
-        const subWorkflowPath = this.workflowPath
-            ? resolve(dirname(this.workflowPath), step.workflow)
-            : resolve(step.workflow);
-        // Read the workflow file content
-        const { readFile } = await import('node:fs/promises');
-        const workflowContent = await readFile(subWorkflowPath, 'utf-8');
-        // Resolve inputs for the sub-workflow
-        const resolvedInputs = resolveTemplates(step.inputs, context);
-        // Get subagent configuration
-        const subagentConfig = step.subagentConfig || {};
-        const model = subagentConfig.model || step.model || this.config.defaultModel;
-        const maxTurns = subagentConfig.maxTurns || 10;
-        const systemPrompt = subagentConfig.systemPrompt || this.buildDefaultSubagentSystemPrompt();
-        const tools = subagentConfig.tools || ['Read', 'Write', 'Bash', 'Glob', 'Grep'];
-        // Build the prompt for the agent
-        const agentPrompt = this.buildSubagentPrompt(workflowContent, resolvedInputs, tools);
-        // Determine the agent action to use
-        const agentName = step.agent || this.config.defaultAgent || 'agent';
-        const agentAction = `${agentName}.chat.completions`;
-        // Build the messages array
-        const messages = [
-            { role: 'system', content: systemPrompt },
-            { role: 'user', content: agentPrompt },
-        ];
-        // Create a virtual action step to execute via the agent
-        const agentStep = {
-            id: `${step.id}-subagent`,
-            type: 'action',
-            action: agentAction,
-            inputs: {
-                model,
-                messages,
-                max_tokens: 8192,
-            },
-            model,
-            agent: agentName,
-        };
-        // Build executor context
-        const executorContext = this.buildStepExecutorContext(agentStep);
-        // Execute the agent call
-        let response;
-        let turns = 0;
-        let conversationMessages = [...messages];
-        let finalOutput = {};
-        while (turns < maxTurns) {
-            turns++;
-            try {
-                response = await stepExecutor({ ...agentStep, inputs: { ...agentStep.inputs, messages: conversationMessages } }, context, sdkRegistry, executorContext);
-                // Parse the response
-                const parsedResponse = this.parseSubagentResponse(response);
-                if (parsedResponse.completed) {
-                    finalOutput = parsedResponse.output || {};
-                    break;
-                }
-                // If agent needs to continue, add its response and continue
-                if (parsedResponse.message) {
-                    conversationMessages.push({ role: 'assistant', content: parsedResponse.message });
-                    // Agent might request a tool call - for now, we'll prompt it to continue
-                    conversationMessages.push({ role: 'user', content: 'Continue with the workflow execution.' });
-                }
-                else {
-                    // No clear continuation, assume completed
-                    finalOutput = parsedResponse.output || {};
-                    break;
-                }
-            }
-            catch (error) {
-                throw new Error(`Sub-agent execution failed at turn ${turns}: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-        if (turns >= maxTurns) {
-            throw new Error(`Sub-agent exceeded maximum turns (${maxTurns})`);
-        }
-        return finalOutput;
-    }
-    /**
-     * Build the default system prompt for sub-agent execution.
-     */
-    buildDefaultSubagentSystemPrompt() {
-        return `You are an AI agent executing a workflow. Your task is to interpret the workflow definition and execute each step in order.
-
-For each step:
-1. Understand what the step requires
-2. Execute the action described
-3. Store any outputs as specified
-
-When you complete all steps, respond with a JSON object containing the workflow outputs.
-
-Format your final response as:
-\`\`\`json
-{
-  "completed": true,
-  "output": { /* workflow outputs here */ }
-}
-\`\`\`
-
-If you encounter an error, respond with:
-\`\`\`json
-{
-  "completed": false,
-  "error": "description of the error"
-}
-\`\`\``;
-    }
-    /**
-     * Build the prompt for sub-agent workflow execution.
-     */
-    buildSubagentPrompt(workflowContent, inputs, tools) {
-        return `Execute the following workflow:
-
-## Workflow Definition
-\`\`\`markdown
-${workflowContent}
-\`\`\`
-
-## Inputs
-\`\`\`json
-${JSON.stringify(inputs, null, 2)}
-\`\`\`
-
-## Available Tools
-${tools.join(', ')}
-
-Execute the workflow steps in order and return the final outputs as JSON.`;
-    }
-    /**
-     * Parse the sub-agent's response to extract completion status and output.
-     */
-    parseSubagentResponse(response) {
-        // Try to extract content from various response formats
-        let content;
-        if (typeof response === 'string') {
-            content = response;
-        }
-        else if (response && typeof response === 'object') {
-            const resp = response;
-            // OpenAI-style response
-            if (resp.choices && Array.isArray(resp.choices)) {
-                const choice = resp.choices[0];
-                if (choice.message && typeof choice.message === 'object') {
-                    const message = choice.message;
-                    content = message.content;
-                }
-            }
-            // Anthropic-style response
-            else if (resp.content && Array.isArray(resp.content)) {
-                const textBlock = resp.content.find((c) => typeof c === 'object' && c !== null && c.type === 'text');
-                content = textBlock?.text;
-            }
-            // Direct content field
-            else if (typeof resp.content === 'string') {
-                content = resp.content;
-            }
-            // Direct message field
-            else if (typeof resp.message === 'string') {
-                content = resp.message;
-            }
-        }
-        if (!content) {
-            return { completed: false, message: 'No content in response' };
-        }
-        // Try to parse JSON from the response
-        const jsonMatch = content.match(/```json\n?([\s\S]*?)```/);
-        if (jsonMatch) {
-            try {
-                const parsed = JSON.parse(jsonMatch[1]);
-                const output = parsed.output;
-                const error = parsed.error;
-                return {
-                    completed: parsed.completed === true,
-                    ...(output !== undefined ? { output } : {}),
-                    ...(error !== undefined ? { error } : {}),
-                };
-            }
-            catch (e) {
-                console.warn('[marktoflow] Failed to parse JSON block in sub-agent response:', e.message);
-            }
-        }
-        // Try to parse raw JSON
-        try {
-            const parsed = JSON.parse(content);
-            if (typeof parsed.completed === 'boolean') {
-                const output = parsed.output;
-                const error = parsed.error;
-                return {
-                    completed: parsed.completed,
-                    ...(output !== undefined ? { output } : {}),
-                    ...(error !== undefined ? { error } : {}),
-                };
-            }
-        }
-        catch (e) {
-            console.warn('[marktoflow] Sub-agent response is not valid JSON:', e.message);
-        }
-        // Return the content as a message
-        return { completed: false, message: content };
-    }
+    // ============================================================================
+    // Step Execution with Retry & Failover
+    // ============================================================================
     /**
      * Build the step executor context with effective model/agent/permissions.
      */
     buildStepExecutorContext(step) {
-        // Merge workflow and step permissions
         const effectivePermissions = mergePermissions(this.workflowPermissions, step.permissions);
-        // Resolve effective model/agent (step overrides workflow defaults)
-        const effectiveModel = step.model || this.config.defaultModel;
-        const effectiveAgent = step.agent || this.config.defaultAgent;
         return {
-            model: effectiveModel,
-            agent: effectiveAgent,
+            model: step.model || this.config.defaultModel,
+            agent: step.agent || this.config.defaultAgent,
             permissions: effectivePermissions,
             securityPolicy: toSecurityPolicy(effectivePermissions),
             basePath: this.workflowPath,
@@ -881,33 +379,25 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
         if (!step.prompt) {
             return step.inputs;
         }
-        // Check cache
         let loadedPrompt = this.promptCache.get(step.prompt);
         if (!loadedPrompt) {
             loadedPrompt = await loadPromptFile(step.prompt, this.workflowPath);
             this.promptCache.set(step.prompt, loadedPrompt);
         }
-        // Resolve prompt inputs (from step.promptInputs, with template resolution)
         const promptInputs = step.promptInputs
             ? resolveTemplates(step.promptInputs, context)
             : {};
-        // Validate prompt inputs
         const validation = validatePromptInputs(loadedPrompt, promptInputs);
         if (!validation.valid) {
             throw new Error(`Invalid prompt inputs: ${validation.errors.join(', ')}`);
         }
-        // Resolve the prompt template
         const resolved = resolvePromptTemplate(loadedPrompt, promptInputs, context);
-        // Merge resolved prompt content into inputs
-        // The resolved content typically goes into a 'messages' or 'prompt' field
         const resolvedInputs = { ...step.inputs };
-        // If inputs has a 'messages' array with a user message, inject prompt content
         if (Array.isArray(resolvedInputs.messages)) {
             resolvedInputs.messages = resolvedInputs.messages.map((msg) => {
                 if (typeof msg === 'object' && msg !== null) {
                     const message = msg;
                     if (message.role === 'user' && typeof message.content === 'string') {
-                        // Replace {{ prompt }} placeholder with resolved content
                         return {
                             ...message,
                             content: message.content.replace(/\{\{\s*prompt\s*\}\}/g, resolved.content),
@@ -918,7 +408,6 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
             });
         }
         else {
-            // Add resolved prompt as 'promptContent' for the executor to use
             resolvedInputs.promptContent = resolved.content;
         }
         return resolvedInputs;
@@ -929,15 +418,13 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
     async executeStepWithRetry(step, context, sdkRegistry, stepExecutor) {
         const startedAt = new Date();
         let lastError;
-        // Build executor context with model/agent/permissions
         const executorContext = this.buildStepExecutorContext(step);
         // Handle sub-workflow execution
         if (isSubWorkflowStep(step)) {
-            // Check if we should use subagent execution
             if (step.useSubagent) {
                 try {
                     this.events.onStepStart?.(step, context);
-                    const output = await this.executeWithTimeout(() => this.executeSubWorkflowWithAgent(step, context, sdkRegistry, stepExecutor), step.timeout ?? this.config.defaultTimeout);
+                    const output = await this.executeWithTimeout(() => executeSubWorkflowWithAgent(step, context, sdkRegistry, stepExecutor, this.workflowPath, this.config.defaultModel, this.config.defaultAgent, (s) => this.buildStepExecutorContext(s)), step.timeout ?? this.config.defaultTimeout);
                     const result = createStepResult(step.id, StepStatus.COMPLETED, output, startedAt, 0);
                     this.events.onStepComplete?.(step, result);
                     return result;
@@ -952,25 +439,35 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
             // Standard sub-workflow execution
             try {
                 this.events.onStepStart?.(step, context);
-                const output = await this.executeWithTimeout(() => this.executeSubWorkflow(step, context, sdkRegistry, stepExecutor), step.timeout ?? this.config.defaultTimeout);
+                const createSubEngine = (cfg) => {
+                    const subEngine = new WorkflowEngine(cfg, this.events, this.stateStore);
+                    return subEngine;
+                };
+                const output = await this.executeWithTimeout(() => executeSubWorkflow(step, context, sdkRegistry, stepExecutor, this.workflowPath, createSubEngine, {
+                    defaultTimeout: this.config.defaultTimeout,
+                    maxRetries: this.config.maxRetries,
+                    retryBaseDelay: this.config.retryBaseDelay,
+                    retryMaxDelay: this.config.retryMaxDelay,
+                    failoverConfig: this.failoverConfig,
+                    healthTracker: this.healthTracker,
+                    ...(this.rollbackRegistry ? { rollbackRegistry: this.rollbackRegistry } : {}),
+                }), step.timeout ?? this.config.defaultTimeout);
                 const result = createStepResult(step.id, StepStatus.COMPLETED, output, startedAt, 0);
                 this.events.onStepComplete?.(step, result);
                 return result;
             }
             catch (error) {
                 lastError = error instanceof Error ? error : new Error(String(error));
-                const result = createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, lastError // Pass full error object
-                );
+                const result = createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, lastError);
                 this.events.onStepComplete?.(step, result);
                 return result;
             }
         }
-        // Regular action step - ensure action is defined
+        // Regular action step
         if (!isActionStep(step)) {
             return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Step is neither an action nor a workflow');
         }
         const maxRetries = step.errorHandling?.maxRetries ?? this.config.maxRetries;
-        // Get or create circuit breaker for this step's action
         const [serviceName] = step.action.split('.');
         let circuitBreaker = this.circuitBreakers.get(serviceName);
         if (!circuitBreaker) {
@@ -978,34 +475,32 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
             this.circuitBreakers.set(serviceName, circuitBreaker);
         }
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
-            // Check circuit breaker
             if (!circuitBreaker.canExecute()) {
                 return createStepResult(step.id, StepStatus.FAILED, null, startedAt, attempt, `Circuit breaker open for service: ${serviceName}`);
             }
             this.events.onStepStart?.(step, context);
             try {
-                // Load and resolve external prompt if specified
                 let resolvedInputs;
                 if (step.prompt) {
                     resolvedInputs = await this.loadAndResolvePrompt(step, context);
                     resolvedInputs = resolveTemplates(resolvedInputs, context);
                 }
                 else {
-                    // Resolve templates in inputs
                     resolvedInputs = resolveTemplates(step.inputs, context);
                 }
                 const stepWithResolvedInputs = { ...step, inputs: resolvedInputs };
-                // Check if this is a built-in operation
                 let output;
-                if (isBuiltInOperation(step.action)) {
-                    // Execute built-in operation directly (no timeout, no SDK executor needed)
-                    // For built-in operations, pass both resolved and unresolved inputs
-                    // to allow selective resolution of template expressions
-                    // Await in case operation is async (e.g., file operations)
+                if (isParallelOperation(step.action)) {
+                    // Pass both resolved and raw inputs to parallel operations.
+                    // Resolved inputs are used for structural fields (items, agents, etc.).
+                    // Raw inputs preserve prompt templates with per-item variables
+                    // ({{ item }}, {{ itemIndex }}) that can't be resolved until iteration.
+                    output = await executeParallelOperation(step.action, resolvedInputs, context, sdkRegistry, stepExecutor, step.inputs);
+                }
+                else if (isBuiltInOperation(step.action)) {
                     output = await executeBuiltInOperation(step.action, step.inputs, resolvedInputs, context);
                 }
                 else {
-                    // Execute step with executor context
                     output = await this.executeWithTimeout(() => stepExecutor(stepWithResolvedInputs, context, sdkRegistry, executorContext), step.timeout ?? this.config.defaultTimeout);
                 }
                 circuitBreaker.recordSuccess();
@@ -1017,16 +512,13 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
                 lastError = error instanceof Error ? error : new Error(String(error));
                 circuitBreaker.recordFailure();
                 this.events.onStepError?.(step, lastError, attempt);
-                // Wait before retry (unless last attempt)
                 if (attempt < maxRetries) {
                     const delay = this.retryPolicy.getDelay(attempt);
                     await sleep(delay);
                 }
             }
         }
-        // All retries exhausted
-        const result = createStepResult(step.id, StepStatus.FAILED, null, startedAt, maxRetries, lastError // Pass full error object to preserve HTTP details, stack traces, etc.
-        );
+        const result = createStepResult(step.id, StepStatus.FAILED, null, startedAt, maxRetries, lastError);
         this.events.onStepComplete?.(step, result);
         return result;
     }
@@ -1035,7 +527,6 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
      */
     async executeStepWithFailover(step, context, sdkRegistry, stepExecutor) {
         const primaryResult = await this.executeStepWithRetry(step, context, sdkRegistry, stepExecutor);
-        // Sub-workflows and non-action steps don't support failover
         if (!isActionStep(step)) {
             return primaryResult;
         }
@@ -1084,6 +575,9 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
         this.healthTracker.markUnhealthy(primaryTool, errorMessage);
         return primaryResult;
     }
+    // ============================================================================
+    // Utility Methods
+    // ============================================================================
     /**
      * Execute a function with a timeout.
      */
@@ -1093,112 +587,11 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
             new Promise((_, reject) => setTimeout(() => reject(new Error(`Step timed out after ${timeoutMs}ms`)), timeoutMs)),
         ]);
     }
-    /**
-     * Evaluate step conditions.
-     */
-    evaluateConditions(conditions, context) {
-        for (const condition of conditions) {
-            if (!this.evaluateCondition(condition, context)) {
-                return false;
-            }
-        }
-        return true;
-    }
-    /**
-     * Evaluate a single condition.
-     * Supports: ==, !=, >, <, >=, <=
-     * Also supports nested property access (e.g., check_result.success)
-     * and step status checks (e.g., step_id.status == 'failed')
-     */
-    evaluateCondition(condition, context) {
-        // Simple expression parsing
-        const operators = ['==', '!=', '>=', '<=', '>', '<'];
-        let operator;
-        let parts = [];
-        for (const op of operators) {
-            if (condition.includes(op)) {
-                operator = op;
-                parts = condition.split(op).map((s) => s.trim());
-                break;
-            }
-        }
-        if (!operator || parts.length !== 2) {
-            // Treat as boolean variable reference with nested property support
-            const value = this.resolveConditionValue(condition, context);
-            return Boolean(value);
-        }
-        const left = this.resolveConditionValue(parts[0], context);
-        const right = this.parseValue(parts[1]);
-        switch (operator) {
-            case '==':
-                return left == right;
-            case '!=':
-                return left != right;
-            case '>':
-                return Number(left) > Number(right);
-            case '<':
-                return Number(left) < Number(right);
-            case '>=':
-                return Number(left) >= Number(right);
-            case '<=':
-                return Number(left) <= Number(right);
-            default:
-                return false;
-        }
-    }
-    /**
-     * Resolve a condition value with support for nested properties.
-     * Handles direct variable references and nested paths.
-     * Uses Nunjucks for template expressions with filters/regex.
-     */
-    resolveConditionValue(path, context) {
-        // If it looks like a template expression, resolve it
-        if (path.includes('|') || path.includes('=~') || path.includes('!~')) {
-            // Build template context
-            const templateContext = {
-                inputs: context.inputs,
-                ...context.variables,
-            };
-            return renderTemplate(`{{ ${path} }}`, templateContext);
-        }
-        // First try to parse as a literal value (true, false, numbers, etc.)
-        const parsedValue = this.parseValue(path);
-        // If parseValue returned the same string, try to resolve as a variable
-        if (parsedValue === path) {
-            const resolved = resolveVariablePath(path, context);
-            return resolved;
-        }
-        // Return the parsed literal value
-        return parsedValue;
-    }
-    /**
-     * Parse a value from a condition string.
-     */
-    parseValue(value) {
-        // Remove quotes
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            return value.slice(1, -1);
-        }
-        // Numbers
-        if (!isNaN(Number(value))) {
-            return Number(value);
-        }
-        // Booleans
-        if (value === 'true')
-            return true;
-        if (value === 'false')
-            return false;
-        if (value === 'null')
-            return null;
-        return value;
-    }
     /**
      * Build the final workflow result.
      */
     buildWorkflowResult(workflow, context, stepResults, startedAt, error) {
         const completedAt = new Date();
-        // Use workflowOutputs if set by workflow.set_outputs, otherwise use all variables
         const output = context.workflowOutputs || context.variables;
         return {
             workflowId: workflow.metadata.id,
@@ -1220,665 +613,6 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
             breaker.reset();
         }
     }
-    // ============================================================================
-    // Control Flow Execution Methods
-    // ============================================================================
-    /**
-     * Execute an if/else conditional step.
-     */
-    async executeIfStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Evaluate condition
-            const conditionResult = this.evaluateCondition(step.condition, context);
-            // Determine which branch to execute
-            const branchSteps = conditionResult
-                ? step.then || step.steps // 'steps' is alias for 'then'
-                : step.else;
-            if (!branchSteps || branchSteps.length === 0) {
-                return createStepResult(step.id, StepStatus.SKIPPED, null, startedAt);
-            }
-            // Execute the branch steps
-            const branchResults = [];
-            for (const branchStep of branchSteps) {
-                const result = await this.executeStep(branchStep, context, sdkRegistry, stepExecutor);
-                if (result.status === StepStatus.COMPLETED && branchStep.outputVariable) {
-                    context.variables[branchStep.outputVariable] = result.output;
-                    branchResults.push(result.output);
-                }
-                if (result.status === StepStatus.FAILED) {
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
-                }
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, branchResults, startedAt);
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a switch/case step.
-     */
-    async executeSwitchStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Resolve the switch expression
-            const expressionValue = String(resolveTemplates(step.expression, context));
-            // Find matching case
-            const caseSteps = step.cases[expressionValue] || step.default;
-            if (!caseSteps || caseSteps.length === 0) {
-                return createStepResult(step.id, StepStatus.SKIPPED, null, startedAt);
-            }
-            // Execute case steps
-            const caseResults = [];
-            for (const caseStep of caseSteps) {
-                const result = await this.executeStep(caseStep, context, sdkRegistry, stepExecutor);
-                if (result.status === StepStatus.COMPLETED && caseStep.outputVariable) {
-                    context.variables[caseStep.outputVariable] = result.output;
-                    caseResults.push(result.output);
-                }
-                if (result.status === StepStatus.FAILED) {
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
-                }
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, caseResults, startedAt);
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a for-each loop step.
-     * Supports optional batch_size and pause_between_batches for rate limiting.
-     */
-    async executeForEachStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        const cleanupLoopVars = () => {
-            delete context.variables[step.itemVariable];
-            delete context.variables['loop'];
-            delete context.variables['batch'];
-            if (step.indexVariable)
-                delete context.variables[step.indexVariable];
-        };
-        try {
-            // Resolve items array
-            const items = resolveTemplates(step.items, context);
-            if (!Array.isArray(items)) {
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Items must be an array');
-            }
-            if (items.length === 0) {
-                return createStepResult(step.id, StepStatus.SKIPPED, [], startedAt);
-            }
-            const batchSize = step.batchSize;
-            const pauseBetweenBatches = step.pauseBetweenBatches;
-            // If batch mode, process items in batches
-            if (batchSize && batchSize > 0) {
-                return await this.executeForEachBatched(step, items, batchSize, pauseBetweenBatches ?? 0, context, sdkRegistry, stepExecutor, startedAt);
-            }
-            // Standard item-by-item execution
-            const results = [];
-            for (let i = 0; i < items.length; i++) {
-                context.variables[step.itemVariable] = items[i];
-                context.variables['loop'] = {
-                    index: i,
-                    first: i === 0,
-                    last: i === items.length - 1,
-                    length: items.length,
-                };
-                if (step.indexVariable) {
-                    context.variables[step.indexVariable] = i;
-                }
-                // Execute iteration steps
-                for (const iterStep of step.steps) {
-                    const result = await this.executeStep(iterStep, context, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && iterStep.outputVariable) {
-                        context.variables[iterStep.outputVariable] = result.output;
-                    }
-                    if (result.status === StepStatus.FAILED) {
-                        const errorAction = step.errorHandling?.action ?? 'stop';
-                        if (errorAction === 'stop') {
-                            cleanupLoopVars();
-                            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
-                        }
-                        break;
-                    }
-                }
-                results.push(context.variables[step.itemVariable]);
-            }
-            cleanupLoopVars();
-            return createStepResult(step.id, StepStatus.COMPLETED, results, startedAt);
-        }
-        catch (error) {
-            cleanupLoopVars();
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute for-each in batch mode.
-     * Items are split into batches; {{ batch }} contains the current batch array.
-     */
-    async executeForEachBatched(step, items, batchSize, pauseBetweenBatches, context, sdkRegistry, stepExecutor, startedAt) {
-        const results = [];
-        const totalBatches = Math.ceil(items.length / batchSize);
-        for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
-            const batchStart = batchIndex * batchSize;
-            const batchItems = items.slice(batchStart, batchStart + batchSize);
-            // Pause between batches (not before first batch)
-            if (batchIndex > 0 && pauseBetweenBatches > 0) {
-                await new Promise((resolve) => setTimeout(resolve, pauseBetweenBatches));
-            }
-            // Expose batch-level variables
-            context.variables['batch'] = batchItems;
-            context.variables['loop'] = {
-                index: batchIndex,
-                first: batchIndex === 0,
-                last: batchIndex === totalBatches - 1,
-                length: totalBatches,
-                batchSize,
-                batchStart,
-                totalItems: items.length,
-            };
-            // Process each item in the batch
-            for (let i = 0; i < batchItems.length; i++) {
-                const globalIndex = batchStart + i;
-                context.variables[step.itemVariable] = batchItems[i];
-                if (step.indexVariable) {
-                    context.variables[step.indexVariable] = globalIndex;
-                }
-                for (const iterStep of step.steps) {
-                    const result = await this.executeStep(iterStep, context, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && iterStep.outputVariable) {
-                        context.variables[iterStep.outputVariable] = result.output;
-                    }
-                    if (result.status === StepStatus.FAILED) {
-                        const errorAction = step.errorHandling?.action ?? 'stop';
-                        if (errorAction === 'stop') {
-                            delete context.variables[step.itemVariable];
-                            delete context.variables['loop'];
-                            delete context.variables['batch'];
-                            if (step.indexVariable)
-                                delete context.variables[step.indexVariable];
-                            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
-                        }
-                        break;
-                    }
-                }
-                results.push(context.variables[step.itemVariable]);
-            }
-        }
-        delete context.variables[step.itemVariable];
-        delete context.variables['loop'];
-        delete context.variables['batch'];
-        if (step.indexVariable)
-            delete context.variables[step.indexVariable];
-        return createStepResult(step.id, StepStatus.COMPLETED, results, startedAt);
-    }
-    /**
-     * Execute a while loop step.
-     */
-    async executeWhileStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        let iterations = 0;
-        try {
-            while (this.evaluateCondition(step.condition, context)) {
-                if (iterations >= step.maxIterations) {
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, `Max iterations (${step.maxIterations}) exceeded`);
-                }
-                // Execute iteration steps
-                for (const iterStep of step.steps) {
-                    const result = await this.executeStep(iterStep, context, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && iterStep.outputVariable) {
-                        context.variables[iterStep.outputVariable] = result.output;
-                    }
-                    if (result.status === StepStatus.FAILED) {
-                        const errorAction = step.errorHandling?.action ?? 'stop';
-                        if (errorAction === 'stop') {
-                            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
-                        }
-                        // 'continue' - skip to next iteration
-                        break;
-                    }
-                }
-                iterations++;
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, { iterations }, startedAt);
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a map transformation step.
-     */
-    async executeMapStep(step, context, _sdkRegistry, _stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Resolve items array
-            const items = resolveTemplates(step.items, context);
-            if (!Array.isArray(items)) {
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Items must be an array');
-            }
-            // Map each item using the expression
-            const mapped = items.map((item) => {
-                context.variables[step.itemVariable] = item;
-                const result = resolveTemplates(step.expression, context);
-                delete context.variables[step.itemVariable];
-                return result;
-            });
-            return createStepResult(step.id, StepStatus.COMPLETED, mapped, startedAt);
-        }
-        catch (error) {
-            delete context.variables[step.itemVariable];
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a filter step.
-     */
-    async executeFilterStep(step, context, _sdkRegistry, _stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Resolve items array
-            const items = resolveTemplates(step.items, context);
-            if (!Array.isArray(items)) {
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Items must be an array');
-            }
-            // Filter items using the condition
-            const filtered = items.filter((item) => {
-                context.variables[step.itemVariable] = item;
-                const result = this.evaluateCondition(step.condition, context);
-                delete context.variables[step.itemVariable];
-                return result;
-            });
-            return createStepResult(step.id, StepStatus.COMPLETED, filtered, startedAt);
-        }
-        catch (error) {
-            delete context.variables[step.itemVariable];
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a reduce/aggregate step.
-     */
-    async executeReduceStep(step, context, _sdkRegistry, _stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Resolve items array
-            const items = resolveTemplates(step.items, context);
-            if (!Array.isArray(items)) {
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Items must be an array');
-            }
-            // Reduce items using the expression
-            let accumulator = step.initialValue ?? null;
-            for (const item of items) {
-                context.variables[step.itemVariable] = item;
-                context.variables[step.accumulatorVariable] = accumulator;
-                accumulator = resolveTemplates(step.expression, context);
-                delete context.variables[step.itemVariable];
-                delete context.variables[step.accumulatorVariable];
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, accumulator, startedAt);
-        }
-        catch (error) {
-            delete context.variables[step.itemVariable];
-            delete context.variables[step.accumulatorVariable];
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute parallel branches.
-     */
-    async executeParallelStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        try {
-            // Execute branches in parallel
-            const branchPromises = step.branches.map(async (branch) => {
-                // Clone context for isolation
-                const branchContext = this.cloneContext(context);
-                // Execute branch steps
-                const branchResults = [];
-                for (const branchStep of branch.steps) {
-                    const result = await this.executeStep(branchStep, branchContext, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && branchStep.outputVariable) {
-                        branchContext.variables[branchStep.outputVariable] = result.output;
-                        branchResults.push(result.output);
-                    }
-                    if (result.status === StepStatus.FAILED) {
-                        throw new Error(`Branch ${branch.id} failed: ${errorToString(result.error)}`);
-                    }
-                }
-                return { branchId: branch.id, context: branchContext, results: branchResults };
-            });
-            // Wait for all branches (or limited concurrency)
-            const branchResults = step.maxConcurrent
-                ? await this.executeConcurrentlyWithLimit(branchPromises, step.maxConcurrent)
-                : await Promise.all(branchPromises);
-            // Merge branch contexts back into main context
-            for (const { branchId, context: branchContext } of branchResults) {
-                this.mergeContexts(context, branchContext, branchId);
-            }
-            const outputs = branchResults.map((br) => br.results);
-            return createStepResult(step.id, StepStatus.COMPLETED, outputs, startedAt);
-        }
-        catch (error) {
-            if (step.onError === 'continue') {
-                return createStepResult(step.id, StepStatus.COMPLETED, null, startedAt);
-            }
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute try/catch/finally step.
-     */
-    async executeTryStep(step, context, sdkRegistry, stepExecutor) {
-        const startedAt = new Date();
-        let tryError;
-        try {
-            // Execute try block
-            for (const tryStep of step.try) {
-                const result = await this.executeStep(tryStep, context, sdkRegistry, stepExecutor);
-                if (result.status === StepStatus.COMPLETED && tryStep.outputVariable) {
-                    context.variables[tryStep.outputVariable] = result.output;
-                }
-                if (result.status === StepStatus.FAILED) {
-                    tryError = new Error(result.error ? errorToString(result.error) : 'Step failed');
-                    break;
-                }
-            }
-            // If error occurred and catch block exists, execute catch
-            let catchError;
-            if (tryError && step.catch) {
-                // Inject error object into context
-                context.variables['error'] = {
-                    message: tryError.message,
-                    step: tryError,
-                };
-                for (const catchStep of step.catch) {
-                    const result = await this.executeStep(catchStep, context, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && catchStep.outputVariable) {
-                        context.variables[catchStep.outputVariable] = result.output;
-                    }
-                    if (result.status === StepStatus.FAILED) {
-                        catchError = new Error(result.error ? errorToString(result.error) : 'Catch block failed');
-                        break;
-                    }
-                }
-                delete context.variables['error'];
-            }
-            // Execute finally block (always runs)
-            if (step.finally) {
-                for (const finallyStep of step.finally) {
-                    const result = await this.executeStep(finallyStep, context, sdkRegistry, stepExecutor);
-                    if (result.status === StepStatus.COMPLETED && finallyStep.outputVariable) {
-                        context.variables[finallyStep.outputVariable] = result.output;
-                    }
-                }
-            }
-            // Return success if catch handled the error, or error if not
-            if (tryError && !step.catch) {
-                // No catch block to handle error
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, tryError.message);
-            }
-            if (catchError) {
-                // Catch block also failed
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, catchError.message);
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, null, startedAt);
-        }
-        catch (error) {
-            // Execute finally even on unexpected error
-            if (step.finally) {
-                try {
-                    for (const finallyStep of step.finally) {
-                        const result = await this.executeStep(finallyStep, context, sdkRegistry, stepExecutor);
-                        if (result.status === StepStatus.COMPLETED && finallyStep.outputVariable) {
-                            context.variables[finallyStep.outputVariable] = result.output;
-                        }
-                    }
-                }
-                catch {
-                    // Ignore finally errors
-                }
-            }
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    /**
-     * Execute a script step (inline JavaScript).
-     */
-    async executeScriptStep(step, context) {
-        const startedAt = new Date();
-        try {
-            // Resolve any templates in the code
-            const resolvedInputs = resolveTemplates(step.inputs, context);
-            // Execute the script with the workflow context
-            const result = await executeScriptAsync(resolvedInputs.code, {
-                variables: context.variables,
-                inputs: context.inputs,
-                steps: context.stepMetadata,
-            }, {
-                timeout: resolvedInputs.timeout ?? 5000,
-            });
-            if (!result.success) {
-                return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error ?? 'Script execution failed');
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, result.value, startedAt);
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    // ============================================================================
-    // Wait Step Execution
-    // ============================================================================
-    /**
-     * Execute a wait/pause step.
-     *
-     * For mode=duration: In-process wait (suitable for short durations).
-     *   For persistent long-duration waits, a WaitManager should checkpoint
-     *   the execution and resume it later via the scheduler.
-     *
-     * For mode=webhook: Returns a resume URL. The execution will be
-     *   checkpointed and resumed when the URL is called.
-     *
-     * For mode=form: Returns form fields. The execution will be
-     *   checkpointed and resumed when the form is submitted.
-     */
-    async executeWaitStep(step, context) {
-        const startedAt = new Date();
-        try {
-            switch (step.mode) {
-                case 'duration': {
-                    if (!step.duration) {
-                        return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Wait step with mode=duration requires a duration');
-                    }
-                    const resolvedDuration = resolveTemplates(step.duration, context);
-                    const ms = parseDuration(resolvedDuration);
-                    // For short durations (under 5 minutes), do in-process wait
-                    if (ms <= 300000) {
-                        await new Promise((resolve) => setTimeout(resolve, ms));
-                        return createStepResult(step.id, StepStatus.COMPLETED, { waited: ms }, startedAt);
-                    }
-                    // For longer durations, checkpoint and schedule resume
-                    // The StateStore will persist the execution state
-                    if (this.stateStore) {
-                        this.stateStore.saveCheckpoint({
-                            runId: context.runId,
-                            stepIndex: context.currentStepIndex,
-                            stepName: step.id,
-                            status: StepStatus.COMPLETED,
-                            startedAt: startedAt,
-                            completedAt: new Date(),
-                            inputs: { mode: 'duration', resumeAt: new Date(Date.now() + ms).toISOString() },
-                            outputs: { waiting: true },
-                            error: null,
-                            retryCount: 0,
-                        });
-                    }
-                    // Set execution status to indicate waiting
-                    const resumeAt = new Date(Date.now() + ms).toISOString();
-                    return createStepResult(step.id, StepStatus.COMPLETED, {
-                        waiting: true,
-                        mode: 'duration',
-                        resumeAt,
-                        durationMs: ms,
-                    }, startedAt);
-                }
-                case 'webhook': {
-                    // Generate a unique resume URL
-                    const resumeToken = crypto.randomUUID();
-                    const webhookPath = step.webhookPath
-                        ? resolveTemplates(step.webhookPath, context)
-                        : `/resume/${context.runId}/${step.id}/${resumeToken}`;
-                    if (this.stateStore) {
-                        this.stateStore.saveCheckpoint({
-                            runId: context.runId,
-                            stepIndex: context.currentStepIndex,
-                            stepName: step.id,
-                            status: StepStatus.COMPLETED,
-                            startedAt: startedAt,
-                            completedAt: new Date(),
-                            inputs: { mode: 'webhook', resumeToken, webhookPath },
-                            outputs: { waiting: true },
-                            error: null,
-                            retryCount: 0,
-                        });
-                    }
-                    return createStepResult(step.id, StepStatus.COMPLETED, {
-                        waiting: true,
-                        mode: 'webhook',
-                        resumeToken,
-                        webhookPath,
-                    }, startedAt);
-                }
-                case 'form': {
-                    if (!step.fields || Object.keys(step.fields).length === 0) {
-                        return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Wait step with mode=form requires fields');
-                    }
-                    const resumeToken = crypto.randomUUID();
-                    if (this.stateStore) {
-                        this.stateStore.saveCheckpoint({
-                            runId: context.runId,
-                            stepIndex: context.currentStepIndex,
-                            stepName: step.id,
-                            status: StepStatus.COMPLETED,
-                            startedAt: startedAt,
-                            completedAt: new Date(),
-                            inputs: { mode: 'form', resumeToken, fields: step.fields },
-                            outputs: { waiting: true },
-                            error: null,
-                            retryCount: 0,
-                        });
-                    }
-                    return createStepResult(step.id, StepStatus.COMPLETED, {
-                        waiting: true,
-                        mode: 'form',
-                        resumeToken,
-                        fields: step.fields,
-                        formPath: `/form/${context.runId}/${step.id}/${resumeToken}`,
-                    }, startedAt);
-                }
-                default:
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, `Unknown wait mode: ${step.mode}`);
-            }
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    // ============================================================================
-    // Merge Step Execution
-    // ============================================================================
-    /**
-     * Execute a merge step - combines data from multiple sources.
-     */
-    async executeMergeStep(step, context) {
-        const startedAt = new Date();
-        try {
-            // Resolve all source expressions to arrays
-            const resolvedSources = [];
-            for (const source of step.sources) {
-                const resolved = resolveTemplates(source, context);
-                if (!Array.isArray(resolved)) {
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, `Merge source "${source}" did not resolve to an array`);
-                }
-                resolvedSources.push(resolved);
-            }
-            let result;
-            switch (step.mode) {
-                case 'append':
-                    result = resolvedSources.flat();
-                    break;
-                case 'match': {
-                    if (!step.matchField) {
-                        return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Merge mode "match" requires matchField');
-                    }
-                    // Return items that appear in ALL sources (by matchField)
-                    const fieldSets = resolvedSources.map((source) => new Set(source.map((item) => getField(item, step.matchField))));
-                    // Intersection of all field sets
-                    const commonKeys = fieldSets.reduce((acc, set) => new Set([...acc].filter((key) => set.has(key))));
-                    // Return items from first source that match
-                    result = resolvedSources[0].filter((item) => commonKeys.has(getField(item, step.matchField)));
-                    break;
-                }
-                case 'diff': {
-                    if (!step.matchField) {
-                        return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Merge mode "diff" requires matchField');
-                    }
-                    // Return items from first source NOT found in other sources
-                    const otherKeys = new Set(resolvedSources.slice(1).flat().map((item) => getField(item, step.matchField)));
-                    result = resolvedSources[0].filter((item) => !otherKeys.has(getField(item, step.matchField)));
-                    break;
-                }
-                case 'combine_by_field': {
-                    if (!step.matchField) {
-                        return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, 'Merge mode "combine_by_field" requires matchField');
-                    }
-                    // Group items by matchField and merge their properties
-                    const grouped = new Map();
-                    const onConflict = step.onConflict ?? 'keep_last';
-                    for (const source of resolvedSources) {
-                        for (const item of source) {
-                            if (!item || typeof item !== 'object')
-                                continue;
-                            const key = getField(item, step.matchField);
-                            const existing = grouped.get(key);
-                            if (existing) {
-                                if (onConflict === 'keep_first') {
-                                    // Only add new fields
-                                    for (const [k, v] of Object.entries(item)) {
-                                        if (!(k in existing))
-                                            existing[k] = v;
-                                    }
-                                }
-                                else if (onConflict === 'keep_last') {
-                                    Object.assign(existing, item);
-                                }
-                                else {
-                                    // merge_fields: deep merge
-                                    Object.assign(existing, item);
-                                }
-                            }
-                            else {
-                                grouped.set(key, { ...item });
-                            }
-                        }
-                    }
-                    result = Array.from(grouped.values());
-                    break;
-                }
-                default:
-                    return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, `Unknown merge mode: ${step.mode}`);
-            }
-            return createStepResult(step.id, StepStatus.COMPLETED, result, startedAt);
-        }
-        catch (error) {
-            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
-        }
-    }
-    // ============================================================================
-    // Helper Methods for Control Flow
-    // ============================================================================
     /**
      * Clone execution context for parallel branches.
      */
@@ -1894,7 +628,6 @@ Execute the workflow steps in order and return the final outputs as JSON.`;
      * Merge branch context back into main context.
      */
     mergeContexts(mainContext, branchContext, branchId) {
-        // Merge variables with branch prefix
         for (const [key, value] of Object.entries(branchContext.variables)) {
             mainContext.variables[`${branchId}.${key}`] = value;
         }