@xyne/workflow-sdk 3.2.36 → 3.2.38

package/dist/connectors/builtin/steps/parallel.step.js

@@ -0,0 +1,175 @@
+/**
+ * PARALLEL step — fan-out N named branches concurrently and collect results.
+ *
+ * BaseControlFlowStep with N dynamic branches. Runs all in parallel via
+ * Promise.allSettled or Promise.race depending on `merge` mode.
+ *
+ * Each branch gets an isolated copy of the workflow context so concurrent
+ * writes to `context.steps` don't conflict. After completion, the last
+ * step's output from each branch is collected into the parallel step's output.
+ *
+ * ## Pause handling (allSettled)
+ *
+ * Each branch runs in its own scope and persists its steps under node-path keys
+ * (`parallel_x:<branch>#0/<stepId>`). When a branch parks, its `walkBranch`
+ * throws `PauseStep`; PARALLEL collects which branches paused and, if any did,
+ * throws a single `PauseStep` so the whole step parks. There is no internal
+ * saved state — the per-branch step records ARE the durable state. On resume
+ * the executor re-enters PARALLEL, re-runs every branch via `walkBranch`:
+ * completed branch steps memo-skip from their records, the parked one(s) resume
+ * from theirs. Multiple branches can be paused simultaneously; each `resume()`
+ * targets one branch's gate by node-path. When the last paused branch
+ * completes, PARALLEL merges everything and returns.
+ *
+ * ## Output
+ *
+ * Discriminated union on `mode` so consumers (including the UI)
+ * can switch on `mode` and get full type safety for each case:
+ *
+ *   allSettled: { mode: 'allSettled', branches: { [name]: { status, value?, reason? } } }
+ *   race:       { mode: 'race',       winner: string, result: { output } }
+ */
+import { z } from 'zod';
+import { BaseControlFlowStep, collectBranchSteps, cloneScope } from '../../../steps/base-step.js';
+import { BuiltinStepType } from '../../../types/known-types.js';
+import { PauseStep } from '../../../engine/pause-step.js';
+// ─── Config ───
+export const ParallelStepConfigSchema = z.object({
+    branches: z.record(z.string(), z.array(z.object({ id: z.string(), type: z.string() }).passthrough())).describe('Named branches that execute concurrently. Each key is a branch name, value is the steps to run'),
+    merge: z.enum(['allSettled', 'race']).default('allSettled').describe('How to combine branch results: allSettled waits for all, race returns first completed'),
+});
+// ─── Output Zod schema (for validation / introspection) ───
+const StepOutputMapSchema = z.record(z.object({ output: z.record(z.unknown()) }));
+const ParallelSettledBranchResultSchema = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('fulfilled'),
+        steps: StepOutputMapSchema,
+    }),
+    z.object({
+        status: z.literal('rejected'),
+        reason: z.string(),
+    }),
+]);
+const ParallelStepOutputSchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('allSettled'),
+        branches: z.record(ParallelSettledBranchResultSchema),
+    }),
+    z.object({
+        mode: z.literal('race'),
+        branch: z.string(),
+        branches: z.record(ParallelSettledBranchResultSchema),
+    }),
+]);
+// ─── Step ───
+export class ParallelStep extends BaseControlFlowStep {
+    type = BuiltinStepType.PARALLEL;
+    name = 'Parallel';
+    description = 'Run multiple branches concurrently and collect results';
+    configSchema = ParallelStepConfigSchema;
+    outputSchema = ParallelStepOutputSchema;
+    category = 'control';
+    icon = 'columns';
+    /**
+     * Declared outputs are dynamic — one per branch key.
+     * Since branch keys are user-defined, we return empty here and let
+     * `getBranches()` handle discovery for validation.
+     */
+    declaredOutputs = [];
+    getBranches(config) {
+        const branches = (config['branches'] ?? {});
+        const result = {};
+        for (const [key, steps] of Object.entries(branches)) {
+            result[key] = steps;
+        }
+        return result;
+    }
+    /**
+     * Collapse the static `mode` discriminated union to the *configured* mode, so
+     * the variable picker sees a concrete object (not an `anyOf`) it can drill.
+     * Only the mode-dependent meta is declared here; the harness
+     * (`resolveOutputJsonSchemaOf`) splices the typed `branches` from `getBranches`.
+     */
+    resolveOutputJsonSchema(config) {
+        const mode = config['merge'] === 'race' ? 'race' : 'allSettled';
+        const properties = { mode: { type: 'string', const: mode } };
+        if (mode === 'race')
+            properties['branch'] = { type: 'string' };
+        return { type: 'object', properties };
+    }
+    async execute(config, ctx) {
+        const branchEntries = Object.entries(config.branches);
+        if (branchEntries.length === 0) {
+            return { mode: config.merge, branches: {} };
+        }
+        if (config.merge === 'allSettled') {
+            return this.executeAllSettled(branchEntries, ctx);
+        }
+        // race
+        return this.executeRace(branchEntries, ctx);
+    }
+    // ─── Merge: allSettled ───
+    async executeAllSettled(branchEntries, ctx) {
+        // Run every branch concurrently, each in its own scope. Completed branch
+        // steps memo-skip on resume; the parked one(s) resume — handled entirely by
+        // the executor's node-path records, so no saved state lives here.
+        const settled = await Promise.allSettled(branchEntries.map(async ([name, steps]) => {
+            const branchCtx = cloneScope(ctx.workflow);
+            await ctx.walkBranch(steps, branchCtx, name);
+            return {
+                steps: collectBranchSteps(steps, branchCtx),
+            };
+        }));
+        const branches = {};
+        let pausedCount = 0;
+        let firstExternalRef;
+        for (let i = 0; i < branchEntries.length; i++) {
+            const name = branchEntries[i][0];
+            const entry = settled[i];
+            if (entry.status === 'fulfilled') {
+                branches[name] = { status: 'fulfilled', steps: entry.value.steps };
+            }
+            else if (PauseStep.is(entry.reason)) {
+                pausedCount++;
+                const pe = entry.reason;
+                if (firstExternalRef === undefined && pe.externalRef !== undefined) {
+                    firstExternalRef = pe.externalRef;
+                }
+            }
+            else {
+                branches[name] = {
+                    status: 'rejected',
+                    reason: entry.reason instanceof Error
+                        ? entry.reason.message
+                        : String(entry.reason),
+                };
+            }
+        }
+        // Any paused branch parks the whole step. The executor records PARALLEL as
+        // EXTERNAL_WAIT and re-enters it on resume; this throw discards the partial
+        // `branches` (the completed branches' outputs are durable in their records).
+        if (pausedCount > 0) {
+            const reason = pausedCount === 1 ? 'branch awaiting resume' : `${String(pausedCount)} branches paused`;
+            throw new PauseStep(reason, firstExternalRef !== undefined ? { externalRef: firstExternalRef } : undefined);
+        }
+        return { mode: 'allSettled', branches };
+    }
+    // ─── Merge: race ───
+    async executeRace(branchEntries, ctx) {
+        const promises = branchEntries.map(async ([name, steps]) => {
+            const branchCtx = cloneScope(ctx.workflow);
+            await ctx.walkBranch(steps, branchCtx, name);
+            return {
+                name,
+                steps: collectBranchSteps(steps, branchCtx),
+            };
+        });
+        const winner = await Promise.race(promises);
+        return {
+            mode: 'race',
+            branch: winner.name,
+            branches: { [winner.name]: { status: 'fulfilled', steps: winner.steps } },
+        };
+    }
+}
+//# sourceMappingURL=parallel.step.js.map

package/dist/connectors/builtin/steps/parallel.step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.step.js","sourceRoot":"","sources":["../../../../src/connectors/builtin/steps/parallel.step.ts"],"names":[],"mappings":"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"}

package/dist/connectors/builtin/steps/ssrf-guard.d.ts

@@ -0,0 +1,9 @@
+/** True if `ip` (a literal IPv4/IPv6) is in a blocked range. Non-IPs are blocked. */
+export declare function isBlockedIp(ip: string): boolean;
+/**
+ * Throw if `rawUrl` is not a safe public http(s) destination. Resolves DNS and
+ * checks every returned address so a hostname pointing at a private/metadata IP
+ * is rejected too. Call this for the initial URL AND every redirect target.
+ */
+export declare function assertPublicHttpUrl(rawUrl: string): Promise<void>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/connectors/builtin/steps/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../../../src/connectors/builtin/steps/ssrf-guard.ts"],"names":[],"mappings":"AAkEA,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK/C;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BvE"}

package/dist/connectors/builtin/steps/ssrf-guard.js

@@ -0,0 +1,115 @@
+/**
+ * SSRF guard for outbound HTTP (the HTTP_REQUEST step).
+ *
+ * A workflow author controls the request URL, so without validation the server
+ * can be turned into a proxy for internal services or — on a cloud VM — the
+ * instance metadata endpoint (169.254.169.254 / metadata.google.internal),
+ * which hands out service-account credentials. This module resolves the target
+ * host and refuses loopback / private / link-local / cloud-metadata addresses.
+ *
+ * Only http/https are allowed. Literal-IP and DNS-resolved addresses are both
+ * checked (basic resistance to a hostname that points at a private IP), and the
+ * step re-validates every redirect hop.
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const BLOCKED_HOSTNAMES = new Set(['metadata.google.internal', 'metadata', 'localhost']);
+function ipv4ToInt(ip) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+    if (!m)
+        return null;
+    let n = 0;
+    for (let i = 1; i <= 4; i += 1) {
+        const octet = Number(m[i]);
+        if (!Number.isInteger(octet) || octet < 0 || octet > 255)
+            return null;
+        n = n * 256 + octet;
+    }
+    return n >>> 0;
+}
+function inCidr(n, base, bits) {
+    const b = ipv4ToInt(base);
+    if (b === null)
+        return false;
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (n & mask) === (b & mask);
+}
+function isBlockedIpv4(ip) {
+    const n = ipv4ToInt(ip);
+    if (n === null)
+        return true; // unparseable → block
+    return (inCidr(n, '0.0.0.0', 8) || // "this" network
+        inCidr(n, '10.0.0.0', 8) || // private
+        inCidr(n, '100.64.0.0', 10) || // CGNAT
+        inCidr(n, '127.0.0.0', 8) || // loopback
+        inCidr(n, '169.254.0.0', 16) || // link-local incl. 169.254.169.254 metadata
+        inCidr(n, '172.16.0.0', 12) || // private
+        inCidr(n, '192.0.0.0', 24) || // IETF protocol assignments
+        inCidr(n, '192.168.0.0', 16) || // private
+        inCidr(n, '198.18.0.0', 15) || // benchmarking
+        inCidr(n, '224.0.0.0', 4) || // multicast
+        inCidr(n, '240.0.0.0', 4) // reserved
+    );
+}
+function isBlockedIpv6(ip) {
+    const addr = (ip.split('%')[0] ?? '').toLowerCase(); // strip zone id
+    if (addr === '::1' || addr === '::')
+        return true; // loopback / unspecified
+    if (addr.startsWith('fc') || addr.startsWith('fd'))
+        return true; // unique-local fc00::/7
+    // link-local fe80::/10 → first hextet fe80..febf
+    if (/^fe[89ab]/.test(addr))
+        return true;
+    const mapped = addr.match(/(?:^|:)(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/); // ::ffff:a.b.c.d
+    if (mapped && mapped[1])
+        return isBlockedIpv4(mapped[1]);
+    return false;
+}
+/** True if `ip` (a literal IPv4/IPv6) is in a blocked range. Non-IPs are blocked. */
+export function isBlockedIp(ip) {
+    const v = isIP(ip);
+    if (v === 4)
+        return isBlockedIpv4(ip);
+    if (v === 6)
+        return isBlockedIpv6(ip);
+    return true;
+}
+/**
+ * Throw if `rawUrl` is not a safe public http(s) destination. Resolves DNS and
+ * checks every returned address so a hostname pointing at a private/metadata IP
+ * is rejected too. Call this for the initial URL AND every redirect target.
+ */
+export async function assertPublicHttpUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`SSRF guard: invalid URL: ${rawUrl}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`SSRF guard: blocked scheme "${url.protocol}" (only http/https allowed)`);
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+    if (BLOCKED_HOSTNAMES.has(host.toLowerCase())) {
+        throw new Error(`SSRF guard: blocked host "${host}"`);
+    }
+    if (isIP(host)) {
+        if (isBlockedIp(host))
+            throw new Error(`SSRF guard: blocked address ${host}`);
+        return;
+    }
+    let addrs;
+    try {
+        addrs = await lookup(host, { all: true });
+    }
+    catch {
+        throw new Error(`SSRF guard: could not resolve host "${host}"`);
+    }
+    for (const a of addrs) {
+        if (isBlockedIp(a.address)) {
+            throw new Error(`SSRF guard: host "${host}" resolves to blocked address ${a.address}`);
+        }
+    }
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/connectors/builtin/steps/ssrf-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../../../../src/connectors/builtin/steps/ssrf-guard.ts"],"names":[],"mappings":"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"}

package/dist/connectors/builtin/steps/switch.step.d.ts

@@ -0,0 +1,235 @@
+/**
+ * SWITCH step — first-match-wins over an ordered list of conditional cases,
+ * with a guaranteed `default` fallback.
+ *
+ * Semantics (no fall-through):
+ *
+ *   for (const [i, c] of cases.entries())
+ *     if (evaluator.evaluate(c.condition, ctx.workflow)) {
+ *       walkBranch(c.steps, `case_${i}`)
+ *       return { branch: `case_${i}`, caseIndex: i, label: c.label ?? null }
+ *     }
+ *   walkBranch(default, 'default')
+ *   return { branch: 'default', caseIndex: null, label: null }
+ *
+ * Branch keys are positional (`case_0`, `case_1`, ..., `default`) so a
+ * paused execution's PausePath survives label edits.
+ */
+import { z } from 'zod';
+import { BaseControlFlowStep } from '../../../steps/base-step.js';
+import type { ControlFlowExecutionContext, BranchStepOutputs } from '../../../steps/base-step.js';
+import { BuiltinStepType } from '../../../types/known-types.js';
+import type { WorkflowStepConfig } from '../../../types/workflow-config.js';
+export declare const SwitchStepConfigSchema: z.ZodObject<{
+    cases: z.ZodArray<z.ZodObject<{
+        condition: z.ZodType<import("../../../types/workflow-config.js").Condition, z.ZodTypeDef, import("../../../types/workflow-config.js").Condition>;
+        label: z.ZodOptional<z.ZodString>;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        steps: z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+        condition: import("../../../types/workflow-config.js").Condition;
+        label?: string | undefined;
+    }, {
+        steps: z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+        condition: import("../../../types/workflow-config.js").Condition;
+        label?: string | undefined;
+    }>, "many">;
+    default: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, "strip", z.ZodTypeAny, {
+    cases: {
+        steps: z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+        condition: import("../../../types/workflow-config.js").Condition;
+        label?: string | undefined;
+    }[];
+    default: z.objectOutputType<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">[];
+}, {
+    cases: {
+        steps: z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+        condition: import("../../../types/workflow-config.js").Condition;
+        label?: string | undefined;
+    }[];
+    default: z.objectInputType<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">[];
+}>;
+export type SwitchStepConfig = z.infer<typeof SwitchStepConfigSchema>;
+export interface SwitchStepOutput extends Record<string, unknown> {
+    /** Which branch executed. `'default'` when no case matched. `case_<i>` (i = caseIndex) otherwise. */
+    branch: string;
+    /** Index of the matched case, or `null` when `default` ran. */
+    caseIndex: number | null;
+    /** Label of the matched case, or `null` when `default` ran (or case had no label). */
+    label: string | null;
+    /**
+     * The taken branch's top-level steps, keyed by branch key (`case_<i>`/`default`)
+     * then step id — referenced as `…output.branches.<key>.steps.<id>.output.<field>`.
+     * Only the taken branch is populated. The harness types all branches from `getBranches`.
+     */
+    branches: Record<string, {
+        steps: BranchStepOutputs;
+    }>;
+}
+export declare class SwitchStep extends BaseControlFlowStep<typeof SwitchStepConfigSchema, SwitchStepOutput> {
+    readonly type = BuiltinStepType.SWITCH;
+    readonly name = "Switch";
+    readonly description = "Route to one of N branches; first matching case wins, otherwise default";
+    readonly configSchema: z.ZodObject<{
+        cases: z.ZodArray<z.ZodObject<{
+            condition: z.ZodType<import("../../../types/workflow-config.js").Condition, z.ZodTypeDef, import("../../../types/workflow-config.js").Condition>;
+            label: z.ZodOptional<z.ZodString>;
+            steps: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            steps: z.objectOutputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+            condition: import("../../../types/workflow-config.js").Condition;
+            label?: string | undefined;
+        }, {
+            steps: z.objectInputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+            condition: import("../../../types/workflow-config.js").Condition;
+            label?: string | undefined;
+        }>, "many">;
+        default: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        cases: {
+            steps: z.objectOutputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+            condition: import("../../../types/workflow-config.js").Condition;
+            label?: string | undefined;
+        }[];
+        default: z.objectOutputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        cases: {
+            steps: z.objectInputType<{
+                id: z.ZodString;
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+            condition: import("../../../types/workflow-config.js").Condition;
+            label?: string | undefined;
+        }[];
+        default: z.objectInputType<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>;
+    readonly outputSchema: z.ZodObject<{
+        branch: z.ZodString;
+        caseIndex: z.ZodNullable<z.ZodNumber>;
+        label: z.ZodNullable<z.ZodString>;
+        branches: z.ZodRecord<z.ZodString, z.ZodObject<{
+            steps: z.ZodRecord<z.ZodString, z.ZodObject<{
+                output: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, "strip", z.ZodTypeAny, {
+                output: Record<string, unknown>;
+            }, {
+                output: Record<string, unknown>;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            steps: Record<string, {
+                output: Record<string, unknown>;
+            }>;
+        }, {
+            steps: Record<string, {
+                output: Record<string, unknown>;
+            }>;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string | null;
+        branch: string;
+        branches: Record<string, {
+            steps: Record<string, {
+                output: Record<string, unknown>;
+            }>;
+        }>;
+        caseIndex: number | null;
+    }, {
+        label: string | null;
+        branch: string;
+        branches: Record<string, {
+            steps: Record<string, {
+                output: Record<string, unknown>;
+            }>;
+        }>;
+        caseIndex: number | null;
+    }>;
+    readonly category: "control";
+    readonly icon = "switch";
+    readonly declaredOutputs: readonly [{
+        readonly key: "branch";
+        readonly label: "Matched branch key";
+    }, {
+        readonly key: "caseIndex";
+        readonly label: "Matched case index";
+    }, {
+        readonly key: "label";
+        readonly label: "Matched case label";
+    }];
+    /**
+     * Expose every branch (each case + default) so the config validator can
+     * walk forward references inside each one independently.
+     */
+    getBranches(config: Record<string, unknown>): Record<string, WorkflowStepConfig[]>;
+    execute(config: SwitchStepConfig, ctx: ControlFlowExecutionContext): Promise<SwitchStepOutput>;
+}
+//# sourceMappingURL=switch.step.d.ts.map

package/dist/connectors/builtin/steps/switch.step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switch.step.d.ts","sourceRoot":"","sources":["../../../../src/connectors/builtin/steps/switch.step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAsB,MAAM,6BAA6B,CAAC;AACtF,OAAO,KAAK,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAgB5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,MAAM,WAAW,gBAAiB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/D,qGAAqG;IACrG,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sFAAsF;IACtF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;CACxD;AAcD,qBAAa,UAAW,SAAQ,mBAAmB,CACjD,OAAO,sBAAsB,EAC7B,gBAAgB,CACjB;IACC,SAAkB,IAAI,0BAA0B;IAChD,SAAkB,IAAI,YAAY;IAClC,SAAkB,WAAW,6EAA6E;IAC1G,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAA0B;IACxD,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAA0B;IACxD,SAAkB,QAAQ,EAAG,SAAS,CAAU;IAChD,SAAkB,IAAI,YAAY;IAClC,SAAkB,eAAe;;;;;;;;;OAItB;IAEX;;;OAGG;IACM,WAAW,CAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAUxB,OAAO,CACpB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,2BAA2B,GAC/B,OAAO,CAAC,gBAAgB,CAAC;CA+B7B"}

package/dist/connectors/builtin/steps/switch.step.js

@@ -0,0 +1,101 @@
+/**
+ * SWITCH step — first-match-wins over an ordered list of conditional cases,
+ * with a guaranteed `default` fallback.
+ *
+ * Semantics (no fall-through):
+ *
+ *   for (const [i, c] of cases.entries())
+ *     if (evaluator.evaluate(c.condition, ctx.workflow)) {
+ *       walkBranch(c.steps, `case_${i}`)
+ *       return { branch: `case_${i}`, caseIndex: i, label: c.label ?? null }
+ *     }
+ *   walkBranch(default, 'default')
+ *   return { branch: 'default', caseIndex: null, label: null }
+ *
+ * Branch keys are positional (`case_0`, `case_1`, ..., `default`) so a
+ * paused execution's PausePath survives label edits.
+ */
+import { z } from 'zod';
+import { BaseControlFlowStep, collectBranchSteps } from '../../../steps/base-step.js';
+import { BuiltinStepType } from '../../../types/known-types.js';
+import { ConditionSchema } from '../../../types/workflow-config.js';
+import { ConditionEvaluator } from '../../../engine/condition-evaluator.js';
+// ─── Config ───
+const SwitchCaseSchema = z.object({
+    condition: ConditionSchema
+        .describe('Recursive condition tree (leaf or all/any composite). First case whose condition is true wins.'),
+    label: z.string().optional()
+        .describe('Optional UI label for this case. Not used for routing — branch keys are positional.'),
+    steps: z.array(z.object({ id: z.string(), type: z.string() }).passthrough()).describe('Steps to execute when this case wins.'),
+});
+export const SwitchStepConfigSchema = z.object({
+    cases: z.array(SwitchCaseSchema)
+        .describe('Ordered cases. Evaluated top-to-bottom; first match wins, no fall-through.'),
+    default: z.array(z.object({ id: z.string(), type: z.string() }).passthrough()).describe('Fallback branch. Runs when no case matches. Use `[]` to no-op the fallback.'),
+});
+const SwitchStepOutputSchema = z.object({
+    branch: z.string(),
+    caseIndex: z.number().int().nullable(),
+    label: z.string().nullable(),
+    branches: z.record(z.object({ steps: z.record(z.object({ output: z.record(z.unknown()) })) })),
+});
+// ─── Step ───
+const DEFAULT_BRANCH_KEY = 'default';
+const caseBranchKey = (i) => `case_${i}`;
+export class SwitchStep extends BaseControlFlowStep {
+    type = BuiltinStepType.SWITCH;
+    name = 'Switch';
+    description = 'Route to one of N branches; first matching case wins, otherwise default';
+    configSchema = SwitchStepConfigSchema;
+    outputSchema = SwitchStepOutputSchema;
+    category = 'control';
+    icon = 'switch';
+    declaredOutputs = [
+        { key: 'branch', label: 'Matched branch key' },
+        { key: 'caseIndex', label: 'Matched case index' },
+        { key: 'label', label: 'Matched case label' },
+    ];
+    /**
+     * Expose every branch (each case + default) so the config validator can
+     * walk forward references inside each one independently.
+     */
+    getBranches(config) {
+        const branches = {};
+        const cases = (config['cases'] ?? []);
+        for (let i = 0; i < cases.length; i++) {
+            branches[caseBranchKey(i)] = (cases[i]?.steps ?? []);
+        }
+        branches[DEFAULT_BRANCH_KEY] = (config['default'] ?? []);
+        return branches;
+    }
+    async execute(config, ctx) {
+        const evaluator = new ConditionEvaluator();
+        for (let i = 0; i < config.cases.length; i++) {
+            const entry = config.cases[i];
+            if (evaluator.evaluate(entry.condition, ctx.workflow)) {
+                const branchKey = caseBranchKey(i);
+                const branchSteps = entry.steps;
+                if (branchSteps.length > 0) {
+                    await ctx.walkBranch(branchSteps, ctx.workflow, branchKey);
+                }
+                return {
+                    branch: branchKey,
+                    caseIndex: i,
+                    label: entry.label ?? null,
+                    branches: { [branchKey]: { steps: collectBranchSteps(branchSteps, ctx.workflow) } },
+                };
+            }
+        }
+        const defaultSteps = config.default;
+        if (defaultSteps.length > 0) {
+            await ctx.walkBranch(defaultSteps, ctx.workflow, DEFAULT_BRANCH_KEY);
+        }
+        return {
+            branch: DEFAULT_BRANCH_KEY,
+            caseIndex: null,
+            label: null,
+            branches: { [DEFAULT_BRANCH_KEY]: { steps: collectBranchSteps(defaultSteps, ctx.workflow) } },
+        };
+    }
+}
+//# sourceMappingURL=switch.step.js.map