@uipath/maestro-builder-sdk 6.29.0 → 6.29.2

package/dist/core/definition-handles.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The source handles a node's definition declares, read against the node's own
+ * inputs — one reader for every layer that has to know which ports a node can
+ * leave on (`merge-roundtrip.ts`'s handle checks, `decompile`'s arm recovery for
+ * a node with no typed factory, and `.stepSwitch` over a `rawNode`).
+ *
+ * A definition lists its handles in `handleConfiguration[].handles[]`. A static
+ * handle is its `id`; a REPEATED one is a template expanded once per item of an
+ * input array:
+ *
+ * ```
+ * { id: 'case-{item.id}', type: 'source', repeat: 'inputs.criteria' }
+ * inputs.criteria = [{ id: 'returns' }, { id: 'billing' }]
+ * → case-returns, case-billing
+ * ```
+ *
+ * This is how `core.logic.agentic-switch` (one exit per choice, plus `default`)
+ * and `core.logic.switch` (one per case) declare their exits.
+ */
+type Def = {
+    readonly [k: string]: unknown;
+} | undefined;
+/**
+ * Every source handle `def` declares for a node with `inputs`, in declaration
+ * order, templates expanded. `undefined` when `def` has no
+ * `handleConfiguration`, or has a template this cannot expand (a `repeat` that
+ * is not an `inputs.` path), so a caller can tell "no handles" from "cannot
+ * know".
+ */
+export declare function expandSourceHandles(def: Def, inputs: unknown): string[] | undefined;
+/**
+ * The FORWARD exits a node's definition declares when it has more than one —
+ * every source handle except `error` and an agent's artifact handles, templates
+ * expanded. `undefined` for a definition with one forward exit or fewer, or one
+ * whose handles cannot be known: such a node has no fan-out to route.
+ */
+export declare function forwardFanOut(def: Def, inputs: unknown): string[] | undefined;
+/**
+ * The port a node's main path leaves on — the edge a plain `.step()` writes
+ * and a following step continues from: the first concrete forward source
+ * handle (`isDefaultForType` wins), else `output`. `undefined` when every
+ * forward source handle is templated (`case-{item.id}`), so no main path leaves
+ * the node.
+ *
+ * `serialize` writes the main-path edge on this port, and `decompile` reads the
+ * main path back off it, so the two must agree: a `core.logic.agentic-switch`
+ * (`case-{item.id}` + `default`) continues on `default`, and each other wired
+ * exit is a `.stepToList('case-<id>', …)` (#1214).
+ */
+export declare function contributionPort(def: Def): string | undefined;
+export {};

package/dist/core/definition-handles.js

@@ -0,0 +1,95 @@
+/**
+ * The source handles a node's definition declares, read against the node's own
+ * inputs — one reader for every layer that has to know which ports a node can
+ * leave on (`merge-roundtrip.ts`'s handle checks, `decompile`'s arm recovery for
+ * a node with no typed factory, and `.stepSwitch` over a `rawNode`).
+ *
+ * A definition lists its handles in `handleConfiguration[].handles[]`. A static
+ * handle is its `id`; a REPEATED one is a template expanded once per item of an
+ * input array:
+ *
+ * ```
+ * { id: 'case-{item.id}', type: 'source', repeat: 'inputs.criteria' }
+ * inputs.criteria = [{ id: 'returns' }, { id: 'billing' }]
+ * → case-returns, case-billing
+ * ```
+ *
+ * This is how `core.logic.agentic-switch` (one exit per choice, plus `default`)
+ * and `core.logic.switch` (one per case) declare their exits.
+ */
+/**
+ * Every source handle `def` declares for a node with `inputs`, in declaration
+ * order, templates expanded. `undefined` when `def` has no
+ * `handleConfiguration`, or has a template this cannot expand (a `repeat` that
+ * is not an `inputs.` path), so a caller can tell "no handles" from "cannot
+ * know".
+ */
+export function expandSourceHandles(def, inputs) {
+    const groups = def?.handleConfiguration;
+    if (!Array.isArray(groups))
+        return undefined;
+    const out = [];
+    for (const g of groups) {
+        for (const h of (g?.handles ?? [])) {
+            if (h?.type !== 'source' || typeof h.id !== 'string')
+                continue;
+            const template = /\{item\.([A-Za-z0-9_]+)\}/.exec(h.id);
+            if (!template) {
+                if (!out.includes(h.id))
+                    out.push(h.id);
+                continue;
+            }
+            if (typeof h.repeat !== 'string' || !h.repeat.startsWith('inputs.'))
+                return undefined;
+            let items = inputs;
+            for (const seg of h.repeat.slice('inputs.'.length).split('.'))
+                items = items?.[seg];
+            for (const item of Array.isArray(items) ? items : []) {
+                const v = item?.[template[1]];
+                if (typeof v !== 'string' && typeof v !== 'number')
+                    continue;
+                const id = h.id.replace(template[0], String(v));
+                if (!out.includes(id))
+                    out.push(id);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Source handles that are not exits: `error` (routed by `.onError()`) and an
+ * agent's artifact handles, which attach its tools, context, escalations and
+ * memory rather than continue the flow.
+ */
+const NOT_FORWARD = new Set(['error', 'tool', 'context', 'escalation', 'memory']);
+/**
+ * The FORWARD exits a node's definition declares when it has more than one —
+ * every source handle except `error` and an agent's artifact handles, templates
+ * expanded. `undefined` for a definition with one forward exit or fewer, or one
+ * whose handles cannot be known: such a node has no fan-out to route.
+ */
+export function forwardFanOut(def, inputs) {
+    const handles = expandSourceHandles(def, inputs)?.filter((h) => !NOT_FORWARD.has(h));
+    return handles !== undefined && handles.length > 1 ? handles : undefined;
+}
+/**
+ * The port a node's main path leaves on — the edge a plain `.step()` writes
+ * and a following step continues from: the first concrete forward source
+ * handle (`isDefaultForType` wins), else `output`. `undefined` when every
+ * forward source handle is templated (`case-{item.id}`), so no main path leaves
+ * the node.
+ *
+ * `serialize` writes the main-path edge on this port, and `decompile` reads the
+ * main path back off it, so the two must agree: a `core.logic.agentic-switch`
+ * (`case-{item.id}` + `default`) continues on `default`, and each other wired
+ * exit is a `.stepToList('case-<id>', …)` (#1214).
+ */
+export function contributionPort(def) {
+    const groups = Array.isArray(def?.handleConfiguration) ? def.handleConfiguration : [];
+    const handles = groups.flatMap((g) => (g?.handles ?? []));
+    const sources = handles.filter((h) => h?.type === 'source' && h?.id !== 'error');
+    const concrete = sources.filter((h) => typeof h?.id === 'string' && !h.id.includes('{'));
+    if (concrete.length === 0 && sources.length > 0)
+        return undefined;
+    return concrete.find((h) => h?.isDefaultForType)?.id ?? concrete[0]?.id ?? 'output';
+}

package/dist/core/raw-node-exits.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The exits `.stepSwitch` routes over when its step is a `rawNode`: the
+ * manifest's forward source handles, `repeat` ones expanded over the node's
+ * inputs, each arm's `value` being its port. A `core.logic.agentic-switch`
+ * with choices `returns` and `billing` has `case-returns`, `case-billing` and
+ * `default`:
+ *
+ * ```ts
+ * .stepSwitch('route', rawNode({ nodeType: 'core.logic.agentic-switch', … }), [
+ *   { value: 'case-returns', body: (b) => b.step('returns', …) },
+ *   { value: 'case-billing', body: (b) => b.step('billing', …) },
+ *   { value: 'default', body: (b) => b.step('triage', …) },
+ * ])
+ * ```
+ *
+ * Internal, not package API: `raw-node.ts` (whose module the package
+ * re-exports) puts the answer on its node under this symbol, and
+ * `flow-step-exits.ts` reads it. `decompile` reads the same handles off the
+ * file's definition, so what it emits recompiles (#1141).
+ */
+import type { DeclaredExit } from './step-ports.js';
+/** The method a raw node answers its exits under. */
+export declare const RAW_NODE_EXITS: unique symbol;
+/**
+ * `action`'s exits when it is a raw node whose manifest declares more than one
+ * forward exit; `undefined` otherwise (then it has nothing to route).
+ */
+export declare function rawNodeExits(action: unknown): DeclaredExit[] | undefined;

package/dist/core/raw-node-exits.js

@@ -0,0 +1,10 @@
+/** The method a raw node answers its exits under. */
+export const RAW_NODE_EXITS = Symbol('rawNodeExits');
+/**
+ * `action`'s exits when it is a raw node whose manifest declares more than one
+ * forward exit; `undefined` otherwise (then it has nothing to route).
+ */
+export function rawNodeExits(action) {
+    const own = action?.[RAW_NODE_EXITS];
+    return typeof own === 'function' ? own.call(action) : undefined;
+}

package/dist/decompile.js

@@ -46,6 +46,7 @@ import { mapJsCode } from './core/js-code-spans.js';
 import { missingBindingLabels } from './core/binding-messages.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
+import { contributionPort, forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
 import { sdkFormFieldType } from './core/form-field-type.js';
@@ -531,11 +532,34 @@ class Graph {
     successorEdges(id) {
         const primary = this.primaryOutcomePort(id);
         const forked = this.fullyWiredExits(id);
+        const side = forked ? undefined : this.rawSidePorts(id);
         return this.outEdges(id).filter((e) => e.sourcePort !== 'error'
             && !ARTIFACT_PORTS.has(e.sourcePort)
             && (forked?.has(e.sourcePort)
                 || (!e.sourcePort.startsWith('branch-')
-                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary))));
+                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary)
+                    && !side?.has(e.sourcePort))));
+    }
+    /**
+     * A multi-exit `rawNode`'s SIDE exits when not every exit is wired: each
+     * declared exit except the one its main path leaves on (`contributionPort`,
+     * the port serialize writes a plain `.step()`'s edge on — `default` for a
+     * `core.logic.agentic-switch`). Each is recovered as a
+     * `.stepToList('<port>', …)` after the `.step`, as `branch-*` and non-primary
+     * `outcome-*` exits are. `undefined` for every other node, and for a raw node
+     * whose exits are all wired (that one is a `.stepSwitch`).
+     *
+     * Without this, a partially wired agentic switch had two successors and no
+     * merge join, so the walk emitted an unstructured-fan-out TODO and dropped
+     * every arm (#1214).
+     */
+    rawSidePorts(id) {
+        const node = this.byId.get(id);
+        const exits = node ? rawNodeExits(node) : undefined;
+        if (!node || exits === undefined || this.fullyWiredExits(id) !== undefined)
+            return undefined;
+        const main = contributionPort(rawNodeDefinition(node));
+        return new Set(exits.map((e) => e.port).filter((p) => p !== main));
     }
 }
 // ─── Node → step-spec source ──────────────────────────────────────────────────
@@ -2396,6 +2420,17 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
                 segs.push(`.stepToList(${tsLiteral(oe.sourcePort)}, ${armCb('p', outSegs)})`);
             }
         }
+        // A partially wired multi-exit raw node (an agentic switch with one choice
+        // unwired): every wired exit but the main path's is its own port list, and
+        // an unwired one stays unwired (#1214).
+        const rawSide = ctx.graph.rawSidePorts(node.id);
+        for (const re of rawSide ? ctx.graph.outEdges(node.id).filter((e) => rawSide.has(e.sourcePort)) : []) {
+            const mainReach = forwardReach(succ, scope, ctx.graph);
+            const sideSegs = edgeRegion(re, EXIT, scope, ipdom, ctx, mainReach);
+            if (sideSegs.length === 0)
+                sideSegs.push('.return({})');
+            segs.push(`.stepToList(${tsLiteral(re.sourcePort)}, ${armCb('p', sideSegs)})`);
+        }
         // A body edge into the enclosing container's break handle: the path exits
         // the loop here. Emit `.break()` and end the region — recompiling recreates
         // exactly this edge and adds no continue back-edge for the path.
@@ -2534,7 +2569,9 @@ function declaredExitsOfNode(node) {
     // A registered type that declares exits answers from its own spec, lifted off
     // this node; one that declares none is not lifted at all (this runs per edge).
     const impl = registeredImpl(node);
-    if (!impl?.exits)
+    if (!impl)
+        return rawNodeExits(node);
+    if (!impl.exits)
         return undefined;
     const lifted = liftRegistered(node, impl);
     const exits = lifted && impl.exits(lifted.spec);
@@ -2542,6 +2579,41 @@ function declaredExitsOfNode(node) {
         return undefined;
     return exits.map((e) => ({ value: e.value, port: e.port }));
 }
+/**
+ * The exits of a node that decompiles to a `rawNode` (a type this SDK has no
+ * factory for, carried with the file's own definition): that definition's
+ * forward source handles, `repeat` ones expanded over the node's inputs, when it
+ * has more than one. `core.logic.agentic-switch` declares `case-{item.id}` over
+ * `inputs.criteria` plus `default`, so a node with choices `returns` and
+ * `billing` has the exits `case-returns`, `case-billing`, `default`. Each exit's
+ * value is its port, which is what `.stepSwitch` over a `rawNode` matches
+ * (`rawNodeExits` in raw-node.ts reads the same handles off the manifest).
+ *
+ * Without this, a fully wired multi-exit raw node had ONE exit to the walker:
+ * it emitted `.step(...)` with a TODO and dropped every arm (#1141).
+ *
+ * `undefined` for every node the decompiler names some other way (the walker's
+ * structural types, triggers, connectors, agents, published resources, IxP):
+ * their exits are not a raw node's, and an agent's artifact handles (`tool`,
+ * `context`, …) are not exits at all.
+ */
+function rawNodeExits(node) {
+    const type = String(node.type);
+    // A registered type (an HTTP call, say) answers from its own `exits`.
+    if (registeredImpl(node) !== undefined)
+        return undefined;
+    if (Object.values(T).includes(type) || isTrigger(type))
+        return undefined;
+    if (['uipath.connector.', 'uipath.core.', 'uipath.ixp.', 'uipath.agent.', 'uipath.conversational.']
+        .some((p) => type.startsWith(p)))
+        return undefined;
+    return forwardFanOut(rawNodeDefinition(node), node.inputs)?.map((port) => ({ value: port, port }));
+}
+/** The definition the file carries for `node`'s type (its version's, else the type's). */
+function rawNodeDefinition(node) {
+    const type = String(node.type);
+    return runDefs.get(`${type}@${node.typeVersion}`) ?? runDefs.get(type);
+}
 /**
  * Split a switch case expression into `<discriminant> === <literal>`, the only
  * form `.switch(on, [{ value }])` models. Returns `undefined` for any other

package/dist/flow-step-exits.js

@@ -8,6 +8,7 @@
 import { resolveVersion } from './core/nodes/versioned.js';
 import { declaredExits } from './core/step-ports.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
+import { rawNodeExits } from './core/raw-node-exits.js';
 /**
  * The author-declared exits of a step's spec: a registered type's own `exits`,
  * at the version the step resolves to (its pin, else the type's choice; an
@@ -16,6 +17,10 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
  * here, so they agree on what a port means.
  */
 export function stepExits(spec, pinnedVersion) {
+    // A `rawNode` declares its exits through the manifest it carries (#1141).
+    const raw = rawNodeExits(spec);
+    if (raw !== undefined)
+        return raw;
     const entry = typeof spec?.kind === 'string' ? FLOW_NODE_TYPES.byKind(spec.kind, spec) : undefined;
     if (!entry)
         return declaredExits(spec, pinnedVersion);

package/dist/merge-roundtrip.js

@@ -50,6 +50,7 @@
  *   merged file still has it.
  */
 import { bindingIdentity } from './core/binding-identity.js';
+import { expandSourceHandles } from './core/definition-handles.js';
 import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 /** A file's definitions, keyed `nodeType@version`. */
 function defsOf(f) {
@@ -279,32 +280,8 @@ export function roundTripFindings(original, baseline, merged) {
 }
 /** The source handles a node's definition declares, or `undefined` when they cannot be known. */
 function declaredSourceHandles(node, def) {
-    const groups = def?.handleConfiguration;
-    if (!Array.isArray(groups))
-        return undefined;
-    const out = new Set();
-    for (const g of groups) {
-        for (const h of (g?.handles ?? [])) {
-            if (h?.type !== 'source' || typeof h.id !== 'string')
-                continue;
-            const template = /\{item\.([A-Za-z0-9_]+)\}/.exec(h.id);
-            if (!template) {
-                out.add(h.id);
-                continue;
-            }
-            if (typeof h.repeat !== 'string' || !h.repeat.startsWith('inputs.'))
-                return undefined; // a template this check cannot expand
-            let items = node.inputs;
-            for (const seg of h.repeat.slice('inputs.'.length).split('.'))
-                items = items?.[seg];
-            for (const item of Array.isArray(items) ? items : []) {
-                const v = item?.[template[1]];
-                if (typeof v === 'string' || typeof v === 'number')
-                    out.add(h.id.replace(template[0], String(v)));
-            }
-        }
-    }
-    return out;
+    const handles = expandSourceHandles(def, node.inputs);
+    return handles === undefined ? undefined : new Set(handles);
 }
 /**
  * The handles a node derives from its own inputs, in order: a definition's

package/dist/raw-node.js

@@ -8,6 +8,8 @@
 import { FlowAction, } from './core/node-classes.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, rawNodeTypedFamilyWarning } from './raw-node-advice.js';
+import { forwardFanOut } from './core/definition-handles.js';
+import { RAW_NODE_EXITS } from './core/raw-node-exits.js';
 /**
  * Place a node this SDK has no factory for, carrying its definition verbatim
  * (`uipath.exotic.thing@2.1` and the manifest the platform served for it).
@@ -88,6 +90,11 @@ class RawNode extends FlowAction {
             out.push({ code: 'RAW_NODE_TYPED_FAMILY', severity: 'warning', message: typed });
         return out;
     }
+    /** Its exits, for `.stepSwitch` (core/raw-node-exits.ts). */
+    [RAW_NODE_EXITS]() {
+        const manifest = this.spec.manifest;
+        return forwardFanOut(manifest, this.spec.inputs ?? {})?.map((port) => ({ value: port, port }));
+    }
     contribute(context) {
         // compile does not run diagnostics(); refuse here too so the escape hatch
         // cannot emit an unconfigured connector node. (An input a registered node

package/dist/serialize.js

@@ -57,6 +57,7 @@ import { resolveSchemaVersion } from './schema-version.js';
 import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-variables.js';
 import { outputBackingGlobal, planOutputBacking } from './flow-output-backing.js';
 import { mapJsCode } from './core/js-code-spans.js';
+import { contributionPort } from './core/definition-handles.js';
 import { prepareCommand } from './core/cli-spelling.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { resourceNodeSortOrder } from './core/process-resource-sort-order.js';
@@ -3531,18 +3532,6 @@ function declaresForwardPort(def, port) {
         return port.length > head.length + tail.length && port.startsWith(head) && port.endsWith(tail);
     });
 }
-/**
- * Forward port: the first concrete source handle (`isDefaultForType` wins), else `output`;
- * `undefined` when every forward source handle is templated (`case-{item.id}`).
- */
-function contributionPort(def) {
-    const handles = (def?.handleConfiguration ?? []).flatMap((g) => g?.handles ?? []);
-    const sources = handles.filter((h) => h?.type === 'source' && h?.id !== 'error');
-    const concrete = sources.filter((h) => typeof h?.id === 'string' && !h.id.includes('{'));
-    if (concrete.length === 0 && sources.length > 0)
-        return undefined;
-    return concrete.find((h) => h?.isDefaultForType)?.id ?? concrete[0]?.id ?? 'output';
-}
 /**
  * Render a switch case value as a JS literal for the case expression.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.29.0",
+  "version": "6.29.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "af71b0c21f732f056d19e802af1c987fd8528336"
+  "gitref": "b0d822e147a21ef1051b36c474b303839e980b13"
 }