@marktoflow/core 2.0.0-alpha.12

package/dist/engine.js

@@ -0,0 +1,1453 @@
+/**
+ * Workflow Execution Engine for marktoflow v2.0
+ *
+ * Executes workflow steps with retry logic, variable resolution,
+ * and SDK invocation.
+ */
+import { StepStatus, WorkflowStatus, createExecutionContext, createStepResult, isActionStep, isSubWorkflowStep, isIfStep, isSwitchStep, isForEachStep, isWhileStep, isMapStep, isFilterStep, isReduceStep, isParallelStep, isTryStep, } 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';
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * 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);
+    }
+}
+// ============================================================================
+// 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
+// ============================================================================
+/**
+ * Smart serialization for template interpolation.
+ * Converts values to strings in a meaningful way for different types.
+ */
+function serializeValue(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    // For primitives, use standard string conversion
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    // For objects and arrays, use JSON serialization for readability
+    // This makes them useful in prompts and messages instead of "[object Object]"
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch (error) {
+        // Fallback to string conversion if JSON serialization fails
+        return String(value);
+    }
+}
+/**
+ * Resolve template variables in a value.
+ * Supports {{variable}} and {{inputs.name}} syntax.
+ */
+export function resolveTemplates(value, context) {
+    if (typeof value === 'string') {
+        // Check if the entire string is a single template expression
+        const singleTemplateMatch = value.match(/^\{\{([^}]+)\}\}$/);
+        if (singleTemplateMatch) {
+            // Return the actual value without converting to string
+            const path = singleTemplateMatch[1].trim();
+            const resolved = resolveVariablePath(path, context);
+            // For single template expressions, return the actual value (could be object, array, etc.)
+            // If undefined, return empty string for backward compatibility
+            return resolved !== undefined ? resolved : '';
+        }
+        // Otherwise, do string interpolation with smart serialization
+        return value.replace(/\{\{([^}]+)\}\}/g, (_, varPath) => {
+            const path = varPath.trim();
+            const resolved = resolveVariablePath(path, context);
+            return serializeValue(resolved);
+        });
+    }
+    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 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;
+}
+export class WorkflowEngine {
+    config;
+    retryPolicy;
+    circuitBreakers = new Map();
+    events;
+    stateStore;
+    rollbackRegistry;
+    failoverConfig;
+    healthTracker;
+    failoverEvents = [];
+    workflowPath; // Base path for resolving sub-workflows
+    workflowPermissions; // Workflow-level permissions
+    promptCache = new Map(); // Cache for loaded prompts
+    constructor(config = {}, events = {}, stateStore) {
+        this.config = {
+            defaultTimeout: config.defaultTimeout ?? 60000,
+            maxRetries: config.maxRetries ?? 3,
+            retryBaseDelay: config.retryBaseDelay ?? 1000,
+            retryMaxDelay: config.retryMaxDelay ?? 30000,
+            defaultAgent: config.defaultAgent,
+            defaultModel: config.defaultModel,
+        };
+        this.retryPolicy = new RetryPolicy(this.config.maxRetries, this.config.retryBaseDelay, this.config.retryMaxDelay);
+        this.events = events;
+        this.stateStore = stateStore;
+        this.rollbackRegistry = config.rollbackRegistry;
+        this.failoverConfig = { ...DEFAULT_FAILOVER_CONFIG, ...(config.failoverConfig ?? {}) };
+        this.healthTracker = config.healthTracker ?? new AgentHealthTracker();
+    }
+    /**
+     * Execute a single step - dispatcher 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)) {
+            return createStepResult(step.id, StepStatus.SKIPPED, null, new Date());
+        }
+        // Dispatch to specialized execution method based on step type
+        if (isIfStep(step)) {
+            return this.executeIfStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isSwitchStep(step)) {
+            return this.executeSwitchStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isForEachStep(step)) {
+            return this.executeForEachStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isWhileStep(step)) {
+            return this.executeWhileStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isMapStep(step)) {
+            return this.executeMapStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isFilterStep(step)) {
+            return this.executeFilterStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isReduceStep(step)) {
+            return this.executeReduceStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isParallelStep(step)) {
+            return this.executeParallelStep(step, context, sdkRegistry, stepExecutor);
+        }
+        if (isTryStep(step)) {
+            return this.executeTryStep(step, context, sdkRegistry, stepExecutor);
+        }
+        // Default: action or workflow step
+        return this.executeStepWithFailover(step, context, sdkRegistry, stepExecutor);
+    }
+    /**
+     * Execute a workflow.
+     */
+    async execute(workflow, inputs = {}, sdkRegistry, stepExecutor) {
+        const context = createExecutionContext(workflow, inputs);
+        const stepResults = [];
+        const startedAt = new Date();
+        // Store workflow-level permissions and defaults
+        this.workflowPermissions = workflow.permissions;
+        // Use workflow defaults if not set in engine config
+        if (!this.config.defaultAgent && workflow.defaultAgent) {
+            this.config.defaultAgent = workflow.defaultAgent;
+        }
+        if (!this.config.defaultModel && workflow.defaultModel) {
+            this.config.defaultModel = workflow.defaultModel;
+        }
+        context.status = WorkflowStatus.RUNNING;
+        this.events.onWorkflowStart?.(workflow, context);
+        if (this.stateStore) {
+            this.stateStore.createExecution({
+                runId: context.runId,
+                workflowId: workflow.metadata.id,
+                workflowPath: 'unknown',
+                status: WorkflowStatus.RUNNING,
+                startedAt: startedAt,
+                completedAt: null,
+                currentStep: 0,
+                totalSteps: workflow.steps.length,
+                inputs: inputs,
+                outputs: null,
+                error: null,
+                metadata: null,
+            });
+        }
+        try {
+            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'
+                context.stepMetadata[step.id] = {
+                    status: result.status.toLowerCase(),
+                    retryCount: result.retryCount,
+                    ...(result.error ? { error: errorToString(result.error) } : {}),
+                };
+                // Store output variable
+                if (step.outputVariable && result.status === StepStatus.COMPLETED) {
+                    context.variables[step.outputVariable] = result.output;
+                }
+                // Check if this step set workflow outputs (from workflow.set_outputs action)
+                if (result.status === StepStatus.COMPLETED &&
+                    result.output &&
+                    typeof result.output === 'object' &&
+                    '__workflow_outputs__' in result.output) {
+                    const outputObj = result.output;
+                    const outputs = outputObj['__workflow_outputs__'];
+                    context.workflowOutputs = outputs;
+                }
+                // 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;
+                    }
+                    if (errorAction === 'stop') {
+                        context.status = WorkflowStatus.FAILED;
+                        const workflowError = result.error ? errorToString(result.error) : `Step ${step.id} failed`;
+                        const workflowResult = this.buildWorkflowResult(workflow, context, stepResults, startedAt, workflowError);
+                        this.events.onWorkflowComplete?.(workflow, workflowResult);
+                        return workflowResult;
+                    }
+                    // 'continue' - keep going
+                    if (errorAction === 'rollback') {
+                        if (this.rollbackRegistry) {
+                            await this.rollbackRegistry.rollbackAllAsync({
+                                context,
+                                inputs: context.inputs,
+                                variables: context.variables,
+                            });
+                        }
+                        context.status = WorkflowStatus.FAILED;
+                        const workflowError = result.error ? errorToString(result.error) : `Step ${step.id} failed`;
+                        const workflowResult = this.buildWorkflowResult(workflow, context, stepResults, startedAt, workflowError);
+                        this.events.onWorkflowComplete?.(workflow, workflowResult);
+                        return workflowResult;
+                    }
+                }
+            }
+            // Determine final status
+            context.status = WorkflowStatus.COMPLETED;
+        }
+        catch (error) {
+            context.status = WorkflowStatus.FAILED;
+            if (this.stateStore) {
+                this.stateStore.updateExecution(context.runId, {
+                    status: WorkflowStatus.FAILED,
+                    completedAt: new Date(),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const workflowResult = this.buildWorkflowResult(workflow, context, stepResults, startedAt, error instanceof Error ? error.message : String(error));
+            this.events.onWorkflowComplete?.(workflow, workflowResult);
+            return workflowResult;
+        }
+        const workflowResult = this.buildWorkflowResult(workflow, context, stepResults, startedAt);
+        if (this.stateStore) {
+            this.stateStore.updateExecution(context.runId, {
+                status: context.status,
+                completedAt: new Date(),
+                outputs: context.variables,
+            });
+        }
+        this.events.onWorkflowComplete?.(workflow, workflowResult);
+        return workflowResult;
+    }
+    /**
+     * 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 {
+                // JSON parse failed, treat as 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 {
+            // Not JSON
+        }
+        // Return the content as a message
+        return { completed: false, message: content };
+    }
+    /**
+     * 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,
+            permissions: effectivePermissions,
+            securityPolicy: toSecurityPolicy(effectivePermissions),
+            basePath: this.workflowPath,
+        };
+    }
+    /**
+     * Load and resolve an external prompt file for a step.
+     */
+    async loadAndResolvePrompt(step, context) {
+        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),
+                        };
+                    }
+                }
+                return msg;
+            });
+        }
+        else {
+            // Add resolved prompt as 'promptContent' for the executor to use
+            resolvedInputs.promptContent = resolved.content;
+        }
+        return resolvedInputs;
+    }
+    /**
+     * Execute a step with retry logic.
+     */
+    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 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);
+                    this.events.onStepComplete?.(step, result);
+                    return result;
+                }
+            }
+            // 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 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
+                );
+                this.events.onStepComplete?.(step, result);
+                return result;
+            }
+        }
+        // Regular action step - ensure action is defined
+        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) {
+            circuitBreaker = new CircuitBreaker();
+            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 };
+                // Execute step with executor context
+                const output = await this.executeWithTimeout(() => stepExecutor(stepWithResolvedInputs, context, sdkRegistry, executorContext), step.timeout ?? this.config.defaultTimeout);
+                circuitBreaker.recordSuccess();
+                const result = createStepResult(step.id, StepStatus.COMPLETED, output, startedAt, attempt);
+                this.events.onStepComplete?.(step, result);
+                return result;
+            }
+            catch (error) {
+                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.
+        );
+        this.events.onStepComplete?.(step, result);
+        return result;
+    }
+    /**
+     * Execute a step with retry + failover support.
+     */
+    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;
+        }
+        const [primaryTool, ...methodParts] = step.action.split('.');
+        const method = methodParts.join('.');
+        if (primaryResult.status === StepStatus.COMPLETED) {
+            this.healthTracker.markHealthy(primaryTool);
+            return primaryResult;
+        }
+        const errorMessage = primaryResult.error ? errorToString(primaryResult.error) : '';
+        const isTimeout = errorMessage.includes('timed out');
+        if (isTimeout && !this.failoverConfig.failoverOnTimeout) {
+            this.healthTracker.markUnhealthy(primaryTool, errorMessage);
+            return primaryResult;
+        }
+        if (!isTimeout && !this.failoverConfig.failoverOnStepFailure) {
+            this.healthTracker.markUnhealthy(primaryTool, errorMessage);
+            return primaryResult;
+        }
+        if (!method || this.failoverConfig.fallbackAgents.length === 0) {
+            this.healthTracker.markUnhealthy(primaryTool, errorMessage);
+            return primaryResult;
+        }
+        let attempts = 0;
+        for (const fallbackTool of this.failoverConfig.fallbackAgents) {
+            if (fallbackTool === primaryTool)
+                continue;
+            if (attempts >= this.failoverConfig.maxFailoverAttempts)
+                break;
+            const fallbackStep = { ...step, action: `${fallbackTool}.${method}`, type: 'action' };
+            const result = await this.executeStepWithRetry(fallbackStep, context, sdkRegistry, stepExecutor);
+            this.failoverEvents.push({
+                timestamp: new Date(),
+                fromAgent: primaryTool,
+                toAgent: fallbackTool,
+                reason: isTimeout ? FailoverReason.TIMEOUT : FailoverReason.STEP_EXECUTION_FAILED,
+                stepIndex: context.currentStepIndex,
+                error: errorMessage || undefined,
+            });
+            attempts += 1;
+            if (result.status === StepStatus.COMPLETED) {
+                this.healthTracker.markHealthy(fallbackTool);
+                return result;
+            }
+        }
+        this.healthTracker.markUnhealthy(primaryTool, errorMessage);
+        return primaryResult;
+    }
+    /**
+     * Execute a function with a timeout.
+     */
+    async executeWithTimeout(fn, timeoutMs) {
+        return Promise.race([
+            fn(),
+            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.
+     */
+    resolveConditionValue(path, context) {
+        // 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,
+            runId: context.runId,
+            status: context.status,
+            stepResults,
+            output,
+            error,
+            startedAt,
+            completedAt,
+            duration: completedAt.getTime() - startedAt.getTime(),
+        };
+    }
+    /**
+     * Reset all circuit breakers.
+     */
+    resetCircuitBreakers() {
+        for (const breaker of this.circuitBreakers.values()) {
+            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.
+     */
+    async executeForEachStep(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');
+            }
+            if (items.length === 0) {
+                return createStepResult(step.id, StepStatus.SKIPPED, [], startedAt);
+            }
+            // Execute steps for each item
+            const results = [];
+            for (let i = 0; i < items.length; i++) {
+                // Inject loop variables
+                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') {
+                            // Clean up loop variables
+                            delete context.variables[step.itemVariable];
+                            delete context.variables['loop'];
+                            if (step.indexVariable)
+                                delete context.variables[step.indexVariable];
+                            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, result.error);
+                        }
+                        // 'continue' - skip to next iteration
+                        break;
+                    }
+                }
+                results.push(context.variables[step.itemVariable]);
+            }
+            // Clean up loop variables
+            delete context.variables[step.itemVariable];
+            delete context.variables['loop'];
+            if (step.indexVariable)
+                delete context.variables[step.indexVariable];
+            return createStepResult(step.id, StepStatus.COMPLETED, results, startedAt);
+        }
+        catch (error) {
+            // Clean up loop variables on error
+            delete context.variables[step.itemVariable];
+            delete context.variables['loop'];
+            if (step.indexVariable)
+                delete context.variables[step.indexVariable];
+            return createStepResult(step.id, StepStatus.FAILED, null, startedAt, 0, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * 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));
+        }
+    }
+    // ============================================================================
+    // Helper Methods for Control Flow
+    // ============================================================================
+    /**
+     * Clone execution context for parallel branches.
+     */
+    cloneContext(context) {
+        return {
+            ...context,
+            variables: { ...context.variables },
+            inputs: { ...context.inputs },
+            stepMetadata: { ...context.stepMetadata },
+        };
+    }
+    /**
+     * 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;
+        }
+    }
+    /**
+     * Execute promises with concurrency limit.
+     */
+    async executeConcurrentlyWithLimit(promises, limit) {
+        const results = [];
+        const executing = [];
+        for (const promise of promises) {
+            const p = promise.then((result) => {
+                results.push(result);
+            });
+            executing.push(p);
+            if (executing.length >= limit) {
+                await Promise.race(executing);
+                executing.splice(executing.findIndex((x) => x === p), 1);
+            }
+        }
+        await Promise.all(executing);
+        return results;
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=engine.js.map