@uipath/maestro-builder-sdk 5.4.1 → 6.0.1

package/dist/core/step-ports.js

@@ -0,0 +1,102 @@
+/**
+ * The exits an action declares that the AUTHOR named — a human task's outcomes,
+ * an HTTP call's response branches — and the port each one leaves on.
+ *
+ * This is what `.stepSwitch()` routes over, and the reason it exists as a table
+ * rather than as two more `if (spec.kind === …)` arms: `serialize` has to turn
+ * an arm's `value` into a port, `check` has to say which values are legal and
+ * which were left out, and `decompile` has to turn a port back into a value.
+ * Those three read the same list here instead of each carrying their own copy
+ * of "how a human task names its ports" and "how an HTTP branch names its
+ * ports".
+ *
+ * `undefined` means the family has no author-declared fan-out at all, which is
+ * what makes `.stepSwitch()` on it an error rather than a no-op.
+ *
+ * The `error` port is deliberately NOT here. It is declared by the definition
+ * rather than by the author, it exists on families that have no other fan-out,
+ * and it is already routed by `.onError()` / `.stepToList('error', …)`. Folding
+ * it in would make every action a `.stepSwitch` candidate and would put failure
+ * handling and outcome routing in one list, where an omitted arm would mean two
+ * different things.
+ */
+import { hitlRoutesPerOutcome, outcomeSlug } from './hitl-routing.js';
+/**
+ * The author-declared exits of `spec`, or a `NoExits` explaining why there are
+ * none to route.
+ */
+export function declaredExits(spec, pinnedVersion) {
+    const kind = spec && 'kind' in spec ? spec.kind : undefined;
+    if (kind === 'hitl') {
+        const inputs = spec?.inputs;
+        const outcomes = (inputs?.outcomes ?? []);
+        if (outcomes.length === 0) {
+            return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
+        }
+        if (!hitlRoutesPerOutcome(inputs, pinnedVersion)) {
+            // WHY it kept the single exit decides what the author can do about it, so
+            // the caller gets the specific one rather than "ports are off".
+            if (inputs?.outcomePorts === false) {
+                return {
+                    reason: 'outcomePorts: false keeps its single `completed` exit',
+                    suggestion: 'Drop `outcomePorts: false`.',
+                };
+            }
+            if (inputs?.variant !== undefined) {
+                return {
+                    reason: `the '${inputs.variant}' variant has no per-outcome definition version to select`,
+                    suggestion: `Drop the variant, or use .step() and switch on out('<step>', 'Action').`,
+                };
+            }
+            if (pinnedVersion !== undefined) {
+                return {
+                    reason: `{ version: '${pinnedVersion}' } pins the definition whose only exit is 'completed'`,
+                    suggestion: 'Drop the pin.',
+                };
+            }
+            if (outcomes.length === 1) {
+                return {
+                    reason: 'a single outcome has a single exit, so there is nothing to route',
+                    suggestion: 'Use .step() — the next step follows it unconditionally.',
+                };
+            }
+            return {
+                reason: 'every outcome ends the process, so no exit distinguishes them',
+                suggestion: 'Use .step().',
+            };
+        }
+        return outcomes.map((o, i) => {
+            const name = (typeof o === 'string' ? o : o?.name) ?? '';
+            return {
+                value: String(name),
+                port: `outcome-${outcomeSlug(name, i)}`,
+                ...(typeof o !== 'string' && o?.action === 'End' ? { endsProcess: true } : {}),
+            };
+        });
+    }
+    if (kind === 'http') {
+        const branches = (spec?.inputs?.branches
+            ?? []);
+        if (branches.length === 0) {
+            return {
+                reason: 'it declares no response branches',
+                suggestion: `branches: [{ name: 'rateLimited', condition: … }]`,
+            };
+        }
+        // The fall-through is an exit like any other here — it is what `.switch()`
+        // spells as its default arm, and leaving it out is the same omission as
+        // leaving out a branch.
+        return [
+            ...branches.map((b) => ({ value: String(b?.name ?? ''), port: `branch-${b?.name ?? ''}` })),
+            { value: 'default', port: 'default', isDefault: true },
+        ];
+    }
+    return {
+        reason: `a ${kind ?? 'custom'} step declares no author-named exits`,
+        suggestion: 'Use .step(); route failures with .onError().',
+    };
+}
+/** Narrowing helper — `declaredExits` returns one or the other. */
+export function hasExits(r) {
+    return Array.isArray(r);
+}

package/dist/decompile.js

@@ -408,16 +408,39 @@ class Graph {
         const first = outcomes[0]?.id;
         return typeof first === 'string' && first !== '' ? `outcome-${first}` : undefined;
     }
+    /**
+     * Every declared exit of `id`, when ALL of them are wired — the `.stepSwitch`
+     * shape. `undefined` otherwise, which leaves the node with a tacit main path
+     * and its siblings as side arms.
+     */
+    fullyWiredExits(id) {
+        const node = this.byId.get(id);
+        const declared = node ? declaredExitsOfNode(node) : undefined;
+        if (declared === undefined || declared.length < 2)
+            return undefined;
+        const wired = new Set(this.outEdges(id).map((e) => e.sourcePort));
+        if (!declared.every((d) => wired.has(d.port)))
+            return undefined;
+        return new Set(declared.map((d) => d.port));
+    }
     /**
      * Out-edges excluding the side paths recovered as port lists: `error`,
      * `branch-*`, and every `outcome-*` except the primary one.
+     *
+     * UNLESS every declared exit is wired. Then the node genuinely FORKS — there
+     * is no main path, each arm is a successor — and the post-dominator has to see
+     * that or it computes the join as the primary arm's first node. Which it did:
+     * a converged two-outcome task decompiled with one arm empty and the other
+     * swallowing the tail, because `ipdom(review)` came back as `publish`.
      */
     successorEdges(id) {
         const primary = this.primaryOutcomePort(id);
+        const forked = this.fullyWiredExits(id);
         return this.outEdges(id).filter((e) => e.sourcePort !== 'error'
             && !ARTIFACT_PORTS.has(e.sourcePort)
-            && !e.sourcePort.startsWith('branch-')
-            && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary));
+            && (forked?.has(e.sourcePort)
+                || (!e.sourcePort.startsWith('branch-')
+                    && (!e.sourcePort.startsWith('outcome-') || e.sourcePort === primary))));
     }
 }
 // ─── Node → step-spec source ──────────────────────────────────────────────────
@@ -1952,6 +1975,25 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         }
         // A regular action step (mock / script / http / transform / connector / …).
         const spec = emitStepSpec(node, ctx.imp, ctx.inputNames, ctx.o, ctx.graph);
+        // `.stepSwitch` when the node's author-declared exits are ALL wired and the
+        // arms rejoin: that graph has no tacit main path to recover, so the
+        // `.step` + `.stepToList` form below cannot express it. It used to come back
+        // as `.stepToRef("end")` — a reference to the synthetic End node, which
+        // `compile` then refused (REF_UNKNOWN_TARGET), so a converged port graph did
+        // not round-trip at all. Reachable from the designer long before
+        // `.stepSwitch` existed; the arms just had nothing to decompile INTO.
+        const exitPorts = portArmExits(node, ctx);
+        if (exitPorts && exitPorts.length > 1) {
+            const r = ipdom.get(node.id) ?? stop;
+            const armSrcs = exitPorts.map(({ value, port }) => {
+                const armSegs = region(portTarget(ctx.graph, node.id, port), r, scope, ipdom, ctx, refInto);
+                return `{ value: ${str(value)}, body: ${armCb('b', armSegs)} }`;
+            });
+            const armList = `[\n${armSrcs.map((a) => reindent(a, '  ')).join(',\n')},\n]`;
+            segs.push(`.stepSwitch(${str(node.id)}, ${spec}, ${armList}${optsArg(node, ctx)})`);
+            cursor = r === EXIT ? undefined : r;
+            continue;
+        }
         segs.push(`.step(${str(node.id)}, ${spec}${optsArg(node, ctx)})`);
         // An error handler on this step (source port `error` + `errorHandlingEnabled`).
         const succ = scopeSucc(ctx.graph, node.id, scope);
@@ -2037,6 +2079,53 @@ function forwardReach(entries, scope, graph) {
     }
     return seen;
 }
+/**
+ * The node's author-declared exits when EVERY one of them is wired — the shape
+ * `.stepSwitch` authors. `undefined` when the node has no such exits, or when
+ * one is unwired, in which case the `.step` + `.stepToList` recovery still
+ * applies and the unwired port stays unwired.
+ *
+ * Deliberately strict about "every one": a partially wired node still has a
+ * tacit main path, and recovering THAT as `.stepSwitch` would invent arms the
+ * flow does not have.
+ */
+function portArmExits(node, ctx) {
+    // One predicate, on the Graph, because `successorEdges` has to agree with this
+    // exactly: if the CFG forks here the arms must be emitted as arms, and if it
+    // does not they must not be.
+    if (ctx.graph.fullyWiredExits(node.id) === undefined)
+        return undefined;
+    return declaredExitsOfNode(node);
+}
+/**
+ * The exits a node declares, read back off the EMITTED artifact rather than off
+ * an authored spec — `inputs.schema.outcomes` for a human task at 1.1/1.2,
+ * `inputs.branches` plus `default` for an HTTP call. The authoring-side twin is
+ * `declaredExits` in `core/step-ports.ts`; they answer about different inputs,
+ * which is why this is not a call into it.
+ */
+function declaredExitsOfNode(node) {
+    const inputs = (node.inputs ?? {});
+    if (String(node.type).startsWith('uipath.human-in-the-loop')) {
+        const version = String(node.typeVersion ?? '');
+        if (version !== '1.1' && version !== '1.2')
+            return undefined;
+        const outcomes = (inputs.schema?.outcomes ?? []);
+        if (outcomes.length === 0)
+            return undefined;
+        return outcomes.map((o) => ({ value: String(o?.name ?? ''), port: `outcome-${o?.id ?? ''}` }));
+    }
+    if (node.type === T.http || node.type === T.httpV2) {
+        const branches = (inputs.branches ?? []);
+        if (branches.length === 0)
+            return undefined;
+        return [
+            ...branches.map((b) => ({ value: String(b?.name ?? ''), port: `branch-${b?.name ?? ''}` })),
+            { value: 'default', port: 'default' },
+        ];
+    }
+    return undefined;
+}
 /**
  * Emit a `.switch(...)` from a `core.logic.switch` node. Each case's serialized
  * expression is `<discriminant> === <JSON-literal>`; the discriminant (shared by

package/dist/flow-expr-check.js

@@ -85,6 +85,10 @@ function addStepNames(steps, roots) {
                 if (s.default)
                     addStepNames(s.default, roots);
                 break;
+            case 'stepSwitch':
+                for (const c of s.cases)
+                    addStepNames(c.body, roots);
+                break;
             case 'loop':
                 addStepNames(s.body, roots);
                 break;
@@ -145,6 +149,13 @@ function walk(steps, roots, out) {
                     walk(s.default, caseRoots, out);
                 break;
             }
+            case 'stepSwitch':
+                // The action's own inputs, then each arm — no discriminant to bind, the
+                // exits are named by the step rather than compared against a value.
+                deepExprs(s.spec.inputs, s.name, roots, out);
+                for (const c of s.cases)
+                    walk(c.body, roots, out);
+                break;
             case 'loop':
                 pushExpr(s.collection.js, s.collection.literal, s.name, roots, out);
                 if (s.options?.completionCondition) {

package/dist/flow-sdk.d.ts

@@ -292,6 +292,19 @@ export interface SwitchArm {
     label?: string;
     body: Step[];
 }
+/**
+ * One arm of a built `.stepSwitch` — the same shape as {@link SwitchArm}, but
+ * `value` names an exit the ACTION declares (a human-task outcome, an HTTP
+ * response branch) rather than a value to compare against. No `label`: a port
+ * edge carries none, and the exit's own name is already the label the canvas
+ * draws.
+ */
+export interface PortArm {
+    /** The exit this arm routes — a human-task outcome name, an HTTP branch name, or `'default'`. */
+    value: string;
+    /** The steps that run on that exit. Ends in `.return()` to be terminal; otherwise it converges. */
+    body: Step[];
+}
 /**
  * Options shared by every builder method that creates a definition-backed node:
  * `version` selects the exact node definition to compile against, and `updates`
@@ -425,6 +438,12 @@ export type Step = {
     cases: SwitchArm[];
     default?: Step[];
     options?: NodeOptions;
+} | {
+    kind: 'stepSwitch';
+    name: string;
+    spec: FlowActionSpec;
+    cases: PortArm[];
+    options?: NodeOptions;
 } | {
     kind: 'loop';
     name: string;
@@ -693,6 +712,48 @@ declare class StepList {
      * @returns This builder, so calls chain.
      */
     step(name: string, spec: FlowActionSpec | FlowAction, options?: NodeOptions): this;
+    /**
+     * Add an action node and route EVERY exit it declares, one arm per exit.
+     *
+     * The symmetric form of `.step()` + `.stepToList()`. Where those make the
+     * first exit the tacit next step and the rest side branches, this makes all
+     * of them arms of one construct — so nothing about a human task's routing
+     * depends on which outcome happens to be listed first.
+     *
+     * Arms behave exactly like `.switch()`'s: one that ends in `.return()` is
+     * terminal, and one that does not CONVERGES, so the step after the
+     * `.stepSwitch` fans in from every arm that reaches it. (That is the
+     * difference from `.stepToList`, whose arms get an End of their own.)
+     *
+     * `value` names an exit the ACTION declares — a human task's outcome name, an
+     * HTTP response branch's name, or `'default'` for HTTP's fall-through — not a
+     * value to compare against. `check` refuses a value the step does not declare
+     * and warns about a declared exit left out, which compiles to an End node.
+     *
+     * @param name - The step's id, as `.step()`.
+     * @param spec - What the node does, from an action factory.
+     * @param cases - One arm per declared exit.
+     * @param options - Node options, as `.step()`.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * **Route a human task's outcomes, and converge on one return**
+     * ```ts
+     * export default flow('draft-review')
+     *   .output({ summary: types.string })
+     *   .var('summary', types.string)
+     *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
+     *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { summary: out('publish') } }) },
+     *     { value: 'Revise', body: (b) => b.step('sendBack', script({ code: 'return "revise";', returns: 'string' }), { updates: { summary: out('sendBack') } }) },
+     *   ])
+     *   .return({ summary: v('summary') })
+     *   .build();
+     * ```
+     */
+    stepSwitch(name: string, spec: FlowActionSpec | FlowAction, cases: {
+        value: string;
+        body: (b: ArmBuilder) => void;
+    }[], options?: NodeOptions): this;
     /**
      * Handle the PREVIOUS step's failure: if it fails, the flow runs `bodyFn`'s
      * steps instead of continuing.

package/dist/flow-sdk.js

@@ -303,6 +303,67 @@ class StepList {
         this.steps.push({ kind: 'action', name, spec: spec, ...(options ? { options } : {}) });
         return this;
     }
+    /**
+     * Add an action node and route EVERY exit it declares, one arm per exit.
+     *
+     * The symmetric form of `.step()` + `.stepToList()`. Where those make the
+     * first exit the tacit next step and the rest side branches, this makes all
+     * of them arms of one construct — so nothing about a human task's routing
+     * depends on which outcome happens to be listed first.
+     *
+     * Arms behave exactly like `.switch()`'s: one that ends in `.return()` is
+     * terminal, and one that does not CONVERGES, so the step after the
+     * `.stepSwitch` fans in from every arm that reaches it. (That is the
+     * difference from `.stepToList`, whose arms get an End of their own.)
+     *
+     * `value` names an exit the ACTION declares — a human task's outcome name, an
+     * HTTP response branch's name, or `'default'` for HTTP's fall-through — not a
+     * value to compare against. `check` refuses a value the step does not declare
+     * and warns about a declared exit left out, which compiles to an End node.
+     *
+     * @param name - The step's id, as `.step()`.
+     * @param spec - What the node does, from an action factory.
+     * @param cases - One arm per declared exit.
+     * @param options - Node options, as `.step()`.
+     * @returns This builder, so calls chain.
+     *
+     * @example
+     * **Route a human task's outcomes, and converge on one return**
+     * ```ts
+     * export default flow('draft-review')
+     *   .output({ summary: types.string })
+     *   .var('summary', types.string)
+     *   .stepSwitch('review', hitl({ fields: [], outcomes: ['Publish', 'Revise'] }), [
+     *     { value: 'Publish', body: (b) => b.step('publish', script({ code: 'return "published";', returns: 'string' }), { updates: { summary: out('publish') } }) },
+     *     { value: 'Revise', body: (b) => b.step('sendBack', script({ code: 'return "revise";', returns: 'string' }), { updates: { summary: out('sendBack') } }) },
+     *   ])
+     *   .return({ summary: v('summary') })
+     *   .build();
+     * ```
+     */
+    stepSwitch(name, spec, cases, options) {
+        if (!Array.isArray(cases) || cases.length === 0) {
+            throw new TypeError(`.stepSwitch('${name}'): needs at least one arm. With nothing to route, use .step().`);
+        }
+        const arms = cases.map((c) => {
+            const arm = new ArmBuilder();
+            c.body?.(arm);
+            // A `.switch()` arm's label becomes `inputs.cases[].label` on the decision
+            // node. There is no such slot here: an edge carries no label, and the port
+            // is already named by the outcome or branch it leaves. Refusing beats
+            // accepting it and dropping it on the floor.
+            if (arm.armLabel !== undefined) {
+                throw new TypeError(`.stepSwitch('${name}') arm '${c.value}': .label() has nowhere to go — a port edge carries no `
+                    + `label, and the exit is named by "${c.value}" already. Use options.label to rename the NODE.`);
+            }
+            return { value: String(c.value), body: arm.steps };
+        });
+        this.steps.push({
+            kind: 'stepSwitch', name, spec: spec, cases: arms,
+            ...(options ? { options } : {}),
+        });
+        return this;
+    }
     /**
      * Handle the PREVIOUS step's failure: if it fails, the flow runs `bodyFn`'s
      * steps instead of continuing.

package/dist/generators/_connections.py

@@ -30,6 +30,8 @@ __all__ = [
     "ConnectionError_",
     "byoa_connections",
     "byoa_listing",
+    "candidate_connections",
+    "candidate_listing",
     "discover_connection",
     "lookup_connection",
     "merge_bindings",
@@ -130,6 +132,48 @@ def discover_connection(connector_key: str, name: str | None = None) -> dict:
     return rows[0]
 
 
+def candidate_connections(connector_key: str, name: str | None = None) -> list[dict]:
+    """Every enabled connection for `connector_key`, own folder FIRST.
+
+    `discover_connection` answers "which one" and stops at the first non-empty
+    scope, which is right for picking a connection and wrong for retrying one:
+    when the own-folder listing holds exactly one, the tenant-wide connections
+    are never even looked at. So a lookup that exhausts the personal-workspace
+    connection reports a bad VALUE while the record sits in another folder's
+    connection (flow-builder-sdk#744, measured on two Jira connections where
+    only the second carried project `TS`).
+
+    Ordering is the same preference `discover_connection` encodes — the caller's
+    own folder is the likeliest and is tried first — but nothing is dropped.
+    Deduplicated by `Id`, because the tenant-wide listing repeats the own-folder
+    rows.
+
+    This does NOT decide anything, and in particular does not raise on several
+    matches: choosing among them is the caller's job, and the only honest way to
+    choose is evidence (a lookup that resolves on exactly one). That keeps this
+    module's rule intact — ambiguity is never resolved by guessing.
+    """
+    ordered: list[dict] = []
+    seen: set[str] = set()
+    for all_folders in (False, True):
+        for row in _matching(_list(all_folders=all_folders), connector_key, name):
+            identifier = str(row.get("Id", ""))
+            if identifier and identifier in seen:
+                continue
+            seen.add(identifier)
+            ordered.append(row)
+    return ordered
+
+
+def candidate_listing(rows: list[dict], indent: str = "    ") -> str:
+    """The candidates, one pasteable `--connection-id` line each."""
+    return "\n".join(
+        f"{indent}{row.get('Name')}  --connection-id {row.get('Id')}"
+        f"  (folder: {row.get('Folder')})"
+        for row in rows
+    )
+
+
 def _enabled_listing(rows: list[dict], connector_key: str) -> str:
     """The enabled connections for `connector_key`, one per line, pasteable."""
     enabled = _matching(rows, connector_key, None)

package/dist/generators/_resolve.py

@@ -25,6 +25,7 @@ import subprocess
 import sys
 
 __all__ = [
+    "LookupExhausted",
     "ResolutionError",
     "parse_resolve_flag",
     "resolve_one",
@@ -55,6 +56,36 @@ class ResolutionError(Exception):
     """A lookup that could not be resolved, with the reason a human needs."""
 
 
+class LookupExhausted(ResolutionError):
+    """The collection was read to the end on THIS connection and had no match.
+
+    Split out from its parent because the two failures want opposite responses
+    and the caller cannot tell them apart from a message. A transport or
+    permission failure says nothing about whether the value exists — retrying it
+    on another connection would hide a broken call behind a confident "no
+    connection has it". An exhaustive miss is positive evidence about this
+    connection specifically, and is the signal `prepare` uses to demote it and
+    try the next candidate (flow-builder-sdk#744).
+
+    `capped` flips that: a scan stopped at the record cap did NOT reach the end,
+    so it is not evidence of absence and must not demote anything.
+
+    The attributes carry the counts so a caller can report per-candidate results
+    without re-parsing the sentence.
+    """
+
+    def __init__(self, message: str, *, field: str, collection: str, by: str,
+                 value: str, scanned: int, pages: int, capped: bool) -> None:
+        super().__init__(message)
+        self.field = field
+        self.collection = collection
+        self.by = by
+        self.value = value
+        self.scanned = scanned
+        self.pages = pages
+        self.capped = capped
+
+
 def parse_resolve_flag(raw: str) -> tuple[str, str, str]:
     """`channel:profile.email=dustin@example.com` -> (field, by, value).
 
@@ -261,13 +292,28 @@ def resolve_one(
         query = f"{query}&nextPage={token}" if query else f"nextPage={token}"
 
     capped = scanned >= MAX_SCANNED or pages > PAGE_GUARD
-    raise ResolutionError(
+    # This states the FACT and stops; `prepare` owns the remedy, because
+    # `prepare` is what knows the other candidate connections.
+    #
+    # It deliberately carries NO "check the value" and NO `uip is resources`
+    # pointer. The old text led with both: it named only the value as suspect
+    # when the connection is equally suspect, and then sent the reader to a
+    # tenant crawl the skill explicitly rules out ("Tenant discovery is not a
+    # phase of either loop", references/CLI-LOOP.md). An agent followed that
+    # advice into exactly what it had been told not to do — 50 of 94 Bash calls
+    # hand-crawling Integration Service, 41 of them paging this collection, and
+    # the run hit its ceiling without producing a flow (flow-builder-sdk#744).
+    #
+    # The listing command is still offered, once, by the caller's terminal
+    # report — where every connection has been tried and seeing what IS there
+    # is finally the next step rather than a detour.
+    raise LookupExhausted(
         f"{field}: no record in {collection!r} has {by}={value!r} "
         f"(scanned {scanned} record(s) across {pages + 1} page(s)"
         + (f"; STOPPED AT THE {MAX_SCANNED}-record cap, so the value may be "
-           f"further in" if capped else "")
-        + ").\n"
-        f"Check the value, or list the collection to see what is there:\n"
-        f"  uip is resources run list {connector_key} {collection} "
-        f"--connection-id {connection_id}"
+           f"further in" if capped
+           else "; collection exhausted")
+        + f") on connection {connection_id}.",
+        field=field, collection=collection, by=by, value=value,
+        scanned=scanned, pages=pages + 1, capped=capped,
     )