@uipath/maestro-builder-sdk 6.19.0 → 6.20.1

package/dist/serialize.js

@@ -10,9 +10,10 @@ import { readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { BUNDLED_DEFINITIONS } from './flow-definitions.js';
+import { BUNDLED_DEFINITIONS, bundledVersions } from './flow-definitions.js';
 import { Expr, toExpr, SCHEDULE_PRESETS, parseIxpProjectType, flatNameOf, flatNameSegmentsOf } from './flow-sdk.js';
 import { FlowAction, FlowTrigger } from './core/node-classes.js';
+import { contextIndexType } from './core/context-index.js';
 import { connectorRawNodeRefusal } from './core/connector-raw-node.js';
 import { rawNodeInputProblem, registeredRawType } from './raw-node-advice.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
@@ -24,7 +25,9 @@ import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
 import { genericEventObjectRefusal } from './core/event-checks.js';
-import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeSlug } from './core/hitl-routing.js';
+import { OUTCOME_HANDLE_NODE_TYPES, assertHitlExitInvariant, hitlExitModel, hitlExitViolation, outcomeIdOf, outcomeSlug } from './core/hitl-routing.js';
+import { STICKY_NOTE_TYPE, STICKY_NOTE_TYPE_VERSION } from './core/definitionless-node-types.js';
+import { placeholderPosition } from './node-placement.js';
 import { declaredExits, hasExits } from './core/step-ports.js';
 import { stopsAtEnd } from './flow-step-tree.js';
 import { assertNodeEnvelope } from './core/node-envelope.js';
@@ -55,6 +58,7 @@ import { planFlowGlobals, planSharedInputs, sharedInputRoots } from './flow-vari
 import { prepareCommand } from './core/cli-spelling.js';
 import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
+import { resourceNodeSortOrder } from './core/process-resource-sort-order.js';
 import { types } from './core/expr.js';
 import { ownEntry } from './core/own-entry.js';
 import { jsonClone } from './core/json-file.js';
@@ -206,6 +210,9 @@ function processResourceLocation(spec) {
  * `icon: 'rpa'`, the `bpmn:ServiceTask` / `Orchestrator.StartJob` / `v2` model,
  * `section: 'Published'` (42/45), `debug.runtime: 'bpmnEngine'`, and the
  * `<bindings.name>` / `<bindings.folderPath>` context placeholders.
+ * `sortOrder` is not one of those constants any more: flow-core derives it from
+ * the category, and renumbered after 07-29, so it comes from
+ * `resourceNodeSortOrder` (#1045).
  *
  * Two fields are derived from the author's call rather than from the tenant, and
  * that limit is real:
@@ -236,7 +243,7 @@ function rpaWorkflowDef(spec) {
         runtimeConstraints: { exclude: ['api-function'] },
         description: loc.description,
         tags: loc.tags,
-        sortOrder: 530,
+        sortOrder: resourceNodeSortOrder('rpa-workflow'),
         supportsErrorHandling: true,
         display: { label: spec.name, icon: 'rpa' },
         handleConfiguration: [
@@ -316,7 +323,7 @@ const API_WORKFLOW_PREFIX = 'uipath.core.api-workflow.';
  * AGREE on, not invented: 42 `uipath.core.api-workflow.*` instances across 42
  * dated `skill-flow-api-workflow` artifacts (2026-05-18 → 07-29), cross-checked
  * against `registry get` for today's workflow. Every one is unanimous —
- * `category: 'api-workflow'`, `sortOrder: 510`, `supportsErrorHandling`,
+ * `category: 'api-workflow'`, `sortOrder: 510` (now 640, see `resourceNodeSortOrder`, #1045), `supportsErrorHandling`,
  * `icon: 'api'`, the `bpmn:ServiceTask` / `Orchestrator.ExecuteApiWorkflowAsync` /
  * `v2` model, `section: 'Published'` (37/42; the 5 without are the in-solution
  * shape, a bare-GUID resourceKey — rpa's 3/45 split again), `resourceSubType:
@@ -354,7 +361,7 @@ function apiWorkflowDef(spec) {
         runtimeConstraints: { exclude: ['api-function'] },
         description: `(${spec.folderPath})`,
         tags: [],
-        sortOrder: 510,
+        sortOrder: resourceNodeSortOrder('api-workflow'),
         supportsErrorHandling: true,
         display: { label: spec.name, icon: 'api' },
         handleConfiguration: [
@@ -435,7 +442,7 @@ function publishedFunctionDef(spec) {
         category: 'function',
         description: `(${spec.folderPath})`,
         tags: [],
-        sortOrder: 512,
+        sortOrder: resourceNodeSortOrder('function'),
         supportsErrorHandling: true,
         display: { label: spec.name, icon: 'function' },
         handleConfiguration: [
@@ -513,7 +520,8 @@ function publishedFunctionDef(spec) {
  *
  *  - `uip maestro flow registry get uipath.core.agentic-process.<key>` for ALL
  *    THREE agentic processes on the tenant (2026-07-29): `category:
- *    'agentic-process'`, `sortOrder: 507`, `supportsErrorHandling`, `icon:
+ *    'agentic-process'`, `sortOrder: 507` (now 610 for bpmn, 600 flow, 620 case:
+ *    `resourceNodeSortOrder`, #1045), `supportsErrorHandling`, `icon:
  *    'agentic-process'`, `version: '1.0.0'`, the `bpmn:ServiceTask` /
  *    `Orchestrator.StartAgenticProcess` / `v2` model, `section: 'Published'`,
  *    `resourceSubType: 'ProcessOrchestration'`, `orchestratorType:
@@ -556,7 +564,7 @@ function agenticProcessDef(spec) {
         runtimeConstraints: { exclude: ['api-function'] },
         description: loc.description,
         tags: loc.tags,
-        sortOrder: 507,
+        sortOrder: resourceNodeSortOrder(form.category),
         supportsErrorHandling: true,
         display: { label: spec.name, icon: form.icon },
         handleConfiguration: [
@@ -637,7 +645,8 @@ const INLINE_AGENT_TYPE = 'uipath.agent.autonomous';
  * checkable rather than asserted:
  *
  *  - `uip maestro flow registry get uipath.core.agent.<key>` for ALL NINE agents on
- *    the tenant (2026-07-29): `category: 'agent'`, `sortOrder: 505`,
+ *    the tenant (2026-07-29): `category: 'agent'`, `sortOrder: 505` (510 since flow-core's
+ *    renumber: the 54 runs from 09-01 below carry 510; `resourceNodeSortOrder`, #1045),
  *    `supportsErrorHandling: true`, `version: '1.0.0'`, the `bpmn:ServiceTask` /
  *    `Orchestrator.StartAgentJob` / `v2` model, `section: 'Published'`,
  *    `resourceSubType: 'Agent'`, `orchestratorType: 'agent'`,
@@ -691,7 +700,7 @@ function agentDef(spec) {
         runtimeConstraints: { exclude: ['api-function'] },
         description: loc.description,
         tags: loc.tags,
-        sortOrder: 505,
+        sortOrder: resourceNodeSortOrder('agent'),
         supportsErrorHandling: true,
         display: {
             label: spec.name,
@@ -836,21 +845,6 @@ function contextIndexDef(spec) {
         },
     };
 }
-/**
- * The node type for a context index: `…context.index.<slug>.<uuid>`.
- *
- * The slug is the index's display name lower-cased with every run of
- * non-alphanumerics collapsed to a single `-`. Measured against the platform's own
- * type for "Billing Dispute SOP Index" → `billing-dispute-sop-index`, and pinned
- * by a test — because a derived identifier that disagrees with the registry's is a
- * node type the tenant has never heard of.
- */
-function contextIndexSlug(name) {
-    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-}
-function contextIndexType(spec) {
-    return `uipath.agent.resource.context.index.${contextIndexSlug(spec.name)}.${spec.id}`;
-}
 /**
  * Render an index's retrieval query into the platform's MODE-TAGGED object.
  *
@@ -2958,9 +2952,14 @@ function connectionResourceBindings(spec, existing) {
  *    create, or the author's `returns` for a create-and-wait. Without a schema a
  *    downstream read is unresolvable.
  */
-function queueItemDef(spec, stepName, ids) {
+function queueItemDef(spec, stepName, ids, version) {
     const nodeType = spec.wait ? NODE_TYPE.queueCreateAndWait : NODE_TYPE.queueCreate;
-    const base = defByType.get(nodeType);
+    // The template at the AUTHOR'S version, when the bundle has it. Starting from
+    // the default and handing it to makeNode with the pin refused every other
+    // bundled version — the bug #988 fixed for inline agents (#1128). An
+    // unbundled pin falls back to the default, and makeNode's exact-version
+    // refusal names what is bundled.
+    const base = (version !== undefined ? DEFS[`${nodeType}@${version}`] : undefined) ?? defByType.get(nodeType);
     if (!base)
         throw new Error(`no bundled definition for "${nodeType}"`);
     const def = jsonClone(base);
@@ -3199,7 +3198,7 @@ function hitlInputs(inputs, nodeId, flowId, label, rename) {
     const outcomes = (inputs?.outcomes ?? []).map((o, i) => {
         const name = typeof o === 'string' ? o : o?.name;
         const action = typeof o === 'string' ? 'Continue' : (o?.action ?? 'Continue');
-        return { id: outcomeId(name, i), name, type: 'string', isPrimary: i === 0, action };
+        return { id: outcomeIdOf(o, i), name, type: 'string', isPrimary: i === 0, action };
     });
     const properties = {};
     for (const f of inputs?.fields ?? []) {
@@ -3475,8 +3474,6 @@ const NO_RENAME = { nodeIds: new Map(), errorEnvelopes: new Map() };
 const ERROR_ENVELOPE_VAR = {
     [NODE_TYPE.httpV2]: 'output',
 };
-/** The `typeVersion` Studio Web stamps on a sticky note. The type has no manifest to take it from. */
-const STICKY_NOTE_TYPE_VERSION = '1.0.0';
 /**
  * Append the flow's `.stickyNotes()` as real `stickyNote` nodes.
  *
@@ -3527,7 +3524,7 @@ function emitStickyNotes(built, scope, claimNoteId) {
         // `flow validate`, manifest or not (#869).
         scope.nodes.push({
             id: emittedId,
-            type: 'stickyNote',
+            type: STICKY_NOTE_TYPE,
             typeVersion: STICKY_NOTE_TYPE_VERSION,
             ui: {
                 position: { x: note.x, y: note.y },
@@ -3849,11 +3846,6 @@ export function resolveContributionDefinition(ref, requestedVersion, where) {
     }
     throw new Error(`${where}: unknown DefinitionReference source "${ref.source}".`);
 }
-/**
- * The forward port of a contribution-lowered node, derived from its
- * definition's handles: the source handle marked `isDefaultForType`, else the
- * first non-error source handle, else the conventional `output`.
- */
 /**
  * Whether `def` declares `port` as a forward source handle: an exact id, or a
  * templated one (`outcome-{item.id}` declares every `outcome-<slug>`). `error` is
@@ -3873,10 +3865,17 @@ 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');
-    return sources.find((h) => h?.isDefaultForType)?.id ?? sources[0]?.id ?? 'output';
+    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.
@@ -4726,6 +4725,8 @@ export function serialize(built, opts = {}) {
      * `.stepToRef` rejoins now do come through here, #938).
      */
     const hitlNodes = new Map();
+    /** Step name → node id of a step whose every forward exit is templated (see `contributionPort`). */
+    const routerNodes = new Map();
     /**
      * Human tasks with an outcome whose path stops at an End while another
      * outcome continues — read by `.parallel`, whose join would wait forever for
@@ -4757,8 +4758,16 @@ export function serialize(built, opts = {}) {
         if (o.requestedVersion !== undefined && def?.version !== o.requestedVersion) {
             const exact = o.def ? undefined : DEFS[`${type}@${o.requestedVersion}`];
             if (!exact) {
+                // Name every version the SDK could have resolved: every bundled
+                // version of the type, else (a type built per resource, a connector)
+                // the definition in hand. Naming only the default sent the reader
+                // looking for a version that was shipped all along (#1128:
+                // quick-form bundles 1.0 AND 1.1, and the message said 1.0).
+                const bundled = bundledVersions(type);
+                const resolvable = bundled.length > 0 ? bundled
+                    : [def?.version].filter((v) => typeof v === 'string');
                 throw new Error(`"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
-                    + `${type}@${def?.version ?? '<none>'}. Versions are exact — omit { version } to use `
+                    + `${type}@${resolvable.join(', ') || '<none>'}. Versions are exact — omit { version } to use `
                     + `the pinned default, or request a version this SDK ships.`);
             }
             def = exact;
@@ -4771,7 +4780,7 @@ export function serialize(built, opts = {}) {
             id,
             type,
             typeVersion: def?.version ?? '1.0.0',
-            ui: { position: { x: 256 + col * 288, y: 144 + (o.parentId ? 160 : 0) }, size: { width: 96, height: 96 }, collapsed: false },
+            ui: { position: placeholderPosition(col, Boolean(o.parentId)), size: { width: 96, height: 96 }, collapsed: false },
             display: { label: label ?? def?.display?.label ?? id, ...(def?.display?.icon ? { icon: def.display.icon } : {}) },
         };
         col++;
@@ -5075,7 +5084,14 @@ export function serialize(built, opts = {}) {
         scope.nodes.push(node);
         for (const t of o.tails)
             addEdge(scope, t, id);
-        return [{ node: id, port: contribution.port ?? contributionPort(def) }];
+        const port = contribution.port ?? contributionPort(def);
+        if (port === undefined) {
+            // Only templated exits: no main path leaves this node. Remember it so a
+            // following `.stepToList` / side-exit `.stepToRef` can still attach.
+            routerNodes.set(o.stepName, id);
+            return [];
+        }
+        return [{ node: id, port }];
     }
     /**
      * Lower a step whose kind is a registered node type (flow-node-registry.ts):
@@ -5413,6 +5429,13 @@ export function serialize(built, opts = {}) {
             const contexts = s.context === undefined ? []
                 : Array.isArray(s.context) ? s.context : [s.context];
             for (const cx of contexts) {
+                // `check`'s AGENT_CONTEXT_NO_ID, again for `--no-check`: a blank id builds
+                // the type `…context.index.<slug>.`, which no tenant serves, and nothing
+                // after this point would say so.
+                if (typeof cx?.id !== 'string' || !GUID_RE.test(cx.id)) {
+                    throw Object.assign(new Error(`inline agent "${step.name}": context index "${cx?.name ?? ''}" needs its index id (a GUID) as \`id\`; `
+                        + `got ${JSON.stringify(cx?.id)}. \`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`), { code: 'AGENT_CONTEXT_NO_ID' });
+                }
                 const cdef = contextIndexDef({ name: cx.name, id: cx.id });
                 // `<step>Context`, deduped by `uid` for a second index on the same agent.
                 // Not slugged from the index NAME: an id is the author's handle on the node
@@ -5876,7 +5899,7 @@ export function serialize(built, opts = {}) {
             const { ids, entries } = queueItemBindings(s, resourceBindings);
             for (const b of entries)
                 resourceBindings.set(b.id, b);
-            const def = queueItemDef(s, step.name, ids);
+            const def = queueItemDef(s, step.name, ids, step.options?.version);
             const id = stepUid(scope, step.name);
             // The result is read as `$vars.<step>.output`, like every other family: the
             // node's own output block maps the runtime `response` onto the variable
@@ -6359,8 +6382,13 @@ export function serialize(built, opts = {}) {
      * from a non-default port is a side exit. Only the seed differs from an ordinary
      * list — the same node, a different port.
      */
-    function emitPortList(step, source, tails, scope, parentId, breakTarget) {
+    function emitPortList(step, source, tails, scope, parentId, loopExits) {
         const handler = step.body;
+        // A node whose exits are all templated hands on no tail; its port lists
+        // leave from the node itself.
+        const router = tails.length === 0 ? routerNodes.get(source) : undefined;
+        if (router !== undefined)
+            tails = [{ node: router, port: step.port }];
         // `emitAction` returns one tail for every action kind — the node's own
         // success port — except a fan-out human task, which returns one per outcome
         // from the SAME node. Tails from two nodes mean a new action shape reached
@@ -6379,7 +6407,7 @@ export function serialize(built, opts = {}) {
             refuseErrorEdgeWithoutPort(nodeId, source);
             node.inputs = { ...(node.inputs ?? {}), errorHandlingEnabled: true };
         }
-        const handlerTails = emit(handler, [{ node: nodeId, port: step.port }], scope, parentId, breakTarget);
+        const handlerTails = emit(handler, [{ node: nodeId, port: step.port }], scope, parentId, loopExits);
         // A body that runs out of steps ends the run on an End of its own (no
         // merge-back is inferred). That End maps the outputs like any other, so a
         // body that set them with `{ updates }` still answers (#742).
@@ -6387,13 +6415,13 @@ export function serialize(built, opts = {}) {
             const endId = uid(scope, `${source}${step.port === 'error' ? 'Error' : step.port.charAt(0).toUpperCase() + step.port.slice(1)}End`);
             emitEnd(scope, endId, handlerTails, { parentId });
         }
-        return tails;
+        return router !== undefined ? [] : tails;
     }
     function emit(steps, incoming, scope, parentId, 
-    // The enclosing container's break handle, when inside a loop/do-while body.
-    // Branch/switch/parallel arms and error handlers INHERIT it; a nested
-    // container replaces it for its own body.
-    breakTarget) {
+    // The enclosing container's break and continue handles, when inside a
+    // loop/do-while body. Branch/switch/parallel arms and error handlers INHERIT
+    // them; a nested container replaces them for its own body.
+    loopExits) {
         let tails = incoming;
         // The action a port-scoped edge leaves. `.stepToList('error', …)` and
         // `.stepToRef('error', …)` are list MEMBERS that follow the step they attach
@@ -6437,6 +6465,14 @@ export function serialize(built, opts = {}) {
             node.display = { ...(node.display ?? {}), label };
         };
         for (const [stepIndex, step] of steps.entries()) {
+            // After a node whose exits are all templated, only its port lists may
+            // follow: nothing continues from it, so a step here would hang off no edge.
+            const router = lastAction !== undefined && tails.length === 0 ? routerNodes.get(lastAction) : undefined;
+            if (router !== undefined && step.kind !== 'stepToList' && step.kind !== 'stepToRef') {
+                throw new Error(`step "${lastAction}": its definition declares only templated exits (such as case-{item.id}), so no `
+                    + `path continues from it and ${'name' in step ? `"${step.name}"` : `.${step.kind}()`} after it would `
+                    + `have no incoming edge. Route each exit with .stepToList('<port>', …), e.g. .stepToList('case-<id>', …).`);
+            }
             if (step.kind === 'action') {
                 tails = emitAction(step, tails, scope, parentId);
                 applyUpdates(step);
@@ -6465,7 +6501,7 @@ export function serialize(built, opts = {}) {
                 }
             }
             else if (step.kind === 'stepToList') {
-                tails = emitPortList(step, lastAction ?? '?', tails, scope, parentId, breakTarget);
+                tails = emitPortList(step, lastAction ?? '?', tails, scope, parentId, loopExits);
             }
             else if (step.kind === 'stepSwitch') {
                 // The action, then EVERY exit it declares as an arm — no tacit tail.
@@ -6510,7 +6546,7 @@ export function serialize(built, opts = {}) {
                     // from all of them. (`.stepToList` instead gives an arm that runs out
                     // of steps an End of its own; `emitEnd` maps the outputs on it,
                     // flow-builder-sdk#742.)
-                    const caseTails = emit(c.body, [{ node: nodeId, port: exit.port }], scope, parentId, breakTarget);
+                    const caseTails = emit(c.body, [{ node: nodeId, port: exit.port }], scope, parentId, loopExits);
                     if (caseTails.length === 0 && stopsAtEnd(c.body))
                         stopped.push(String(c.value));
                     armTails.push(...(hitlNodes.has(nodeId)
@@ -6555,8 +6591,8 @@ export function serialize(built, opts = {}) {
                 scope.nodes.push(node);
                 for (const t of tails)
                     addEdge(scope, t, id);
-                const thenTails = emit(step.then, [{ node: id, port: 'true' }], scope, parentId, breakTarget);
-                const elseTails = emit(step.otherwise, [{ node: id, port: 'false' }], scope, parentId, breakTarget);
+                const thenTails = emit(step.then, [{ node: id, port: 'true' }], scope, parentId, loopExits);
+                const elseTails = emit(step.otherwise, [{ node: id, port: 'false' }], scope, parentId, loopExits);
                 tails = [...thenTails, ...elseTails];
             }
             else if (step.kind === 'switch') {
@@ -6571,8 +6607,11 @@ export function serialize(built, opts = {}) {
                 // the runtime — so no `=js:` prefix, same as a decision's `expression`.
                 const id = stepUid(scope, step.name);
                 const node = makeNode(NODE_TYPE.switch, id, step.options?.label ?? step.label ?? step.name, { parentId, requestedVersion: step.options?.version });
+                // `id` is the author's when given (a decompiled switch keeps the
+                // canvas's `default-1`, …: merge keeps the original node, so the edges
+                // must leave from ITS handles), else positional (#1130).
                 const cases = step.cases.map((c, i) => ({
-                    id: `case_${i + 1}`,
+                    id: c.id ?? `case_${i + 1}`,
                     label: c.label ?? `Case ${caseLiteral(c.value)}`,
                     expression: `${renameRefs(step.on.js, scope.rename)} === ${caseLiteral(c.value)}`,
                 }));
@@ -6585,9 +6624,9 @@ export function serialize(built, opts = {}) {
                 // merge node; the convergence point is found by graph search).
                 const armTails = [];
                 for (const [i, c] of step.cases.entries())
-                    armTails.push(...emit(c.body, [{ node: id, port: `case-${cases[i].id}` }], scope, parentId, breakTarget));
+                    armTails.push(...emit(c.body, [{ node: id, port: `case-${cases[i].id}` }], scope, parentId, loopExits));
                 if (step.default !== undefined)
-                    armTails.push(...emit(step.default, [{ node: id, port: 'default' }], scope, parentId));
+                    armTails.push(...emit(step.default, [{ node: id, port: 'default' }], scope, parentId, loopExits));
                 tails = armTails;
             }
             else if (step.kind === 'parallel') {
@@ -6620,7 +6659,7 @@ export function serialize(built, opts = {}) {
                 const armTails = [];
                 const endsBefore = hitlEndExits.length;
                 for (const arm of step.arms) {
-                    const t = emit(arm, tails, scope, parentId, breakTarget);
+                    const t = emit(arm, tails, scope, parentId, loopExits);
                     // An arm hands the join ONE edge, or several that are alternatives —
                     // `.branch` / `.switch` / `.stepSwitch` arms, a fan-out task's
                     // outcomes — of which only one fires. Refused when any of them is a
@@ -6705,7 +6744,7 @@ export function serialize(built, opts = {}) {
                     addEdge(scope, t, id);
                 const bodyPort = v24 ? 'start' : 'output';
                 const backPort = v24 ? 'continue' : 'loopBack';
-                const bodyTails = emit(step.body, [{ node: id, port: bodyPort }], scope, id, v24 ? { node: id, port: 'break' } : undefined);
+                const bodyTails = emit(step.body, [{ node: id, port: bodyPort }], scope, id, v24 ? { node: id, break: 'break', continue: backPort } : { node: id, continue: backPort });
                 for (const bt of bodyTails)
                     addEdge(scope, bt, id, backPort);
                 applyUpdates(step);
@@ -6724,18 +6763,29 @@ export function serialize(built, opts = {}) {
                 scope.nodes.push(node);
                 for (const t of tails)
                     addEdge(scope, t, id);
-                const bodyTails = emit(step.body, [{ node: id, port: 'start' }], scope, id, { node: id, port: 'break' });
+                const bodyTails = emit(step.body, [{ node: id, port: 'start' }], scope, id, { node: id, break: 'break', continue: 'continue' });
                 for (const bt of bodyTails)
                     addEdge(scope, bt, id, 'continue');
                 applyUpdates(step);
                 tails = [{ node: id, port: 'success' }];
             }
             else if (step.kind === 'break') {
-                if (!breakTarget) {
+                if (!loopExits?.break) {
                     throw new Error('.break() has no enclosing .loop()/.doWhile() body to exit — it is only valid inside a container.');
                 }
                 for (const t of tails)
-                    addEdge(scope, t, breakTarget.node, breakTarget.port);
+                    addEdge(scope, t, loopExits.node, loopExits.break);
+                tails = [];
+            }
+            else if (step.kind === 'continue') {
+                // The same edge a body's last step gets, from wherever this path has got
+                // to — so a handler or an arm can go on to the next iteration instead of
+                // ending the run on an End of its own (#1129).
+                if (!loopExits) {
+                    throw new Error('.continue() has no enclosing .loop()/.doWhile() body to go back to — it is only valid inside a container.');
+                }
+                for (const t of tails)
+                    addEdge(scope, t, loopExits.node, loopExits.continue);
                 tails = [];
             }
             else if (step.kind === 'terminate') {
@@ -6773,7 +6823,8 @@ export function serialize(built, opts = {}) {
                 else {
                     // Any other port is a SIDE EXIT from the step just emitted. The main
                     // path is untouched, so `tails` survives and chaining continues.
-                    const from = tails[0];
+                    const router = tails.length === 0 && lastAction !== undefined ? routerNodes.get(lastAction) : undefined;
+                    const from = tails[0] ?? (router !== undefined ? { node: router, port: step.port } : undefined);
                     if (!from)
                         throw new Error(`.stepToRef('${step.port}', '${step.target}') has no step to leave from.`);
                     refuseRewire('.stepToRef', step.port, lastAction ?? '?', tails);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.19.0",
+  "version": "6.20.1",
   "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": "75a7db3acd31187aec1aa0d4e7df67ec11b7985a"
+  "gitref": "5440c25e8e833aced459eb5a0ae9109ac3c973ae"
 }