@uipath/maestro-builder-sdk 6.20.5 → 6.21.0

package/dist/serialize.js

@@ -55,8 +55,9 @@ import { migrateToSchemaVersion } from './migrate.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 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 { 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';
@@ -119,8 +120,6 @@ const NODE_TYPE = {
     doWhile: 'core.logic.dowhile',
     subflow: 'core.subflow',
     terminate: 'core.logic.terminate',
-    queueCreate: 'core.action.queue.create',
-    queueCreateAndWait: 'core.action.queue.create-and-wait',
     // The two AI patterns. `summarize()` emits `deep-rag`: the canvas name is
     // "Summarize", the wire type is the backend's (`ECS.DeepRag`), and there is
     // no `uipath.pattern.summarize` node type at all.
@@ -2923,123 +2922,6 @@ function connectionResourceBindings(spec, existing) {
     });
     return { entries };
 }
-/**
- * Build the definition for one queue-item node.
- *
- * Unlike `rpaWorkflowDef`, this one starts from the BUNDLED definition — the queue
- * node types are generic (no tenant key in the type), so the platform's own copy
- * can be shipped and is: `core-definitions.json` carries both at `@1.2`, verbatim
- * from the catalogue the running `uip` consults (`@uipath/flow-core/manifest`'s
- * `ootbNodes`). A test pins that the emitted definition is that copy plus exactly
- * the three per-instance edits below, so the bundled snapshot stays diffable
- * against upstream.
- *
- * VERSION 1.2, not the 1.0 the bundled sample carries. The platform is two
- * migrations on, and both are semantic: 1.0 → 1.1 re-types `itemData` from
- * `string` to `object`, and 1.1 → 1.2 makes the field validate as an object
- * expression. `shared/sample-flows/queue-operations.flow` is v1.0-era (a JSON
- * STRING in `itemData`) and dated 2026-05-20 — the shape the platform no longer
- * writes. Reading it for the surface would have shipped the wrong field TYPE.
- *
- * The three per-instance edits:
- *
- *  - `model.bindings.resourceKey` — the queue's own Orchestrator key. The shipped
- *    definition ships it BLANK, because only an instance knows which queue.
- *  - `model.context` — the `=bindings.<id>` references. The definition ships
- *    `<bindings.name>` placeholders; an instance names the actual binding ids,
- *    which is the second way `resourceBindings` can be resolved and the
- *    shape the bundled sample has.
- *  - `outputDefinition.output.schema` — the queue item's record for a plain
- *    create, or the author's `returns` for a create-and-wait. Without a schema a
- *    downstream read is unresolvable.
- */
-function queueItemDef(spec, stepName, ids, version) {
-    const nodeType = spec.wait ? NODE_TYPE.queueCreateAndWait : NODE_TYPE.queueCreate;
-    // 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);
-    def.model.bindings.resourceKey = spec.key;
-    def.model.context = [
-        { name: 'name', type: 'string', value: `=bindings.${ids.name}`, default: spec.queue },
-        { name: 'folderPath', type: 'string', value: `=bindings.${ids.folderPath}`, default: spec.folderPath },
-        { name: '_label', type: 'string', value: stepName },
-    ];
-    const schema = spec.wait
-        ? (spec.returns && Object.keys(spec.returns).length
-            ? {
-                type: 'object',
-                properties: Object.fromEntries(Object.entries(spec.returns).map(([k, t]) => [k, { type: t }])),
-            }
-            : undefined)
-        : jsonClone(QUEUE_ITEM_RECORD_SCHEMA);
-    if (schema)
-        def.outputDefinition.output.schema = schema;
-    return def;
-}
-/**
- * The two bindings a queue reference carries — the same `name` + `folderPath` pair
- * the process families use, keyed to the queue's own Orchestrator key rather than
- * to a `<folderPath>.<name>` string. That is what the only queue instance the repo
- * has (`sample-flows/queue-operations.flow`) uses, and it is the queue's stable
- * identity: a queue can be renamed, its key cannot.
- *
- * ONE PAIR PER QUEUE, not per step. Bindings are addressed by
- * `resource + resourceKey + propertyAttribute` — that is the key a bindings
- * lookup map is built on — so a second pair for the same queue is not a second
- * reference, it is a duplicate that shadows the first: both nodes resolve to
- * whichever was inserted last, and the other pair sits in the file referenced by
- * nothing. So two steps on the same queue SHARE these, and the ids come from the
- * queue rather than from a step name.
- *
- * (The rpa family mints its pair from the STEP name, so two steps starting the same
- * process emit the same duplicate-and-shadow shape. Nothing exercises it today —
- * every rpa flow in the repo has one process step — and changing those ids would
- * rewrite the rpa goldens, so it is recorded as a finding rather than fixed here.)
- */
-function queueItemBindings(spec, existing) {
-    const found = (attr) => [...existing.values()].find((b) => b.resource === 'queue' && b.resourceKey === spec.key && b.propertyAttribute === attr)?.id;
-    const already = { name: found('name'), folderPath: found('folderPath') };
-    if (already.name && already.folderPath) {
-        return { ids: { name: already.name, folderPath: already.folderPath }, entries: [] };
-    }
-    // A readable, stable id per queue. Two queues that share a NAME across folders
-    // would collide, so the id is suffixed until it is free.
-    const slug = spec.queue.replace(/[^A-Za-z0-9]/g, '') || 'Queue';
-    let base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}`;
-    for (let n = 2; existing.has(`${base}Name`) || existing.has(`${base}FolderPath`); n++) {
-        base = `b${slug.charAt(0).toUpperCase()}${slug.slice(1)}${n}`;
-    }
-    const ids = { name: `${base}Name`, folderPath: `${base}FolderPath` };
-    return {
-        ids,
-        entries: [
-            {
-                id: ids.name,
-                name: 'name',
-                type: 'string',
-                resource: 'queue',
-                resourceKey: spec.key,
-                default: spec.queue,
-                propertyAttribute: 'name',
-            },
-            {
-                id: ids.folderPath,
-                name: 'folderPath',
-                type: 'string',
-                resource: 'queue',
-                resourceKey: spec.key,
-                default: spec.folderPath,
-                propertyAttribute: 'folderPath',
-            },
-        ],
-    };
-}
 /**
  * Encode a scheduled trigger's single `every` interval into the three inputs the
  * platform's node carries.
@@ -3589,10 +3471,11 @@ function applyAuthorLayout(layout, scope, where) {
  * identically into ExpressionValue envelopes.
  */
 function renderUpdates(updates, rename) {
-    return Object.entries(updates).map(([variableId, val]) => {
+    return Object.entries(updates).map(([name, val]) => {
         const expr = toExpr(val);
         const expression = expr.literal ? '=js:' + JSON.stringify(expr.value) : '=js:' + renameRefs(expr.js, rename);
-        return { variableId, expression };
+        // An output is never an update target: its backing Variable is (#1092).
+        return { variableId: rename.updates?.get(name) ?? name, expression };
     });
 }
 /**
@@ -3778,7 +3661,6 @@ export function bundledActionNodeType(spec) {
     switch (spec?.kind) {
         case 'http': return spec.inputs?.managed ? NODE_TYPE.httpV2 : NODE_TYPE.http;
         case 'hitl': return hitlNodeType(spec.inputs);
-        case 'queueItem': return spec.inputs?.wait ? NODE_TYPE.queueCreateAndWait : NODE_TYPE.queueCreate;
         case 'inlineAgent': return INLINE_AGENT_TYPE;
         case 'subflow':
         case 'summarize':
@@ -4263,7 +4145,14 @@ function emittableGlobals(built, where, kind = 'root') {
     if (plan.problems.length) {
         throw new Error(`${where}: ${plan.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
     }
-    return plan;
+    // An output the flow sets from inside gets an `inout` Variable to hold the
+    // value; the End copies it into the Output (#1092, `flow-output-backing.ts`).
+    const sharedOutputs = new Set(shared.targets.filter((t) => t.declaredAs === 'output').map((t) => t.name));
+    const backing = planOutputBacking(built, plan.outputs, plan.vars, sharedOutputs);
+    if (backing.problems.length) {
+        throw new Error(`${where}: ${backing.problems.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
+    }
+    return { ...plan, backing: backing.backing, backingReads: backing.reads };
 }
 /**
  * The flow's `{ shared }` input plan (#924), refused here as `check` refuses it
@@ -4284,17 +4173,20 @@ function sharedInputsOf(built, where, kind) {
         throw new Error(`${where}: ${errors.map((p) => `[${p.code}] ${p.message}`).join(' ')}`);
     return plan;
 }
-function newScope(outputs, vars = []) {
+function newScope(outputs, vars = [], backing = new Map(), backingReads = backing) {
+    const typeOf = new Map(outputs.map((o) => [o.name, o.type]));
     return {
         nodes: [],
         edges: [],
         variableUpdates: {},
-        outputType: new Map(outputs.map((o) => [o.name, o.type])),
+        outputType: typeOf,
         endVarType: new Map([
             ...outputs.map((o) => [o.name, o.type]),
+            ...[...backing].map(([o, b]) => [b, typeOf.get(o)]),
             ...vars.map((vd) => [vd.name, vd.type]),
         ]),
-        rename: { nodeIds: new Map(), errorEnvelopes: new Map() },
+        backing,
+        rename: { nodeIds: new Map(), errorEnvelopes: new Map(), vars: new Map(backingReads), updates: new Map(backing) },
         pending: new Map(),
         agentSchemas: [],
         stepNodeId: new Map(),
@@ -4535,11 +4427,11 @@ function isTypeDesc(type) {
  * An End node's `outputs` map: every variable this scope exposes as a flow
  * output, in declaration order.
  *
- * `explicit` holds the sources a `.return({…})` named. Everything else maps to
- * ITSELF (`$vars.<name>`) — "this output is whatever the variable holds when the
- * flow leaves here", which is what Studio Web wires when you add a variable to
- * an End node, and the only sensible reading for a `.var(…)` counter or an
- * output another branch returns.
+ * `explicit` holds the sources a `.return({…})` named. Everything else gets
+ * `fillInSource`: a Variable maps to ITSELF (`$vars.<name>`), "whatever it holds
+ * when the flow leaves here"; an output maps from its backing Variable when a
+ * step sets it, else to `null` (#1092). An End never reads `$vars.<output>`:
+ * Studio Web does not declare Outputs on `$vars`.
  *
  * Emitting the full set is not cosmetic. The product's output-mapping rule warns
  * `MISSING_OUTPUT_MAPPING` once per (End node × unmapped output variable), and
@@ -4552,8 +4444,7 @@ function isTypeDesc(type) {
 function endOutputs(scope, explicit = {}) {
     const outs = {};
     for (const [name, type] of scope.endVarType) {
-        const source = explicit[name] ?? `=js:$vars.${name}`;
-        outs[name] = { type, description: '', source, var: name };
+        outs[name] = { type, description: '', source: explicit[name] ?? fillInSource(scope, name), var: name };
     }
     // A `.return(…)` naming something the flow never declared is a check() error
     // (RETURN_UNDECLARED), but serialize must not silently swallow the mapping if
@@ -4564,6 +4455,23 @@ function endOutputs(scope, explicit = {}) {
     }
     return outs;
 }
+/**
+ * What an End maps a variable to when no `.return()` named it here.
+ *
+ * - A Variable (`inout`, a backing one included) maps to itself: "whatever it
+ *   holds when the flow leaves here".
+ * - An Output with a backing Variable maps from that Variable (#1092).
+ * - Any other Output was never set on the way (only `.return()` values set
+ *   it, and this End returns none), so it maps to `null`. That is the value the
+ *   old `$vars.<output>` read gave on this path, without reading an Output,
+ *   which Studio Web does not allow.
+ */
+function fillInSource(scope, name) {
+    if (!scope.outputType.has(name))
+        return `=js:$vars.${name}`;
+    const backing = scope.backing.get(name);
+    return backing ? `=js:$vars.${backing}` : '=js:null';
+}
 /**
  * A Terminate event has no action result, but it is still a terminal event. The
  * product's output-mapping validator therefore requires every flow output on it,
@@ -4586,19 +4494,23 @@ function terminateOutputs(scope) {
  * same name (an error in its own right — DUP_STEP).
  */
 function renameRefs(text, rename) {
-    if (rename.nodeIds.size === 0 && rename.errorEnvelopes.size === 0)
+    if (rename.nodeIds.size === 0 && rename.errorEnvelopes.size === 0 && !rename.vars?.size)
         return text;
     // `.error` matches only with a FIELD behind it: a bare `$vars.<step>.error` is
     // the boolean "did this fail" (`err('<step>')`), which is truthy on every
     // family — the envelope object included — and must be left alone.
-    return text.replace(/\$vars\.([A-Za-z0-9_]+)(\.error(?=\.[A-Za-z0-9_]))?/g, (m, name, tail) => {
+    // Only code is rewritten: `"$vars.summary"` in a script is text (#1092).
+    return mapJsCode(text, (code) => code.replace(/\$vars\.([A-Za-z0-9_]+)(\.error(?=\.[A-Za-z0-9_]))?/g, (m, name, tail) => {
+        const backing = rename.vars?.get(name);
+        if (backing)
+            return `$vars.${backing}${tail ?? ''}`;
         const to = rename.nodeIds.get(name);
         const nodeId = to && to.length > 0 ? to[0] : name;
         if (!tail)
             return nodeId === name ? m : `$vars.${nodeId}`;
         const envelope = rename.errorEnvelopes.get(name) ?? 'error';
         return `$vars.${nodeId}.${envelope}`;
-    });
+    }));
 }
 /** Every step name a flow declares in its own scope (not its children's). */
 function stepNamesOf(steps, out = []) {
@@ -4743,7 +4655,7 @@ export function serialize(built, opts = {}) {
     const sidecars = opts.sidecars ?? [];
     const subflows = {};
     const rootGlobals = emittableGlobals(built, `flow "${built.id}"`);
-    const root = newScope(rootGlobals.outputs, rootGlobals.vars);
+    const root = newScope(rootGlobals.outputs, rootGlobals.vars, rootGlobals.backing, rootGlobals.backingReads);
     // `input('x')` lowers eagerly to `$vars.start.output.x` — `start` being the
     // trigger node's default id. When the flow renames the trigger, register that
     // rename so the SAME pass that rewrites step-name references rewrites these
@@ -4920,7 +4832,7 @@ export function serialize(built, opts = {}) {
      */
     function emitSubflowBody(child, nodeId) {
         const childGlobals = emittableGlobals(child, `subflow "${nodeId}"`, 'subflow');
-        const scope = newScope(childGlobals.outputs, childGlobals.vars);
+        const scope = newScope(childGlobals.outputs, childGlobals.vars, childGlobals.backing, childGlobals.backingReads);
         // Claim this copy's node ids UP FRONT, so the rename map is complete before
         // the first expression renders. A child's step names are free the first
         // time it runs; if any of them is already taken — which is what a second
@@ -4958,6 +4870,11 @@ export function serialize(built, opts = {}) {
             globals.push({ id: inp.name, name: inp.name, direction: 'in', type: inp.type, triggerNodeId: startId, ...varMeta(inp) });
         for (const o of childGlobals.outputs)
             globals.push({ id: o.name, name: o.name, direction: 'out', type: o.type, ...varMeta(o) });
+        for (const o of childGlobals.outputs) {
+            const b = childGlobals.backing.get(o.name);
+            if (b)
+                globals.push(outputBackingGlobal(o, b));
+        }
         for (const vd of childGlobals.vars)
             globals.push({ id: vd.name, name: vd.name, direction: 'inout', type: vd.type, ...varMeta(vd) });
         resolveRejoins(scope, addEdge);
@@ -5080,10 +4997,6 @@ export function serialize(built, opts = {}) {
             return 'default';
         if (type === NODE_TYPE.loop)
             return 'success';
-        // Both queue definitions declare exactly one source handle, `success` — and
-        // the shipped `sample-flows/queue-operations.flow` wires its edges to it.
-        if (type === NODE_TYPE.queueCreate || type === NODE_TYPE.queueCreateAndWait)
-            return 'success';
         // Every human-task definition declares one static source handle, `completed`.
         // It is the real exit only where the product draws it: action-app,
         // document-validation, and a task with no outcomes. A base or quick-form task
@@ -5205,6 +5118,7 @@ export function serialize(built, opts = {}) {
             mint: (seed) => stableId(`${built.id}:${id}:${seed}`),
             bind: (b) => { bound.push(b); },
             definition: (typeName, version) => bundledDefinition(typeName, version),
+            bindings: resourceBindings,
         };
         const bound = [];
         const contribution = impl.serialize(spec, ctx);
@@ -5965,42 +5879,6 @@ export function serialize(built, opts = {}) {
                 addEdge(scope, t, id);
             return [{ node: id, port: successPort(def.nodeType) }];
         }
-        if (spec.kind === 'queueItem') {
-            const s = spec.inputs;
-            // The bindings first: two steps on the same queue share one pair, and the
-            // node's `model.context` has to name the ids that actually exist.
-            const { ids, entries } = queueItemBindings(s, resourceBindings);
-            for (const b of entries)
-                resourceBindings.set(b.id, b);
-            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
-            // `output` (`source: "=response", var: "output"`), and the product honours
-            // that mapping for both queue variants. (An alias to `.response` lived here
-            // from #273 until #891; a live debug run on 2026-10-01 measured
-            // `.output.Key` populated and `.response` undefined.)
-            const node = makeNode(def.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def });
-            // The node KEEPS its copy of the model here, unlike the rpa families. Two
-            // reasons: it is what the one queue instance the repo has carries, and it is
-            // what `makeNode` does for every other core action node with a model (http,
-            // script, transform). The model resolves from either place since #94, and a
-            // bindings lookup reads node-first for the same reason.
-            node.inputs = {
-                queue: { name: s.queue, folderPath: s.folderPath, key: s.key },
-                // `itemData`, not `item`: the surface's name is friendlier, the node's is
-                // the platform's. The reference documents the mapping.
-                itemData: renderMap(s.item ?? {}, scope.rename),
-                priority: s.priority ?? 'Normal',
-                reference: s.reference === undefined ? '' : renderValue(s.reference, scope.rename),
-                deferDate: s.deferDate === undefined ? '' : renderValue(s.deferDate, scope.rename),
-                dueDate: s.dueDate === undefined ? '' : renderValue(s.dueDate, scope.rename),
-            };
-            scope.nodes.push(node);
-            for (const t of tails)
-                addEdge(scope, t, id);
-            return [{ node: id, port: successPort(def.nodeType) }];
-        }
         if (spec.kind === 'conversationalAgent') {
             // The text CONVERSATIONAL agent: the inline agent's cluster shape (a
             // minted `source` plus an `agent.json` sidecar) with the family's own
@@ -6919,10 +6797,14 @@ export function serialize(built, opts = {}) {
                 for (const [name, expr] of Object.entries(step.values)) {
                     const src = expr.literal ? '=js:' + JSON.stringify(expr.value) : '=js:' + renameRefs(expr.js, scope.rename);
                     explicit[name] = src;
-                    // Only the values the author actually RETURNED are written back to the
-                    // variable. The identity mappings `endOutputs` fills in read a
-                    // variable; a variableUpdate for one would be a no-op assignment.
-                    updates.push({ variableId: name, expression: src });
+                    // The End's output mapping is what sets an Output; Studio Web writes
+                    // no variable update for it (`end-node-sets-output.flow`), and an
+                    // Output is not an update target (#1092). A returned `.var()` is a
+                    // Variable, so it is still written back. The identity mappings
+                    // `endOutputs` fills in read a variable; an update for one would be
+                    // a no-op assignment.
+                    if (!scope.outputType.has(name))
+                        updates.push({ variableId: name, expression: src });
                 }
                 emitEnd(scope, id, tails, { label: step.options?.label, parentId, requestedVersion: step.options?.version, explicit });
                 const extra = step.options?.updates ?? {};
@@ -7073,6 +6955,11 @@ export function serialize(built, opts = {}) {
         globals.push({ id: inp.name, name: inp.name, direction: 'in', type: inp.type, triggerNodeId, ...varMeta(inp) });
     for (const o of rootGlobals.outputs)
         globals.push({ id: o.name, name: o.name, direction: 'out', type: o.type, ...varMeta(o) });
+    for (const o of rootGlobals.outputs) {
+        const b = rootGlobals.backing.get(o.name);
+        if (b)
+            globals.push(outputBackingGlobal(o, b));
+    }
     for (const vd of rootGlobals.vars)
         globals.push({ id: vd.name, name: vd.name, direction: 'inout', type: vd.type, ...varMeta(vd) });
     for (const ep of entryPoints) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.20.5",
+  "version": "6.21.0",
   "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": "2ed3ce64cea5047f9da44c287cacc18f0f66f37d"
+  "gitref": "c72d3cea4a18fc9bad9e6a10a817f7534b6de674"
 }