@uipath/maestro-builder-sdk 6.20.4 → 6.20.6

package/dist/flow-sdk.js

@@ -1176,6 +1176,16 @@ class FlowBuilder extends StepList {
      * second variable (its default becomes the output's); a different type is a
      * `check` error, `OUTPUT_VAR_MISMATCH`.
      *
+     * In the `.flow`, Studio Web sets an Output only on an End node, and neither
+     * Update Variable nor an expression can touch one. So an output that the flow
+     * sets or reads from inside (`{ updates }`, a `{ shared }` input, a
+     * `default`, or a `v('<name>')` read) is emitted with a backing Variable,
+     * `<name>Value` (`direction: 'inout'`): updates and reads go to the Variable,
+     * and every End maps the output from it. That id must be free; a step,
+     * input or `.var()` already called `<name>Value` is a `check` error,
+     * `OUTPUT_BACKING_COLLISION`. An output only `.return({ … })` sets needs no
+     * Variable: an End that does not name it maps `null`.
+     *
      * @example
      * **A loop accumulator**
      * ```ts

package/dist/flow-variables.d.ts

@@ -54,10 +54,12 @@ export interface FlowGlobalsPlan<D extends DeclaredVariable = DeclaredVariable>
  * `@uipath/maestro-sdk` (the code that turns a `.flow` into what runs):
  * - only an `out` global is a flow OUTPUT at the root — `buildNodeOutputMappings`
  *   drops an End node's mapping for any id that is not `direction: 'out'`;
- * - `inout` is published as an INPUT too — solution discovery puts it on the
- *   entry point's input schema — so `inout` would widen the caller's contract;
- * - `{ updates }` on an `out` global is the same output mapping (`var: <id>`) as
- *   on an `inout` one, so a loop body can read and rewrite it mid-run;
+ * - `inout` is not part of the caller's contract either way: `@uipath/flow-schema`
+ *   packaging builds the entry-point input schema from `in` globals bound to the
+ *   trigger, and the output schema from `out` globals only;
+ * - a loop body that reads and rewrites the value mid-run does so through the
+ *   output's backing `inout` Variable (`flow-output-backing.ts`, #1092), because
+ *   Studio Web neither updates nor reads an Output;
  * - the `default` on `<uipath:output>` is serialized (`collectVariablesFromNodes`)
  *   and a subflow seeds its `out` globals from `defaultValue ?? null`
  *   (`buildSeedTask`). The v1 CLI's `variable add --direction out

package/dist/flow-variables.js

@@ -58,10 +58,12 @@ const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
  * `@uipath/maestro-sdk` (the code that turns a `.flow` into what runs):
  * - only an `out` global is a flow OUTPUT at the root — `buildNodeOutputMappings`
  *   drops an End node's mapping for any id that is not `direction: 'out'`;
- * - `inout` is published as an INPUT too — solution discovery puts it on the
- *   entry point's input schema — so `inout` would widen the caller's contract;
- * - `{ updates }` on an `out` global is the same output mapping (`var: <id>`) as
- *   on an `inout` one, so a loop body can read and rewrite it mid-run;
+ * - `inout` is not part of the caller's contract either way: `@uipath/flow-schema`
+ *   packaging builds the entry-point input schema from `in` globals bound to the
+ *   trigger, and the output schema from `out` globals only;
+ * - a loop body that reads and rewrites the value mid-run does so through the
+ *   output's backing `inout` Variable (`flow-output-backing.ts`, #1092), because
+ *   Studio Web neither updates nor reads an Output;
  * - the `default` on `<uipath:output>` is serialized (`collectVariablesFromNodes`)
  *   and a subflow seeds its `out` globals from `defaultValue ?? null`
  *   (`buildSeedTask`). The v1 CLI's `variable add --direction out

package/dist/serialize.d.ts

@@ -122,6 +122,26 @@ export declare function perCallDefinition(spec: {
     kind?: string;
     inputs?: any;
 } | undefined): any | undefined;
+/**
+ * The definition version serialize emits for a typed action step that is not
+ * yet on the node-type registry: the author's `{ version }` when given,
+ * otherwise the version the step's inputs select, otherwise `undefined` (the
+ * pinned default). Two such families pick a version themselves:
+ *
+ *  - `hitl`: `exposeError` selects `@1.2`, per-outcome routing selects `@1.1`;
+ *  - `inlineAgent`: the newest bundled version, not the first bundled entry.
+ *
+ * The emit paths read their version here, and `check` resolves the definition
+ * it asks about with this same version (#1041), so the two cannot pick
+ * different definitions. For instance `inlineAgent({ ... })` gives the newest
+ * bundled version in both. A registered family (e.g. `dataFabricRead`, whose
+ * `resultMode` selects `core.datafabric.read@1.4`) gets the same guarantee from
+ * the registry's `resolveVersion`, which check and serialize both call.
+ */
+export declare function actionVersion(spec: {
+    kind?: string;
+    inputs?: any;
+} | undefined, explicit: string | undefined): string | undefined;
 /**
  * The bundled definition of `nodeType` that `makeNode` resolves: the author's
  * exact `{ version }` when given, otherwise the pinned default (the first

package/dist/serialize.js

@@ -55,6 +55,8 @@ 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';
@@ -3589,10 +3591,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 };
     });
 }
 /**
@@ -3836,6 +3839,45 @@ export function perCallDefinition(spec) {
         default: return undefined;
     }
 }
+/**
+ * The definition version serialize emits for a typed action step that is not
+ * yet on the node-type registry: the author's `{ version }` when given,
+ * otherwise the version the step's inputs select, otherwise `undefined` (the
+ * pinned default). Two such families pick a version themselves:
+ *
+ *  - `hitl`: `exposeError` selects `@1.2`, per-outcome routing selects `@1.1`;
+ *  - `inlineAgent`: the newest bundled version, not the first bundled entry.
+ *
+ * The emit paths read their version here, and `check` resolves the definition
+ * it asks about with this same version (#1041), so the two cannot pick
+ * different definitions. For instance `inlineAgent({ ... })` gives the newest
+ * bundled version in both. A registered family (e.g. `dataFabricRead`, whose
+ * `resultMode` selects `core.datafabric.read@1.4`) gets the same guarantee from
+ * the registry's `resolveVersion`, which check and serialize both call.
+ */
+export function actionVersion(spec, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    // Keyed by the node type `bundledActionNodeType` already picks, so the
+    // version rule adds no second dispatch on the step's kind.
+    const type = bundledActionNodeType(spec);
+    if (type === NODE_TYPE.hitl)
+        return hitlNeededVersion(spec?.inputs);
+    if (type === INLINE_AGENT_TYPE)
+        return INLINE_AGENT_DEFAULT_VERSION;
+    return undefined;
+}
+/**
+ * The base human task version a task's inputs need when nothing is pinned:
+ * `exposeError` needs 1.2 (it adds the `error` output), and a task that
+ * routes per outcome needs 1.1. Only the base task reaches here: a variant
+ * (quick-form, app task) has its own node type and one definition.
+ */
+function hitlNeededVersion(inputs) {
+    if (inputs?.exposeError)
+        return '1.2';
+    return hitlExitModel(inputs, undefined).shape === 'per-outcome' ? '1.1' : undefined;
+}
 /**
  * The bundled definition of `nodeType` that `makeNode` resolves: the author's
  * exact `{ version }` when given, otherwise the pinned default (the first
@@ -4224,7 +4266,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
@@ -4245,17 +4294,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(),
@@ -4496,11 +4548,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
@@ -4513,8 +4565,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
@@ -4525,6 +4576,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,
@@ -4547,19 +4615,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 = []) {
@@ -4704,7 +4776,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
@@ -4881,7 +4953,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
@@ -4919,6 +4991,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);
@@ -5356,7 +5433,7 @@ export function serialize(built, opts = {}) {
             // the node to another version as a side effect (#956). Both now live in
             // the sidecar and on edges; neither selects a definition. An explicit
             // `{ version }` (what decompile writes back) resolves exactly.
-            const version = step.options?.version ?? INLINE_AGENT_DEFAULT_VERSION;
+            const version = actionVersion(spec, step.options?.version);
             // `definitions[]` holds one entry per type@version, so a flow where any
             // agent attaches memory keeps the handle for all of them.
             const withMemory = s.memory !== undefined
@@ -6278,13 +6355,12 @@ export function serialize(built, opts = {}) {
                 throw new Error(`"${step.name}": outcomePorts: true, but the '${spec.inputs?.variant}' variant reads its outcomes `
                     + `from its app and leaves on its single 'completed' exit. Route on out('${step.name}', 'Action') downstream.`);
             }
-            const neededVersion = hitlType !== NODE_TYPE.hitl ? undefined
-                : spec.inputs?.exposeError ? '1.2' : exitModel.shape === 'per-outcome' ? '1.1' : undefined;
             if (spec.inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
                 throw new Error(`"${step.name}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
                     + `Drop the pin or match it.`);
             }
-            const node = makeNode(hitlType, id, step.name, { parentId, requestedVersion: pinned ?? neededVersion });
+            // The same version `check` resolves the definition at (#1041).
+            const node = makeNode(hitlType, id, step.name, { parentId, requestedVersion: actionVersion(spec, pinned) });
             const { inputs, outputs } = hitlInputs(spec.inputs, id, built.id, step.name, scope.rename);
             node.inputs = inputs;
             // The definition's `outputDefinition` gives the two output SLOTS; the form
@@ -6881,10 +6957,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 ?? {};
@@ -7035,6 +7115,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.4",
+  "version": "6.20.6",
   "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": "7dcc7ebc0420e1fca8be0368269c8f20ff60eff6"
+  "gitref": "124c0cac0f49d9974da5619817458d4d8760a91f"
 }