@runflow-ai/sdk 1.0.86 → 1.0.88

package/dist/workflows/workflow.js

@@ -1,20 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkflowBuilder = exports.Workflow = void 0;
+exports.FlowBuilder = exports.WorkflowBuilder = exports.Workflow = void 0;
 exports.createWorkflow = createWorkflow;
 exports.createStep = createStep;
 exports.createAgentStep = createAgentStep;
 exports.createFunctionStep = createFunctionStep;
 exports.createConnectorStep = createConnectorStep;
+exports.flow = flow;
+const events_1 = require("events");
 const agent_1 = require("../core/agent");
 const api_client_1 = require("../core/api-client");
 const trace_collector_1 = require("../observability/trace-collector");
+const logger_1 = require("../core/logger");
+const performance_logger_1 = require("../core/performance-logger");
+const context_1 = require("../core/context");
 // ============================================================================
 // WORKFLOW CLASS
 // ============================================================================
-class Workflow {
+class Workflow extends events_1.EventEmitter {
     constructor(config) {
+        super();
         this.config = config;
+        this.logger = (0, logger_1.createLogger)({ name: `workflow:${config.id}`, level: this.resolveLogLevel() });
         // Auto-initialize API client when used directly as SDK (outside execution engine)
         if (!this.apiClient) {
             const apiClient = (0, api_client_1.createRunflowAPIClient)();
@@ -34,6 +41,20 @@ class Workflow {
             flushInterval: 1000,
         });
     }
+    // Resolve log level from environment
+    resolveLogLevel() {
+        if (process.env.RUNFLOW_LOG_LEVEL) {
+            return process.env.RUNFLOW_LOG_LEVEL;
+        }
+        return process.env.NODE_ENV === 'production' ? 'info' : 'debug';
+    }
+    // Save result to both stepResults Map and results plain object
+    saveResult(context, stepId, result) {
+        context.stepResults.set(stepId, result);
+        if (context.results) {
+            context.results[stepId] = result;
+        }
+    }
     // Executar workflow
     async execute(input) {
         if (!this.apiClient) {
@@ -41,13 +62,18 @@ class Workflow {
         }
         // Validar input
         const validatedInput = this.config.inputSchema.parse(input);
+        // Resolve execution ID: prefer Runflow global state, fallback to generated
+        const globalExecId = context_1.Runflow.getState().executionId;
+        const executionId = globalExecId || `wf_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+        // Plain object for V2 FlowContext results
+        const resultsObj = {};
         // Criar contexto de execução
-        const executionId = `wf_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
         const context = {
             workflowId: this.config.id,
             executionId,
             input: validatedInput,
             stepResults: new Map(),
+            results: resultsObj,
             currentStep: '',
             metadata: {
                 startTime: new Date(),
@@ -57,8 +83,9 @@ class Workflow {
             },
             runflowAPI: this.apiClient,
         };
-        console.log(`🔄 Starting workflow: ${this.config.id} (${executionId})`);
-        // 🔍 Trace: Workflow Execution
+        this.logger.info({ workflowId: this.config.id, executionId }, `Starting workflow: ${this.config.id} (${executionId})`);
+        this.emit('workflow:start', { workflowId: this.config.id, executionId, input: validatedInput });
+        // Trace: Workflow Execution
         const workflowStartTime = Date.now();
         const workflowSpan = this.traceCollector?.startSpan('workflow_execution', {
             workflowId: this.config.id,
@@ -77,12 +104,13 @@ class Workflow {
                 context.metadata.currentTime = new Date();
                 // Verificar condição se existir (antes de contar como executado)
                 if (step.condition && !step.condition(context)) {
-                    console.log(`  ⏭️  Step skipped: ${step.id} (condition not met)`);
+                    this.logger.debug({ stepId: step.id }, `Step skipped: ${step.id} (condition not met)`);
+                    this.emit('step:skip', { stepId: step.id, reason: 'condition not met' });
                     continue;
                 }
                 context.metadata.stepCount++;
-                console.log(`  📍 Executing step: ${step.id} (${step.type})`);
-                // 🔍 Trace: Workflow Step (child of workflow_execution)
+                this.logger.debug({ stepId: step.id, stepType: step.type }, `Executing step: ${step.id} (${step.type})`);
+                // Trace: Workflow Step (child of workflow_execution)
                 const stepStartTime = Date.now();
                 const stepSpan = this.traceCollector?.startSpan('workflow_step', {
                     workflowId: this.config.id,
@@ -90,20 +118,23 @@ class Workflow {
                     stepType: step.type,
                     stepNumber: context.metadata.stepCount,
                     totalSteps: this.config.steps.length,
-                }, workflowSpanId); // ✅ Child of workflow_execution
+                }, workflowSpanId);
                 stepSpan?.setInput(currentInput);
+                this.emit('step:start', { stepId: step.id, stepType: step.type, input: currentInput });
                 // Executar step com retry se configurado
                 let stepResult;
                 try {
-                    if (step.retryConfig) {
-                        stepResult = await this.executeStepWithRetry(step, currentInput, context);
-                    }
-                    else {
-                        stepResult = await this.executeStep(step, currentInput, context);
-                    }
-                    // Armazenar resultado
-                    context.stepResults.set(step.id, stepResult);
-                    // 🔍 Finalizar trace do step
+                    stepResult = await performance_logger_1.performanceLogger.measure(`workflow:${this.config.id}:step:${step.id}`, async () => {
+                        if (step.retryConfig) {
+                            return this.executeStepWithRetry(step, currentInput, context);
+                        }
+                        else {
+                            return this.executeStep(step, currentInput, context);
+                        }
+                    }, { stepType: step.type });
+                    // Armazenar resultado (both Map and plain object)
+                    this.saveResult(context, step.id, stepResult);
+                    // Finalizar trace do step
                     stepSpan?.setOutput(stepResult);
                     stepSpan?.setMetadata({
                         workflowId: this.config.id,
@@ -125,10 +156,11 @@ class Workflow {
                     else {
                         currentInput = stepResult;
                     }
-                    console.log(`  ✅ Step completed: ${step.id}`);
+                    this.logger.debug({ stepId: step.id }, `Step completed: ${step.id}`);
+                    this.emit('step:complete', { stepId: step.id, output: stepResult, durationMs: Date.now() - stepStartTime });
                 }
                 catch (stepError) {
-                    // 🔍 Trace de erro do step
+                    // Trace de erro do step
                     stepSpan?.setMetadata({
                         workflowId: this.config.id,
                         stepId: step.id,
@@ -139,6 +171,7 @@ class Workflow {
                         error: stepError instanceof Error ? stepError.message : 'Unknown error',
                     });
                     stepSpan?.finish();
+                    this.emit('step:error', { stepId: step.id, error: stepError instanceof Error ? stepError.message : 'Unknown error' });
                     throw stepError;
                 }
             }
@@ -158,7 +191,7 @@ class Workflow {
                 };
             // Validar output final
             const finalOutput = this.config.outputSchema.parse(workflowOutput);
-            // 🔍 Finalizar trace do workflow
+            // Finalizar trace do workflow
             workflowSpan?.setOutput({
                 stepsExecuted: context.metadata.stepCount,
                 totalSteps: this.config.steps.length,
@@ -175,12 +208,13 @@ class Workflow {
             workflowSpan?.finish();
             // Forçar flush dos traces
             await this.traceCollector?.flush();
-            console.log(`🎉 Workflow completed: ${this.config.id}`);
+            this.logger.info({ workflowId: this.config.id, executionId }, `Workflow completed: ${this.config.id}`);
+            this.emit('workflow:complete', { executionId, output: finalOutput, durationMs: Date.now() - workflowStartTime });
             return finalOutput;
         }
         catch (error) {
-            console.error(`❌ Workflow failed: ${this.config.id}`, error);
-            // 🔍 Trace de erro do workflow
+            this.logger.error({ workflowId: this.config.id, executionId, err: error }, `Workflow failed: ${this.config.id}`);
+            // Trace de erro do workflow
             workflowSpan?.setMetadata({
                 workflowId: this.config.id,
                 workflowName: this.config.name || this.config.id,
@@ -193,6 +227,7 @@ class Workflow {
             });
             workflowSpan?.finish();
             await this.traceCollector?.flush();
+            this.emit('workflow:error', { executionId, error: error instanceof Error ? error.message : 'Unknown error', durationMs: Date.now() - workflowStartTime });
             throw error;
         }
     }
@@ -209,6 +244,10 @@ class Workflow {
                 return this.executeConditionStep(step.config, input, context);
             case 'parallel':
                 return this.executeParallelStep(step.config, input, context);
+            case 'switch':
+                return this.executeSwitchStep(step.config, input, context);
+            case 'foreach':
+                return this.executeForeachStep(step.config, input, context);
             default:
                 throw new Error(`Unknown step type: ${step.type}`);
         }
@@ -230,7 +269,7 @@ class Workflow {
                 }
                 if (attempt < retryConfig.maxAttempts) {
                     const delay = this.calculateRetryDelay(retryConfig, attempt);
-                    console.log(`  🔄 Retry ${attempt}/${retryConfig.maxAttempts} in ${delay}ms: ${step.id}`);
+                    this.logger.info({ stepId: step.id, attempt, maxAttempts: retryConfig.maxAttempts, delay }, `Retry ${attempt}/${retryConfig.maxAttempts} in ${delay}ms: ${step.id}`);
                     await new Promise(resolve => setTimeout(resolve, delay));
                 }
             }
@@ -268,6 +307,7 @@ class Workflow {
             prompt = this.interpolateTemplate(config.promptTemplate, {
                 input,
                 context: Object.fromEntries(context.stepResults),
+                results: context.results || Object.fromEntries(context.stepResults),
                 workflow: { id: context.workflowId, step: context.currentStep }
             });
         }
@@ -285,7 +325,8 @@ class Workflow {
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            throw new Error(`Agent step failed [${agent.name}/${agent.model}] at step "${context.currentStep}": ${err.message}`);
+            err.message = `Agent step failed [${agent.name}/${agent.model}] at step "${context.currentStep}": ${err.message}`;
+            throw err;
         }
     }
     // Executar function step
@@ -294,8 +335,16 @@ class Workflow {
         if (config.inputSchema) {
             input = config.inputSchema.parse(input);
         }
-        // Executar função
-        const result = await config.execute(input, context);
+        // Executar funcao
+        let result;
+        try {
+            result = await config.execute(input, context);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            err.message = `Function step failed at "${context.currentStep}": ${err.message}`;
+            throw err;
+        }
         // Validar output se schema fornecido
         if (config.outputSchema) {
             return config.outputSchema.parse(result);
@@ -311,17 +360,27 @@ class Workflow {
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            throw new Error(`Connector step failed [${config.connector}/${config.resource}/${config.action}]: ${err.message}`);
+            err.message = `Connector step failed [${config.connector}/${config.resource}/${config.action}] at step "${context.currentStep}": ${err.message}`;
+            throw err;
         }
     }
     // Executar condition step
     async executeConditionStep(config, input, context) {
-        const condition = config.condition(context);
+        let condition;
+        try {
+            condition = config.condition(context);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            err.message = `Condition evaluation failed at "${context.currentStep}": ${err.message}`;
+            throw err;
+        }
         const pathSteps = condition ? config.truePath : (config.falsePath || []);
         // Executar steps do path escolhido
         let currentInput = input;
         for (const step of pathSteps) {
             currentInput = await this.executeStep(step, currentInput, context);
+            this.saveResult(context, step.id, currentInput);
         }
         // Quando unwrapResult=true, retorna apenas o resultado interno (mais natural para downstream)
         if (config.unwrapResult) {
@@ -335,16 +394,22 @@ class Workflow {
     }
     // Executar parallel step
     async executeParallelStep(config, input, context) {
+        if (!Array.isArray(config.steps)) {
+            throw new Error(`Parallel step "${context.currentStep}" requires an array of steps. ` +
+                `Use: .parallel('id', [createFunctionStep('a', handler), createFunctionStep('b', handler)])`);
+        }
         const promises = config.steps.map(step => this.executeStep(step, input, context));
         if (config.waitForAll !== false) {
             // Aguardar todos completarem
             const results = await Promise.all(promises);
+            const resultsMap = {};
+            config.steps.forEach((step, i) => {
+                resultsMap[step.id] = results[i];
+                this.saveResult(context, step.id, results[i]);
+            });
             return {
                 type: 'parallel',
-                results: results.reduce((acc, result, index) => {
-                    acc[config.steps[index].id] = result;
-                    return acc;
-                }, {}),
+                results: resultsMap,
             };
         }
         else {
@@ -359,6 +424,92 @@ class Workflow {
             };
         }
     }
+    // Executar switch step
+    async executeSwitchStep(config, input, context) {
+        if (typeof config.evaluate !== 'function') {
+            const wrongKey = Object.keys(config).find(k => typeof config[k] === 'function' && k !== 'evaluate');
+            throw new Error(`Switch step "${context.currentStep}": missing "on" property. ` +
+                (wrongKey ? `Did you mean "on" instead of "${wrongKey}"? ` : '') +
+                `Use: .switch('id', { on: (ctx) => ctx.results.step.value, cases: { ... } })`);
+        }
+        const value = config.evaluate(context);
+        const handler = config.cases[value] ?? config.defaultCase;
+        if (!handler) {
+            throw new Error(`Switch step: no case matched for "${value}" and no default provided. Available cases: [${Object.keys(config.cases).join(', ')}]`);
+        }
+        this.logger.debug({ switchValue: value }, `Switch routing: "${value}"`);
+        let result;
+        try {
+            if (Array.isArray(handler)) {
+                let currentInput = input;
+                for (const step of handler) {
+                    currentInput = await this.executeStep(step, currentInput, context);
+                    this.saveResult(context, step.id, currentInput);
+                }
+                result = currentInput;
+            }
+            else {
+                result = await handler(input, context);
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            err.message = `Switch step failed at "${context.currentStep}" (case "${value}"): ${err.message}`;
+            throw err;
+        }
+        if (config.unwrapResult ?? true) {
+            return result;
+        }
+        return { switchValue: value, caseTaken: config.cases[value] ? value : 'default', result };
+    }
+    // Executar foreach step
+    async executeForeachStep(config, input, context) {
+        if (typeof config.handler !== 'function') {
+            throw new Error(`Foreach step "${context.currentStep}": missing "handler" function. ` +
+                `Use: .foreach('id', { handler: async (item) => ({ ...item, processed: true }) })`);
+        }
+        if (!Array.isArray(input)) {
+            this.logger.warn({ stepId: context.currentStep, inputType: typeof input }, `Foreach step "${context.currentStep}" received non-array input (${typeof input}). ` +
+                `The previous step must return an array. Use .map() to extract the array first.`);
+            return [];
+        }
+        const items = input;
+        if (items.length === 0)
+            return [];
+        const concurrency = config.concurrency || 1;
+        const handleItem = async (item, itemIndex) => {
+            try {
+                return await config.handler(item, context);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                err.message = `Foreach step failed at "${context.currentStep}" (item ${itemIndex}): ${err.message}`;
+                throw err;
+            }
+        };
+        if (concurrency === 1) {
+            const results = [];
+            for (let i = 0; i < items.length; i++) {
+                results.push(await handleItem(items[i], i));
+            }
+            return results;
+        }
+        // Concurrent with limit.
+        // The shared `index` variable is safe because Node.js is single-threaded:
+        // `index++` (read + increment) completes synchronously before the `await`,
+        // so no two workers can read the same index value.
+        const results = new Array(items.length);
+        let index = 0;
+        const runNext = async () => {
+            while (index < items.length) {
+                const currentIndex = index++;
+                results[currentIndex] = await handleItem(items[currentIndex], currentIndex);
+            }
+        };
+        const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => runNext());
+        await Promise.all(workers);
+        return results;
+    }
     // Interpolar template com variáveis
     interpolateTemplate(template, variables) {
         return template.replace(/\{\{([\w-]+(?:\.[\w-]+)*)\}\}/g, (match, path) => {
@@ -391,6 +542,231 @@ class Workflow {
     getNestedValue(obj, path) {
         return path.split('.').reduce((current, key) => current?.[key], obj);
     }
+    // ============================================================================
+    // GRAPH GENERATION
+    // ============================================================================
+    toGraph() {
+        const nodes = [];
+        const edges = [];
+        let previousExitNodes = [];
+        for (const step of this.config.steps) {
+            const entryNodes = this.addStepToGraph(step, nodes, edges);
+            // Connect previous step's exit nodes to this step's entry nodes
+            for (const prev of previousExitNodes) {
+                for (const entry of entryNodes) {
+                    edges.push({ source: prev, target: entry });
+                }
+            }
+            previousExitNodes = this.getExitNodes(step);
+        }
+        return { id: this.config.id, name: this.config.name || this.config.id, nodes, edges };
+    }
+    /**
+     * Adds a step (and its sub-steps) to the graph. Returns the entry node IDs.
+     */
+    addStepToGraph(step, nodes, edges) {
+        const nodeType = this.stepTypeToNodeType(step.type);
+        if (step.type === 'condition') {
+            const config = step.config;
+            // Add the branch decision node
+            nodes.push({
+                id: step.id,
+                type: nodeType,
+                label: step.name || step.id,
+                ...(step.description && { metadata: { description: step.description } }),
+            });
+            // True path sub-nodes
+            let prevIds = [step.id];
+            for (const sub of config.truePath) {
+                const subEntries = this.addStepToGraph(sub, nodes, edges);
+                for (const prev of prevIds) {
+                    for (const entry of subEntries) {
+                        edges.push({
+                            source: prev,
+                            target: entry,
+                            label: prev === step.id ? 'true' : undefined,
+                        });
+                    }
+                }
+                prevIds = this.getExitNodes(sub);
+            }
+            // False path sub-nodes
+            if (config.falsePath && config.falsePath.length > 0) {
+                let falsePrevIds = [step.id];
+                for (const sub of config.falsePath) {
+                    const subEntries = this.addStepToGraph(sub, nodes, edges);
+                    for (const prev of falsePrevIds) {
+                        for (const entry of subEntries) {
+                            edges.push({
+                                source: prev,
+                                target: entry,
+                                label: prev === step.id ? 'false' : undefined,
+                            });
+                        }
+                    }
+                    falsePrevIds = this.getExitNodes(sub);
+                }
+            }
+            return [step.id];
+        }
+        if (step.type === 'switch') {
+            const config = step.config;
+            nodes.push({
+                id: step.id,
+                type: nodeType,
+                label: step.name || step.id,
+                ...(step.description && { metadata: { description: step.description } }),
+            });
+            // Add case nodes
+            for (const [caseName, handler] of Object.entries(config.cases)) {
+                if (Array.isArray(handler)) {
+                    // handler is WorkflowStep[]
+                    let prevIds = [step.id];
+                    for (const sub of handler) {
+                        const subEntries = this.addStepToGraph(sub, nodes, edges);
+                        for (const prev of prevIds) {
+                            for (const entry of subEntries) {
+                                edges.push({
+                                    source: prev,
+                                    target: entry,
+                                    label: prev === step.id ? caseName : undefined,
+                                });
+                            }
+                        }
+                        prevIds = this.getExitNodes(sub);
+                    }
+                }
+                else {
+                    // handler is a function — create virtual node
+                    const virtualId = `${step.id}:${caseName}`;
+                    nodes.push({ id: virtualId, type: 'function', label: caseName });
+                    edges.push({ source: step.id, target: virtualId, label: caseName });
+                }
+            }
+            // Default case
+            if (config.defaultCase) {
+                if (Array.isArray(config.defaultCase)) {
+                    let prevIds = [step.id];
+                    for (const sub of config.defaultCase) {
+                        const subEntries = this.addStepToGraph(sub, nodes, edges);
+                        for (const prev of prevIds) {
+                            for (const entry of subEntries) {
+                                edges.push({
+                                    source: prev,
+                                    target: entry,
+                                    label: prev === step.id ? 'default' : undefined,
+                                });
+                            }
+                        }
+                        prevIds = this.getExitNodes(sub);
+                    }
+                }
+                else {
+                    const virtualId = `${step.id}:default`;
+                    nodes.push({ id: virtualId, type: 'function', label: 'default' });
+                    edges.push({ source: step.id, target: virtualId, label: 'default' });
+                }
+            }
+            return [step.id];
+        }
+        if (step.type === 'parallel') {
+            const config = step.config;
+            // Add container node
+            nodes.push({
+                id: step.id,
+                type: nodeType,
+                label: step.name || step.id,
+                ...(step.description && { metadata: { description: step.description } }),
+            });
+            // Add child nodes
+            for (const sub of config.steps) {
+                const subEntries = this.addStepToGraph(sub, nodes, edges);
+                for (const entry of subEntries) {
+                    edges.push({ source: step.id, target: entry });
+                }
+            }
+            return [step.id];
+        }
+        // Simple step (function, agent, connector, foreach)
+        nodes.push({
+            id: step.id,
+            type: nodeType,
+            label: step.name || step.id,
+            ...(step.description && { metadata: { description: step.description } }),
+        });
+        return [step.id];
+    }
+    /**
+     * Maps step type to GraphNode type. 'function' becomes 'step' for display purposes,
+     * but we keep the original type for graph fidelity.
+     */
+    stepTypeToNodeType(type) {
+        return type;
+    }
+    /**
+     * Returns the IDs of nodes that "exit" a complex step — i.e., the last nodes
+     * in each branch that need to connect to the next sequential step.
+     */
+    getExitNodes(step) {
+        if (step.type === 'condition') {
+            const config = step.config;
+            const exits = [];
+            if (config.truePath.length > 0) {
+                const last = config.truePath[config.truePath.length - 1];
+                exits.push(...this.getExitNodes(last));
+            }
+            else {
+                exits.push(step.id);
+            }
+            if (config.falsePath && config.falsePath.length > 0) {
+                const last = config.falsePath[config.falsePath.length - 1];
+                exits.push(...this.getExitNodes(last));
+            }
+            else {
+                exits.push(step.id);
+            }
+            return exits;
+        }
+        if (step.type === 'switch') {
+            const config = step.config;
+            const exits = [];
+            for (const [caseName, handler] of Object.entries(config.cases)) {
+                if (Array.isArray(handler) && handler.length > 0) {
+                    const last = handler[handler.length - 1];
+                    exits.push(...this.getExitNodes(last));
+                }
+                else if (!Array.isArray(handler)) {
+                    exits.push(`${step.id}:${caseName}`);
+                }
+                else {
+                    exits.push(step.id);
+                }
+            }
+            if (config.defaultCase) {
+                if (Array.isArray(config.defaultCase) && config.defaultCase.length > 0) {
+                    const last = config.defaultCase[config.defaultCase.length - 1];
+                    exits.push(...this.getExitNodes(last));
+                }
+                else if (!Array.isArray(config.defaultCase)) {
+                    exits.push(`${step.id}:default`);
+                }
+                else {
+                    exits.push(step.id);
+                }
+            }
+            return exits;
+        }
+        if (step.type === 'parallel') {
+            const config = step.config;
+            const exits = [];
+            for (const sub of config.steps) {
+                exits.push(...this.getExitNodes(sub));
+            }
+            return exits.length > 0 ? exits : [step.id];
+        }
+        // Simple step
+        return [step.id];
+    }
     // Getters
     get id() {
         return this.config.id;
@@ -488,7 +864,7 @@ class WorkflowBuilder {
         return this.then(parallelStep);
     }
     // Adicionar conditional step
-    condition(id, condition, truePath, falsePath) {
+    condition(id, condition, truePath, falsePath, options) {
         const conditionStep = {
             id,
             type: 'condition',
@@ -496,6 +872,7 @@ class WorkflowBuilder {
                 condition,
                 truePath,
                 falsePath,
+                unwrapResult: options?.unwrap,
             },
         };
         return this.then(conditionStep);
@@ -520,6 +897,163 @@ class WorkflowBuilder {
 }
 exports.WorkflowBuilder = WorkflowBuilder;
 // ============================================================================
+// FLOW BUILDER (V2 Fluent API)
+// ============================================================================
+class FlowBuilder {
+    constructor(config) {
+        this.steps = [];
+        this.stepCounter = 0;
+        this.config = config;
+    }
+    nextId(prefix) {
+        return `${prefix}_${++this.stepCounter}`;
+    }
+    step(id, handlerOrOpts) {
+        let handler;
+        let opts = {};
+        if (typeof handlerOrOpts === 'function') {
+            handler = handlerOrOpts;
+        }
+        else {
+            handler = handlerOrOpts.handler;
+            opts = handlerOrOpts;
+        }
+        const step = {
+            id,
+            type: 'function',
+            config: {
+                execute: handler,
+                outputSchema: opts.outputSchema,
+            },
+            condition: opts.condition,
+            retryConfig: opts.retryConfig,
+            inputTransform: opts.inputTransform,
+            outputTransform: opts.outputTransform,
+        };
+        this.steps.push(step);
+        return this;
+    }
+    agent(id, agent, opts) {
+        const step = {
+            id,
+            type: 'agent',
+            config: {
+                agent,
+                prompt: opts?.prompt,
+                promptTemplate: opts?.promptTemplate,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    branch(id, opts) {
+        const step = {
+            id,
+            type: 'condition',
+            config: {
+                condition: opts.condition,
+                truePath: this.toBranchPath(`${id}_true`, opts.onTrue),
+                falsePath: opts.onFalse ? this.toBranchPath(`${id}_false`, opts.onFalse) : undefined,
+                unwrapResult: opts.unwrap ?? true,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    switch(id, opts) {
+        const step = {
+            id,
+            type: 'switch',
+            config: {
+                evaluate: opts.on,
+                cases: opts.cases,
+                defaultCase: opts.default,
+                unwrapResult: opts.unwrap ?? true,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    map(transform) {
+        if (typeof transform !== 'function') {
+            throw new Error(`.map() expects a transform function, not ${typeof transform}. ` +
+                `Use: .map((output) => output.items) — no ID parameter, no ctx.`);
+        }
+        const id = this.nextId('map');
+        const step = {
+            id,
+            type: 'function',
+            config: {
+                execute: async (input) => transform(input),
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    foreach(id, opts) {
+        const step = {
+            id,
+            type: 'foreach',
+            config: {
+                handler: opts.handler,
+                concurrency: opts.concurrency,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    connector(id, connector, resource, action, parameters) {
+        const step = {
+            id,
+            type: 'connector',
+            config: {
+                connector,
+                resource,
+                action,
+                parameters,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    parallel(id, steps, opts) {
+        const step = {
+            id,
+            type: 'parallel',
+            config: {
+                steps,
+                waitForAll: opts?.waitForAll,
+                maxConcurrency: opts?.maxConcurrency,
+            },
+        };
+        this.steps.push(step);
+        return this;
+    }
+    output(transform) {
+        this.config = { ...this.config, outputTransform: transform };
+        return this;
+    }
+    build() {
+        return new Workflow({ ...this.config, steps: this.steps });
+    }
+    toBranchPath(defaultId, handlerOrSteps) {
+        if (Array.isArray(handlerOrSteps)) {
+            return handlerOrSteps;
+        }
+        return [{
+                id: defaultId,
+                type: 'function',
+                config: {
+                    execute: handlerOrSteps,
+                },
+            }];
+    }
+}
+exports.FlowBuilder = FlowBuilder;
+function flow(config) {
+    return new FlowBuilder(config);
+}
+// ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
 function inferStepType(config) {
@@ -527,6 +1061,10 @@ function inferStepType(config) {
         return 'agent';
     if ('execute' in config)
         return 'function';
+    if ('evaluate' in config)
+        return 'switch';
+    if ('handler' in config && !('execute' in config))
+        return 'foreach';
     if ('connector' in config)
         return 'connector';
     if ('condition' in config)