@uipath/maestro-builder-sdk 6.8.3 → 6.8.4

package/dist/core/actions.d.ts

@@ -564,16 +564,16 @@ export interface HitlInputs {
     /**
      * The completion buttons, e.g. `['Approve', 'Reject']`. At least one, or the
      * reviewer has no way to complete the task and the flow waits forever. The
-     * first is the primary (default) one. MORE THAN ONE gives each outcome its own
-     * exit, `outcome-<slug>`: the first continues the main path and the rest are
-     * routed with `.stepToList('outcome-<slug>', …)`. Only
-     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`, a `variant`, an
-     * explicit `{ version }`, or every outcome ending the process keeps the older
-     * single `completed` exit.
+     * first is the primary (default) one. Each outcome is its own exit,
+     * `outcome-<slug>`: the default node and `'quick-form'` never leave on
+     * `completed` once they have outcomes. On the default node MORE THAN ONE
+     * outcome routes per outcome: the first continues the main path and the rest
+     * are routed with `.stepToList('outcome-<slug>', …)`. With `'quick-form'`,
+     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`, an explicit
+     * `{ version }` or one outcome, `.step()` continues EVERY outcome instead.
      *
      * Which one they pressed is also `out('<step>', 'Action')` — that is what the
-     * platform's own routing conditions compare against, so a task on the single
-     * exit branches on it downstream.
+     * platform's own routing conditions compare against.
      */
     outcomes: Outcome[];
     /** Who gets the task and how. Omit for the definition's default delivery. */
@@ -581,25 +581,25 @@ export interface HitlInputs {
     /** Action Center labels, comma-separated (the platform stores one string). */
     labels?: string;
     /**
-     * Whether each outcome exits from its OWN port (`outcome-<id>`) instead of the
-     * single `completed` one. **More than one outcome does this by default**, so
-     * the useful value is `false` — an opt back into the single exit, for a task
-     * that routes the decision as DATA by reading `out('<step>', 'Action')`.
+     * Whether the task ROUTES per outcome. Each outcome has its own exit either
+     * way (`outcome-<id>`, the name slugified: `'Approve'` → `outcome-approve`).
      *
-     * Per-outcome exits select the node's **1.1** definition, whose handles are
-     * `outcome-<id>` (ids are the outcome names slugified, e.g. `'Approve'` →
-     * `outcome-approve`). They REPLACE `completed` rather than adding to it. The
-     * FIRST (primary) outcome continues the main path; route the others with
-     * `.stepToList('outcome-<id>', …)`, or the run stalls when the reviewer picks
-     * one. Base variant only — the sub-typed nodes have no per-outcome definition
-     * version, so they keep the single exit whatever this says.
+     * `true`: the FIRST outcome continues the main path and the others are routed
+     * with `.stepToList('outcome-<id>', …)`, or the run stalls when the reviewer
+     * picks one. The default node with more than one outcome already does this,
+     * on its **1.1** definition unless a `{ version }` pins another; `'quick-form'`
+     * supports it on its one definition. `false`: EVERY outcome continues to the
+     * next step on its own edge — a task that routes the decision as DATA by
+     * reading `out('<step>', 'Action')`; `'quick-form'` does this by default.
+     * `'action-app'` and `'document-validation'` read their outcomes from the app
+     * and leave on their one `completed` exit, so `true` is refused there.
      */
     outcomePorts?: boolean;
     /**
      * Expose the task's runtime error as a bindable `out('<step>', 'error')`
      * object (`{ code, message, detail, category, status }`). Selects the node's
      * **1.2** definition — which also routes per outcome, so this implies
-     * {@link HitlInputs.outcomePorts | outcomePorts}. Base variant only.
+     * {@link HitlInputs.outcomePorts | outcomePorts}. Default node only.
      */
     exposeError?: boolean;
     /**

package/dist/core/hitl-routing.d.ts

@@ -1,38 +1,73 @@
 /**
- * Does a human task route PER OUTCOME — one `outcome-<id>` exit each — or leave
- * on the single `completed` handle?
- *
- * Shared by `serialize` (which picks the node's definition version and its tail
- * port from this) and `check` (whose four outcome-port rules all key on it), so
- * the two cannot drift. They did drift once, in the direction that matters
- * least visibly: `check` keyed on the `outcomePorts` FLAG while `serialize` was
- * about to infer it, which would have made `check` refuse per-outcome wiring
- * that `compile` then emitted.
- *
- * **More than one outcome infers it.** Declaring outcomes creates no exits on
- * the 1.0 definition — its one source handle is `completed`, so every button
- * the reviewer can press leaves the node the same way and the decision never
- * reaches the graph. That shape is only meaningful for a zero- or one-outcome
- * acknowledgement, and at two or more it compiled, validated `Valid`, and
- * shipped flows whose approve and reject paths were indistinguishable — first
- * silently (flow-builder-sdk#735), then past the warning that #738 added
- * (#739). So the flag is what an author reaches for to *override* the shape,
- * not what they must remember to switch it on.
- *
- * Four things turn the inference off, in this order:
- *
- * 1. `outcomePorts: false` — an explicit opt back into the single exit.
- * 2. A `variant`. The quick-form, action-app and document-validation node types
- *    carry no per-outcome definition version to select, so `completed` plus a
- *    `switch` on `out('<step>', 'Action')` is their only shape (#729).
- * 3. An explicitly pinned `{ version }`. The shape of a deployed artifact is
- *    recorded in its `typeVersion`, and `decompile` emits that pin — so
- *    decompiling a 1.0 flow and recompiling it round-trips exactly instead of
- *    promoting the node to 1.1 and stranding its `completed` edge.
- * 4. Every outcome carrying `action: 'End'`. The run stops AT the node, so no
- *    exit can distinguish anything and per-outcome handles would only invite
- *    routes that can never be taken. The same reasoning suppresses
- *    HITL_OUTCOMES_UNREACHABLE.
+ * How a human task leaves its node — the one model `serialize`, `check` and
+ * `.stepSwitch` (`step-ports.ts`) all read, so the three cannot drift. They did
+ * drift once, in the direction that matters least visibly: `check` keyed on the
+ * `outcomePorts` FLAG while `serialize` was about to infer it, which would have
+ * made `check` refuse per-outcome wiring that `compile` then emitted.
+ *
+ * **The product's rule, which the model follows.** On the base node
+ * (`uipath.human-in-the-loop`, `type: 'quick'`) and on the quick-form variant,
+ * the designer draws ONE handle per entry in `inputs.schema.outcomes`, named
+ * `outcome-<id>`, whatever the node's `typeVersion` — and draws the manifest's
+ * static `completed` handle only when there are no outcomes
+ * (flow-workbench `build-handle-customization.ts:102-124`; it derives them on
+ * every render and deliberately never saves them). A leftover `completed` edge
+ * on such a node is a stale placeholder: since flow-workbench #3512 the load
+ * path and the converter remap it to the PRIMARY outcome
+ * (`hitl-edge-reconciliation.ts:52-63`), so every other outcome loses its path at
+ * run time. So a task with outcomes never leaves on `completed` here. The two
+ * app-backed variants are different: action-app and document-validation read
+ * their outcomes from `inputs.app`, and `completed` really is the only handle
+ * they render (`hitl-edge-reconciliation.ts:68-74`).
+ *
+ * (This replaces an older premise — "the definition VERSION selects the port
+ * shape, and the variants have no per-outcome version" (#729). The manifests do
+ * declare only `completed` statically; the designer just never reads that list
+ * for these two node types once outcomes exist.)
+ *
+ * **Three shapes**, and what `.step()` after the task means in each — ".step()
+ * continues from the task's tails":
+ *
+ * - `per-outcome`: the task ROUTES per outcome. One tail, the PRIMARY (first)
+ *   outcome's `outcome-<id>`; the author routes the rest with `.stepToList` /
+ *   `.stepToRef`, or all of them as `.stepSwitch` arms.
+ * - `every-outcome`: the task does NOT route per outcome. One tail PER outcome,
+ *   so `.step()` continues every outcome to the next step ("fan-out") — the
+ *   decision reaches the flow as data, `out('<step>', 'Action')`, in the handles
+ *   the product draws. An `action: 'End'` outcome is the exception: the flow
+ *   runtime never reads `action` (flow-workbench `hitl-serialization.ts` does
+ *   not; only the agent storage projection does), so the graph is the only thing
+ *   that can end the run there, and `serialize` gives it an End node.
+ * - `placeholder`: `completed` — action-app, document-validation, and a task
+ *   with no outcomes.
+ *
+ * **More than one outcome infers `per-outcome`** on the base node (#739): a task
+ * that publishes a choice and then routes every button the same way was the
+ * modelling error behind flow-builder-sdk#735, and a warning alone did not
+ * change what agents emitted. Five things keep a base or quick-form task on
+ * `every-outcome` instead, in this order:
+ *
+ * 1. `outcomePorts: false` — the explicit "decision as data" choice.
+ * 2. `variant: 'quick-form'`. Not a product limit — quick-form draws the same
+ *    per-outcome handles — but its authors write `.step()` or a `.switch` on the
+ *    Action after it and mean "every outcome continues" (every quick-form source
+ *    in the 09-23 baseline does), so inferring primary-only there would strand
+ *    the other outcomes. It routes per outcome when asked: `outcomePorts: true`,
+ *    or `.stepSwitch`. Its definition version never moves.
+ * 3. An explicit `{ version }` pin. `decompile` pins every node and writes
+ *    `outcomePorts: true` whenever a task's outcomes lead to different places, so
+ *    a pinned task that reaches `.step()` without the flag is a round-tripped
+ *    artifact whose outcomes all go to one step, or a legacy lone `completed`
+ *    edge, which meant "every outcome continues" before #3512. Both are this
+ *    shape. The pin also wins the version: `outcomePorts: true` on a pinned 1.0
+ *    routes per outcome on the 1.0 node, which `flow validate` accepts.
+ * 4. A single outcome — an acknowledgement, not a choice.
+ * 5. Every outcome carrying `action: 'End'` — there is no continuation to
+ *    distinguish, and each outcome gets its End.
+ *
+ * `exposeError: true` or `outcomePorts: true` select `per-outcome` on every node
+ * type, including the two app-backed variants, so that `serialize` and `check`
+ * refuse them there with their own message rather than silently ignoring them.
  */
 import type { HitlInputs } from './actions.js';
 /**
@@ -44,4 +79,64 @@ import type { HitlInputs } from './actions.js';
  * nothing else recognises.
  */
 export declare function outcomeSlug(name: unknown, index: number): string;
+/** One outcome's exit. */
+export interface HitlOutcomeExit {
+    /** The outcome NAME — what `.stepSwitch` arms and `out('<step>', 'Action')` compare against. */
+    value: string;
+    /** The emitted source handle, `outcome-<id>`. */
+    port: string;
+    /** `action: 'End'`: the author says this outcome ends the run. */
+    endsProcess: boolean;
+}
+/** Why a base or quick-form task continues every outcome, phrased for a diagnostic. */
+export type HitlFanOutReason = 'outcomePorts: false' | 'quick-form' | 'pinned' | 'one outcome' | 'every outcome ends';
+export type HitlExitModel = {
+    shape: 'placeholder';
+} | {
+    shape: 'every-outcome';
+    exits: HitlOutcomeExit[];
+    why: HitlFanOutReason;
+} | {
+    shape: 'per-outcome';
+    exits: HitlOutcomeExit[];
+};
+/**
+ * The two human-task node types whose exits the product derives from
+ * `inputs.schema.outcomes`. Keyed on TYPE, never on whether `schema.outcomes` is
+ * present: the SDK writes `schema.outcomes` on an action-app task too (its
+ * `Action` output is enumerated over them), and that task's `completed` is real.
+ */
+export declare const OUTCOME_HANDLE_NODE_TYPES: ReadonlySet<string>;
+/** The same test on the authored side: no variant (the base node), or quick-form. */
+export declare function hitlDerivesOutcomeHandles(variant: unknown): boolean;
+export declare function hitlExitModel(inputs: HitlInputs | undefined, pinnedVersion?: string): HitlExitModel;
+/** Does this task route PER OUTCOME (primary continues, the rest are routed)? */
 export declare function hitlRoutesPerOutcome(inputs: HitlInputs | undefined, pinnedVersion?: string): boolean;
+type NodeLike = {
+    id?: unknown;
+    type?: unknown;
+    inputs?: any;
+};
+type EdgeLike = {
+    sourceNodeId?: unknown;
+    sourcePort?: unknown;
+};
+/**
+ * Why an edge on `port` cannot leave `node`, or `undefined` when it can.
+ *
+ * Only the two node types whose handles the product derives from the outcomes
+ * are judged, and only once they HAVE outcomes: then `completed` is a handle
+ * the product does not draw, and an `outcome-<id>` naming no declared outcome is
+ * one `flow validate` refuses ("Edge references undeclared source handle"). A
+ * real outcome named "Completed" is `outcome-completed`, which is fine — the
+ * bare `completed` never is.
+ */
+export declare function hitlExitViolation(node: NodeLike, port: string): string | undefined;
+/**
+ * The post-emit half of the guard: every edge of an emitted scope, whatever
+ * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
+ * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
+ * these would ship a flow that validates and then drops outcomes at run time.
+ */
+export declare function assertHitlExitInvariant(nodes: readonly NodeLike[], edges: readonly EdgeLike[]): void;
+export {};

package/dist/core/hitl-routing.js

@@ -14,20 +14,104 @@ export function outcomeSlug(name, index) {
         .replace(/^-+|-+$/g, '');
     return slug || `outcome-${index + 1}`;
 }
-export function hitlRoutesPerOutcome(inputs, pinnedVersion) {
-    // `exposeError` selects 1.2, which routes per outcome too. Both flags are
-    // honoured on a variant so that `serialize` still refuses them there with its
-    // own message rather than silently ignoring them.
+/**
+ * The two human-task node types whose exits the product derives from
+ * `inputs.schema.outcomes`. Keyed on TYPE, never on whether `schema.outcomes` is
+ * present: the SDK writes `schema.outcomes` on an action-app task too (its
+ * `Action` output is enumerated over them), and that task's `completed` is real.
+ */
+export const OUTCOME_HANDLE_NODE_TYPES = new Set([
+    'uipath.human-in-the-loop',
+    'uipath.human-in-the-loop.quick-form',
+]);
+/** The same test on the authored side: no variant (the base node), or quick-form. */
+export function hitlDerivesOutcomeHandles(variant) {
+    return variant === undefined || variant === 'quick-form';
+}
+export function hitlExitModel(inputs, pinnedVersion) {
+    const exits = (inputs?.outcomes ?? []).map((o, i) => {
+        const name = typeof o === 'string' ? o : o?.name;
+        return {
+            value: String(name ?? ''),
+            port: `outcome-${outcomeSlug(name, i)}`,
+            endsProcess: typeof o !== 'string' && o?.action === 'End',
+        };
+    });
     if (inputs?.exposeError === true || inputs?.outcomePorts === true)
-        return true;
+        return { shape: 'per-outcome', exits };
+    if (!hitlDerivesOutcomeHandles(inputs?.variant) || exits.length === 0)
+        return { shape: 'placeholder' };
+    const every = (why) => ({ shape: 'every-outcome', exits, why });
     if (inputs?.outcomePorts === false)
-        return false;
-    if (inputs?.variant !== undefined)
-        return false;
+        return every('outcomePorts: false');
+    if (inputs?.variant === 'quick-form')
+        return every('quick-form');
     if (pinnedVersion !== undefined)
-        return false;
-    const outcomes = inputs?.outcomes ?? [];
-    if (outcomes.length <= 1)
-        return false;
-    return !outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
+        return every('pinned');
+    if (exits.length === 1)
+        return every('one outcome');
+    if (exits.every((e) => e.endsProcess))
+        return every('every outcome ends');
+    return { shape: 'per-outcome', exits };
+}
+/** Does this task route PER OUTCOME (primary continues, the rest are routed)? */
+export function hitlRoutesPerOutcome(inputs, pinnedVersion) {
+    return hitlExitModel(inputs, pinnedVersion).shape === 'per-outcome';
+}
+function outcomeIdsOf(node) {
+    let schema = node.inputs?.schema;
+    if (typeof schema === 'string') {
+        try {
+            schema = JSON.parse(schema);
+        }
+        catch {
+            return [];
+        }
+    }
+    const outcomes = Array.isArray(schema?.outcomes) ? schema.outcomes : [];
+    return outcomes.map((o) => o?.id).filter((id) => typeof id === 'string' && id !== '');
+}
+/**
+ * Why an edge on `port` cannot leave `node`, or `undefined` when it can.
+ *
+ * Only the two node types whose handles the product derives from the outcomes
+ * are judged, and only once they HAVE outcomes: then `completed` is a handle
+ * the product does not draw, and an `outcome-<id>` naming no declared outcome is
+ * one `flow validate` refuses ("Edge references undeclared source handle"). A
+ * real outcome named "Completed" is `outcome-completed`, which is fine — the
+ * bare `completed` never is.
+ */
+export function hitlExitViolation(node, port) {
+    if (!OUTCOME_HANDLE_NODE_TYPES.has(String(node.type)))
+        return undefined;
+    const ids = outcomeIdsOf(node);
+    if (ids.length === 0)
+        return undefined;
+    const declared = ids.map((i) => `outcome-${i}`).join(', ');
+    if (port === 'completed') {
+        return `human task "${String(node.id)}" has outcomes (${declared}), so the product draws no `
+            + `'completed' handle on it — an edge there is remapped to the primary outcome and every other `
+            + `outcome loses its path.`;
+    }
+    if (port.startsWith('outcome-') && !ids.includes(port.slice('outcome-'.length))) {
+        return `human task "${String(node.id)}" has no outcome for port "${port}" — it declares ${declared}.`;
+    }
+    return undefined;
+}
+/**
+ * The post-emit half of the guard: every edge of an emitted scope, whatever
+ * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
+ * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
+ * these would ship a flow that validates and then drops outcomes at run time.
+ */
+export function assertHitlExitInvariant(nodes, edges) {
+    const byId = new Map(nodes.map((n) => [String(n.id), n]));
+    for (const e of edges) {
+        const node = byId.get(String(e.sourceNodeId));
+        if (!node)
+            continue;
+        const why = hitlExitViolation(node, String(e.sourcePort));
+        if (why)
+            throw new Error(`serialize: ${why}`);
+    }
 }

package/dist/core/step-ports.d.ts

@@ -1,3 +1,4 @@
+import type { Step } from '../flow-sdk.js';
 /** One author-named exit: the value an arm matches on, and the port it wires. */
 export interface DeclaredExit {
     /** What `.stepSwitch()`'s arm `value` matches — the outcome or branch NAME. */
@@ -34,4 +35,11 @@ type SpecLike = {
 export declare function declaredExits(spec: SpecLike | undefined, pinnedVersion?: string): DeclaredExit[] | NoExits;
 /** Narrowing helper — `declaredExits` returns one or the other. */
 export declare function hasExits(r: DeclaredExit[] | NoExits): r is DeclaredExit[];
+/**
+ * Whether a step list that hands on no tail got there by reaching an End — a
+ * `.return()`, on some path — rather than by stopping the whole run
+ * (`.terminate`) or leaving a loop (`.break`). Only the first leaves a sibling
+ * `.parallel` join waiting: a terminate ends the run, join included.
+ */
+export declare function stopsAtEnd(steps: readonly Step[]): boolean;
 export {};

package/dist/core/step-ports.js

@@ -20,7 +20,7 @@
  * handling and outcome routing in one list, where an omitted arm would mean two
  * different things.
  */
-import { hitlRoutesPerOutcome, outcomeSlug } from './hitl-routing.js';
+import { hitlExitModel } from './hitl-routing.js';
 /**
  * The author-declared exits of `spec`, or a `NoExits` explaining why there are
  * none to route.
@@ -29,32 +29,29 @@ 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
+        const model = hitlExitModel(inputs, pinnedVersion);
+        if (model.shape === 'placeholder') {
+            // WHY it has no outcome exits 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?.outcomes ?? []).length === 0) {
+                return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
             }
-            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: `the '${inputs?.variant}' variant reads its outcomes from its app and leaves on its single 'completed' exit`,
+                suggestion: `Use .step() and switch on out('<step>', 'Action').`,
+            };
+        }
+        // A quick-form task and a pinned one continue every outcome under `.step()`,
+        // but their outcome handles are real, so `.stepSwitch` routes them. The
+        // other fan-out reasons leave nothing to route.
+        if (model.shape === 'every-outcome' && model.why !== 'quick-form' && model.why !== 'pinned') {
+            if (model.why === 'outcomePorts: false') {
                 return {
-                    reason: `{ version: '${pinnedVersion}' } pins the definition whose only exit is 'completed'`,
-                    suggestion: 'Drop the pin.',
+                    reason: 'outcomePorts: false continues every outcome to the next step',
+                    suggestion: 'Drop `outcomePorts: false`.',
                 };
             }
-            if (outcomes.length === 1) {
+            if (model.why === 'one outcome') {
                 return {
                     reason: 'a single outcome has a single exit, so there is nothing to route',
                     suggestion: 'Use .step() — the next step follows it unconditionally.',
@@ -65,14 +62,11 @@ export function declaredExits(spec, pinnedVersion) {
                 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 } : {}),
-            };
-        });
+        return model.exits.map((e) => ({
+            value: e.value,
+            port: e.port,
+            ...(e.endsProcess ? { endsProcess: true } : {}),
+        }));
     }
     if (kind === 'http') {
         const branches = (spec?.inputs?.branches
@@ -100,3 +94,16 @@ export function declaredExits(spec, pinnedVersion) {
 export function hasExits(r) {
     return Array.isArray(r);
 }
+/**
+ * Whether a step list that hands on no tail got there by reaching an End — a
+ * `.return()`, on some path — rather than by stopping the whole run
+ * (`.terminate`) or leaving a loop (`.break`). Only the first leaves a sibling
+ * `.parallel` join waiting: a terminate ends the run, join included.
+ */
+export function stopsAtEnd(steps) {
+    const has = (list, kinds) => list.some((st) => kinds.has(st.kind)
+        || (st.kind === 'branch' && (has(st.then, kinds) || has(st.otherwise, kinds)))
+        || ((st.kind === 'switch' || st.kind === 'stepSwitch') && st.cases.some((c) => has(c.body, kinds)))
+        || (st.kind === 'switch' && st.default !== undefined && has(st.default, kinds)));
+    return has(steps, new Set(['return'])) && !has(steps, new Set(['terminate', 'break']));
+}