@uipath/maestro-builder-sdk 6.71.0 → 6.72.0

package/dist/core/script-function.js

@@ -77,18 +77,18 @@ export function scriptBodySyntaxError(code) {
 }
 /**
  * The JavaScript engine's early error for a body run as
- * `function (<scopeGlobal>) { "use strict"; <code> }`, or undefined when it has
+ * `function (<params>) { "use strict"; <code> }`, or undefined when it has
  * none.
  *
  * TypeScript's parser does not report early errors (a duplicate `let`, a
- * `const $vars` that clashes with the parameter, an octal literal in strict
+ * `const $vars` that clashes with a parameter, an octal literal in strict
  * code), and the printed function lives in an ES module, which is strict. A body
  * with one would make the whole module unloadable, so decompile asks the engine.
  * The body is compiled, never called. A host without the `Function`
  * constructor (a strict content-security policy) cannot answer, which is
  * reported as an error too, so the caller keeps the string form.
  */
-export function scriptBodyEarlyError(code, runtime) {
+export function scriptBodyEarlyError(code, params) {
     // Compiled for their early errors only; neither is invoked. Module code also
     // reserves `await`, which no synchronous constructor reports: an async
     // function reserves it the same way, so a body must compile as both. (A
@@ -96,8 +96,8 @@ export function scriptBodyEarlyError(code, runtime) {
     // the module's plain function.)
     const AsyncFunction = (async () => { }).constructor;
     try {
-        new Function(runtime.scopeGlobal, `"use strict";\n${code}`);
-        new AsyncFunction(runtime.scopeGlobal, `"use strict";\n${code}`);
+        new Function(...params, `"use strict";\n${code}`);
+        new AsyncFunction(...params, `"use strict";\n${code}`);
         return undefined;
     }
     catch (e) {
@@ -167,6 +167,7 @@ function functionName(fn) {
         return fn.name || undefined;
     return /^\s*(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/.exec(fn)?.[1];
 }
+const ORDINALS = ['first', 'second', 'third', 'fourth'];
 class Lowering {
     ts;
     sf;
@@ -177,9 +178,9 @@ class Lowering {
     problems = [];
     edits = [];
     free = new Set();
-    aliased = new Set();
-    param;
-    paramSymbol;
+    aliased = new Map();
+    read = new Set();
+    params = [];
     ownNameSymbol;
     constructor(ts, sf, fn, runtime, options) {
         this.ts = ts;
@@ -196,18 +197,18 @@ class Lowering {
             return { ok: false, problems: this.problems, free: [] };
         if (ts.isFunctionExpression(fn) && fn.name)
             this.ownNameSymbol = this.checker.getSymbolAtLocation(fn.name);
-        const renaming = this.param !== undefined && this.param.text !== this.runtime.scopeGlobal;
-        if (renaming) {
-            this.checkNoCapture();
-            this.checkNoRedeclaredParameter();
+        for (const param of this.params) {
+            if (param.id.text === param.scope.global)
+                continue;
+            this.checkNoCapture(param.scope.global);
+            this.checkNoRedeclaredParameter(param);
         }
         this.checkConstGlobals();
         this.visit(fn.body, 0);
-        if (this.aliased.size > 0) {
-            const name = [...this.aliased][0];
-            this.problems.push(`it uses its parameter \`${name}\` other than as a dotted read (\`${name}.start.output.x\`): an alias, a computed or optional read, `
-                + `or passing \`${name}\` on hides the step it reads from the step renaming and reference checks, which see only \`${this.runtime.scopeGlobal}.<step>\`. `
-                + 'Read each step with dots.');
+        for (const [name, scope] of this.aliased) {
+            this.problems.push(`it uses its parameter \`${name}\` other than as a dotted read (\`${name}.${scope.example}\`): an alias, a computed or optional read, `
+                + `or passing \`${name}\` on hides the ${scope.reads} it reads from ${scope.checkedBy}, which see only \`${scope.global}.<${scope.reads}>\`. `
+                + `Read each ${scope.reads} with dots.`);
         }
         const free = [...this.free].sort();
         if (free.length > 0) {
@@ -216,7 +217,9 @@ class Lowering {
         }
         if (this.problems.length > 0)
             return { ok: false, problems: this.problems, free };
-        return { ok: true, code: this.body() };
+        const scopesRead = this.runtime.scopes.filter((s) => this.read.has(s)).map((s) => s.global);
+        const scopesDeclared = this.runtime.scopes.filter((s) => this.bindsInFunctionScope(s.global)).map((s) => s.global);
+        return { ok: true, code: this.body(), scopesRead, scopesDeclared };
     }
     /** The function forms that cannot become a body at all. */
     checkShape() {
@@ -226,34 +229,49 @@ class Lowering {
             this.problems.push('it is `async`; a script body runs synchronously.');
         if (ts.isFunctionExpression(fn) && fn.asteriskToken)
             this.problems.push('it is a generator; a script body returns one value.');
-        if (fn.parameters.length > 1) {
-            this.problems.push(`it takes ${fn.parameters.length} parameters; a script function takes one, the runtime's variable scope (${this.runtime.scopeGlobal}), or none.`);
-            return;
-        }
-        const p = fn.parameters[0];
-        if (!p)
+        const { scopes } = this.runtime;
+        if (fn.parameters.length > scopes.length) {
+            const order = scopes.map((s) => `${s.holds} (${s.global})`);
+            this.problems.push(scopes.length === 1
+                ? `it takes ${fn.parameters.length} parameters; a script function takes one, ${order[0]}, or none.`
+                : `it takes ${fn.parameters.length} parameters; a script function takes at most ${scopes.length}, in this order: ${order.join(', ')}.`);
             return;
-        if (p.dotDotDotToken)
-            this.problems.push('its parameter is a rest parameter; take the variable scope as one plain parameter.');
-        else if (p.initializer)
-            this.problems.push('its parameter has a default value; the runtime always supplies the variable scope.');
-        else if (!ts.isIdentifier(p.name)) {
-            this.problems.push('its parameter is destructured. Take the variable scope as one plain parameter and read it with dots '
-                + `(\`vars.start.output.x\`): a destructured read is invisible to the step renaming and reference checks that read \`${this.runtime.scopeGlobal}.<step>\`.`);
-        }
-        else {
-            this.param = p.name;
-            this.paramSymbol = this.checker.getSymbolAtLocation(p.name);
         }
+        fn.parameters.forEach((p, i) => {
+            const scope = scopes[i];
+            const its = fn.parameters.length > 1 ? `its ${ORDINALS[i]} parameter` : 'its parameter';
+            if (p.dotDotDotToken)
+                this.problems.push(`${its} is a rest parameter; take ${scope.holds} as one plain parameter.`);
+            else if (p.initializer)
+                this.problems.push(`${its} has a default value; the runtime always supplies ${scope.holds}.`);
+            else if (!ts.isIdentifier(p.name)) {
+                this.problems.push(`${its} is destructured. Take ${scope.holds} as one plain parameter and read it with dots `
+                    + `(\`${scope.param}.${scope.example}\`): a destructured read is invisible to ${scope.checkedBy} that read \`${scope.global}.<${scope.reads}>\`.`);
+            }
+            else {
+                // Parameters bind by position, so one named like another scope would be
+                // renamed to its own scope's global and read that scope instead:
+                // `($metadata) => $metadata.InstanceId` would read `$vars.InstanceId`.
+                const name = p.name.text;
+                const named = scopes.find((other) => other !== scope && other.global === name);
+                if (named) {
+                    this.problems.push(`${its} is named \`${named.global}\` but receives ${scope.holds} (${scope.global}): parameters bind by position, `
+                        + `and \`${named.global}\` is the ${ORDINALS[scopes.indexOf(named)]} one. `
+                        + `Take them in order, \`(${scopes.map((s) => s.global).join(', ')}) => …\`, or give this one another name.`);
+                }
+                else {
+                    this.params.push({ id: p.name, symbol: this.checker.getSymbolAtLocation(p.name), scope });
+                }
+            }
+        });
     }
     /**
-     * Refuse a binding named like the scope global anywhere in the function: once
-     * the parameter's references are rewritten to that name, the binding would
+     * Refuse a binding named like a scope global anywhere in the function: once
+     * a parameter's references are rewritten to that name, the binding would
      * capture them (`const $vars = {…}; return vars.x` would read the local).
      */
-    checkNoCapture() {
+    checkNoCapture(target) {
         const { ts } = this;
-        const target = this.runtime.scopeGlobal;
         let found = false;
         const visit = (n) => {
             if (found)
@@ -269,6 +287,38 @@ class Lowering {
                 + `Rename the inner binding, or name the parameter \`${target}\` so nothing is renamed.`);
         }
     }
+    /**
+     * Whether the body binds `name` in the function's own scope: a top-level
+     * `let`, `const`, `class` or `function` (a label does not scope what it
+     * labels), or a `var` anywhere outside a nested function, which hoists.
+     */
+    bindsInFunctionScope(name) {
+        const { ts } = this;
+        const body = this.fn.body;
+        if (!ts.isBlock(body))
+            return false;
+        for (let stmt of body.statements) {
+            while (ts.isLabeledStatement(stmt))
+                stmt = stmt.statement;
+            if (ts.isVariableStatement(stmt) && stmt.declarationList.declarations.some((d) => bindsName(ts, d.name, name)))
+                return true;
+            if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) && stmt.name?.text === name)
+                return true;
+        }
+        let found = false;
+        const vars = (n) => {
+            if (found || ts.isFunctionLike(n) || ts.isClassLike(n))
+                return;
+            if (ts.isVariableDeclarationList(n) && (n.flags & ts.NodeFlags.BlockScoped) === 0
+                && n.declarations.some((d) => bindsName(ts, d.name, name))) {
+                found = true;
+                return;
+            }
+            ts.forEachChild(n, vars);
+        };
+        ts.forEachChild(body, vars);
+        return found;
+    }
     /**
      * Refuse a `var vars` or `function vars() {}` in the body: either binds the
      * parameter's own name in the function's scope, so the rename would rewrite the
@@ -278,9 +328,9 @@ class Lowering {
      * still resolving the reads to the parameter. A nested function (arrows
      * included) has its own `var` scope, so its declarations are its own.
      */
-    checkNoRedeclaredParameter() {
+    checkNoRedeclaredParameter(param) {
         const { ts } = this;
-        const name = this.param.text;
+        const name = param.id.text;
         let found = false;
         const visit = (n) => {
             if (found)
@@ -303,7 +353,7 @@ class Lowering {
         };
         visit(this.fn.body);
         if (found) {
-            this.problems.push(`it redeclares its parameter \`${name}\` (a \`var\` or a function declaration), which the rename to \`${this.runtime.scopeGlobal}\` would split from its reads. `
+            this.problems.push(`it redeclares its parameter \`${name}\` (a \`var\` or a function declaration), which the rename to \`${param.scope.global}\` would split from its reads. `
                 + 'Give the local a name of its own.');
         }
     }
@@ -445,14 +495,18 @@ class Lowering {
         const parent = id.parent;
         const shorthand = ts.isShorthandPropertyAssignment(parent) && parent.name === id;
         const symbol = shorthand ? this.checker.getShorthandAssignmentValueSymbol(parent) : this.checker.getSymbolAtLocation(id);
-        if (symbol && symbol === this.paramSymbol) {
+        const param = symbol ? this.params.find((p) => p.symbol === symbol) : undefined;
+        if (param) {
+            const { scope } = param;
+            this.read.add(scope);
             if (this.options.scopeReadsOnly && !(ts.isPropertyAccessExpression(parent) && parent.expression === id && !parent.questionDotToken)) {
-                this.aliased.add(id.text);
+                if (!this.aliased.has(id.text))
+                    this.aliased.set(id.text, scope);
             }
-            if (this.param.text !== this.runtime.scopeGlobal) {
+            if (param.id.text !== scope.global) {
                 this.edits.push(shorthand
-                    ? [id.getStart(), id.end, `${id.text}: ${this.runtime.scopeGlobal}`]
-                    : [id.getStart(), id.end, this.runtime.scopeGlobal]);
+                    ? [id.getStart(), id.end, `${id.text}: ${scope.global}`]
+                    : [id.getStart(), id.end, scope.global]);
             }
             return;
         }
@@ -471,7 +525,7 @@ class Lowering {
         }
         if (symbol && !isUndefinedSymbol(symbol))
             return;
-        if (id.text === this.runtime.scopeGlobal || this.runtime.globals.has(id.text)) {
+        if (this.runtime.scopes.some((s) => s.global === id.text) || this.runtime.globals.has(id.text)) {
             this.checkGlobalMember(id);
             return;
         }
@@ -541,7 +595,7 @@ class Lowering {
     }
 }
 /** The checker of a one-file program over `sf`, with no default library: globals resolve to nothing. */
-function oneFileChecker(ts, sf) {
+export function oneFileChecker(ts, sf) {
     const options = { noLib: true, noResolve: true, types: [], target: ts.ScriptTarget.ES2020 };
     const host = {
         getSourceFile: (name) => (name === sf.fileName ? sf : undefined),
@@ -557,7 +611,7 @@ function oneFileChecker(ts, sf) {
     return ts.createProgram({ rootNames: [sf.fileName], options, host }).getTypeChecker();
 }
 /** The checker's own symbol for `undefined`, which a no-lib program still binds. */
-function isUndefinedSymbol(s) {
+export function isUndefinedSymbol(s) {
     return s.escapedName === 'undefined' && (s.declarations?.length ?? 0) === 0;
 }
 /** Whether `id` is read as a value, not a property name, label, or type. */

package/dist/nodes/process/flow/check.js

@@ -33,6 +33,9 @@ export const PROCESS_DIAGNOSTICS = {
     AGENTIC_RESERVED_INPUT: { severity: 'error', summary: 'an agentic process step with the reserved fireAndForget input' },
     APIWF_EMPTY_RETURNS: { severity: 'warning', summary: 'an API workflow step with returns: {}' },
     APIWF_KEY_NOT_KEY: { severity: 'error', summary: 'an API workflow step whose key is not a GUID' },
+    APIWF_LOCAL_HAS_FOLDER: { severity: 'error', summary: 'an API workflow step in-solution, with a folderPath' },
+    APIWF_LOCAL_NO_PROJECT_ID: { severity: 'error', summary: 'an API workflow step in-solution, with no projectId' },
+    APIWF_LOCAL_PROJECT_ID_NOT_GUID: { severity: 'error', summary: 'an API workflow step in-solution, with a projectId that is not a GUID' },
     APIWF_NAME_IS_PATH: { severity: 'error', summary: 'an API workflow step whose name looks like a folder path' },
     APIWF_NO_FOLDER: { severity: 'error', summary: 'an API workflow step with no folderPath' },
     APIWF_NO_KEY: { severity: 'error', summary: 'an API workflow step with no key' },
@@ -157,10 +160,21 @@ export function checkApiWorkflow(inputs, ctx) {
         at('APIWF_NO_NAME', `API workflow step "${step}" has no \`name\`. The runtime starts the job by name + folder, not by the `
             + `key in the node type, so without it the workflow cannot be resolved and the run fails before dispatch.`, `name: 'NameToAgeFixed'`);
     }
-    if (blank(inputs?.folderPath)) {
+    const inSolution = inputs?.location === 'in-solution';
+    if (!inSolution && blank(inputs?.folderPath)) {
         at('APIWF_NO_FOLDER', `API workflow step "${step}" has no \`folderPath\`. The runtime starts the job by name + folder, so the `
-            + `Orchestrator folder holding the workflow is required.`, `folderPath: 'Shared'`);
+            + `Orchestrator folder holding the workflow is required. For an API workflow in the SAME solution, set `
+            + `\`location: 'in-solution'\` and its \`projectId\` instead.`, `folderPath: 'Shared'`);
+    }
+    if (inSolution && blank(inputs?.projectId)) {
+        at('APIWF_LOCAL_NO_PROJECT_ID', `In-solution API workflow step "${step}" has no \`projectId\`. Read \`resource.projectKey\` from `
+            + `\`resources/solution_folder/process/api/<project>.json\`.`, `projectId: '<resource.projectKey>'`);
+    }
+    else if (inSolution && !GUID_RE.test(String(inputs.projectId).trim())) {
+        at('APIWF_LOCAL_PROJECT_ID_NOT_GUID', `In-solution API workflow step "${step}" has projectId ${JSON.stringify(inputs.projectId)}, which is not `
+            + `the sibling project's GUID. Read \`resource.projectKey\` from the generated resource file.`, `projectId: '<resource.projectKey>'`);
     }
+    // A folderPath beside in-solution is the serializer's APIWF_LOCAL_HAS_FOLDER (refusals.ts).
     const name = typeof inputs?.name === 'string' ? inputs.name.trim() : '';
     if (name.includes('/')) {
         at('APIWF_NAME_IS_PATH', `API workflow step "${step}"'s \`name\` is ${JSON.stringify(inputs.name)}, which is a folder path. `

package/dist/nodes/process/flow/node-type.js

@@ -176,7 +176,8 @@ const API_WORKFLOW_PREFIX = 'uipath.core.api-workflow.';
  * one the platform's own definition writes.
  */
 function apiWorkflowDef(spec) {
-    const resourceKey = `${spec.folderPath}.${spec.name}`;
+    const loc = processResourceLocation(spec);
+    const { resourceKey } = loc;
     const properties = {};
     for (const [k, v] of Object.entries(spec.inputs)) {
         properties[k] = { type: typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string' };
@@ -186,8 +187,8 @@ function apiWorkflowDef(spec) {
         version: '1.0.0',
         category: 'api-workflow',
         runtimeConstraints: { exclude: ['api-function'] },
-        description: `(${spec.folderPath})`,
-        tags: [],
+        description: loc.description,
+        tags: loc.tags,
         sortOrder: resourceNodeSortOrder('api-workflow'),
         supportsErrorHandling: true,
         display: { label: spec.name, icon: 'api' },
@@ -195,11 +196,12 @@ function apiWorkflowDef(spec) {
             { position: 'left', handles: [{ id: 'input', type: 'target', handleType: 'input' }] },
             { position: 'right', handles: [{ id: 'output', type: 'source', handleType: 'output' }] },
         ],
+        ...loc.definitionExtras,
         model: {
             type: 'bpmn:ServiceTask',
             serviceType: 'Orchestrator.ExecuteApiWorkflowAsync',
             version: 'v2',
-            section: 'Published',
+            ...(loc.inSolution ? {} : { section: 'Published' }),
             bindings: {
                 resource: 'process',
                 resourceSubType: 'Api',
@@ -207,9 +209,10 @@ function apiWorkflowDef(spec) {
                 orchestratorType: 'api',
                 values: [
                     { name: 'name', propertyAttribute: 'name', default: spec.name },
-                    { name: 'folderPath', propertyAttribute: 'folderPath', default: spec.folderPath },
+                    { name: 'folderPath', propertyAttribute: 'folderPath', default: loc.folderPath },
                 ],
             },
+            ...loc.modelExtras,
             context: [
                 { name: 'name', type: 'string', value: '<bindings.name>' },
                 { name: 'folderPath', type: 'string', value: '<bindings.folderPath>' },
@@ -611,7 +614,10 @@ export function processDefinition(spec) {
                 inputs: s.inputs ?? {}, returns: s.returns,
             });
         case 'apiWorkflow':
-            return apiWorkflowDef({ key: s.key, name: s.name, folderPath: s.folderPath, inputs: s.inputs ?? {}, returns: s.returns });
+            return apiWorkflowDef({
+                key: s.key, name: s.name, folderPath: s.folderPath, location: s.location, projectId: s.projectId,
+                inputs: s.inputs ?? {}, returns: s.returns,
+            });
         case 'agenticProcess':
             return agenticProcessDef({
                 key: s.key, name: s.name, folderPath: s.folderPath, location: s.location, projectId: s.projectId,
@@ -723,11 +729,14 @@ function liftProcess(node, ctx, prefix, kind, form) {
     const name = binding('name');
     const folderPath = binding('folderPath');
     // A sibling project of the same solution (#951): the model names its project
-    // instead of a folder. `isInSolution` is flow-core's marker. Read back as
-    // `location: 'in-solution'` so the recompile takes the in-solution path
-    // instead of a published one with an empty folder.
+    // instead of a folder. `isInSolution` is flow-core's marker; files that carry
+    // `projectName` but neither it nor `projectId` still carry the `in-solution`
+    // tag and an empty folder. Read back as `location: 'in-solution'` so the
+    // recompile takes the in-solution path instead of a published one with an
+    // empty folder (#1396). A tag beside a real folder is not enough.
     const projectId = typeof def?.model?.projectId === 'string' ? def.model.projectId : undefined;
-    const inSolution = def?.model?.isInSolution === true || projectId !== undefined;
+    const inSolution = def?.model?.isInSolution === true || projectId !== undefined
+        || (Array.isArray(def?.tags) && def.tags.includes('in-solution') && !folderPath);
     const inputs = { ...(n.inputs ?? {}) };
     // The design-time fire-and-forget switch is an OPTION on agenticProcess(),
     // not a process argument — serialize adds it to `inputs` after rendering the

package/dist/nodes/process/flow/refusals.js

@@ -25,7 +25,7 @@ const KINDS = {
         noKeySuggestion: `key: '486edc26-0658-4ac1-92c9-1ef953927151'`,
     },
     apiWorkflow: {
-        noKeyCode: 'APIWF_NO_KEY', label: 'API workflow', oldField: 'workflow',
+        noKeyCode: 'APIWF_NO_KEY', localCode: 'APIWF_LOCAL_HAS_FOLDER', label: 'API workflow', oldField: 'workflow', localLabel: 'API workflow step',
         noKey: (step) => `API workflow step "${step}" has no \`key\`. That is the published workflow's key (a GUID), and `
             + `it becomes part of the node's type — without it there is no workflow to invoke. Find it with `
             + `\`uip or processes list --all-folders\` (an API workflow's ProcessKey reads "<name>.api.<name>").`,

package/dist/nodes/process/flow/spec.d.ts

@@ -74,12 +74,38 @@ export interface ApiWorkflowInputs {
      * `uip or processes list --all-folders --process-type Api` (an API workflow's
      * `ProcessKey` reads `<name>.api.<name>`; the GUID you want is the row's `Key`)
      * or `uip maestro flow registry search`.
+     *
+     * For an in-solution sibling it is `resource.key` from
+     * `resources/solution_folder/process/api/<project>.json`, the suffix of the
+     * node type `uip maestro flow registry list --local` shows.
      */
     key: string;
     /** The workflow's name in Orchestrator — e.g. `'NameToAgeFixed'`. */
     name: string;
-    /** The Orchestrator folder holding it — e.g. `'Shared'`. */
-    folderPath: string;
+    /**
+     * Where the workflow lives. `'published'` (the default) is a workflow
+     * deployed to `folderPath`. `'in-solution'` is a sibling API workflow project
+     * of the same solution: it needs `projectId` and no `folderPath`, and `key` is
+     * that sibling's `resource.key`.
+     */
+    location?: ProcessLocation;
+    /**
+     * The Orchestrator folder holding it — e.g. `'Shared'`. Required for a
+     * published workflow; omit it for an in-solution sibling.
+     *
+     * @enforcedBy APIWF_NO_FOLDER A published API workflow needs its folder.
+     * @enforcedBy APIWF_LOCAL_HAS_FOLDER An in-solution API workflow has no folder.
+     */
+    folderPath?: string;
+    /**
+     * The sibling API workflow project's `resource.projectKey`, read from
+     * `resources/solution_folder/process/api/<project>.json`. Required only when
+     * `location` is `'in-solution'`.
+     *
+     * @enforcedBy APIWF_LOCAL_NO_PROJECT_ID An in-solution API workflow needs its project id.
+     * @enforcedBy APIWF_LOCAL_PROJECT_ID_NOT_GUID The project id is the sibling's GUID, not its name.
+     */
+    projectId?: string;
     /**
      * The WORKFLOW's own input arguments, by its own argument names (e.g.
      * `{ name: 'tomasz' }`). Not a fixed schema — every workflow declares its own.

package/dist/nodes/script/flow/factories.d.ts

@@ -9,9 +9,11 @@ import type { ScriptInputs, ScriptValue } from './spec.js';
  * Declare an inline script action, as a TypeScript function the compiler checks.
  *
  * The function is never called. Its body, exactly as written, becomes the
- * script; its parameter is an authoring-time name for the Flow runtime's own
- * `$vars` global and is renamed to it. `returns` is the declaration that reaches
- * the `.flow`, and tsc checks the function's return against it.
+ * script; its parameters are authoring-time names for the Flow runtime's own
+ * `$vars` and `$metadata` globals (typed `FlowVars` and `FlowMetadata`), in
+ * that order, and are renamed to them. Take neither, `$vars` alone, or both.
+ * `returns` is the declaration that reaches the `.flow`, and tsc checks the
+ * function's return against it.
  *
  * The function may read only what the script runtime has (the ES2020 built-ins
  * and `console`): a module constant, an import or a library throws here, because
@@ -20,29 +22,29 @@ import type { ScriptInputs, ScriptValue } from './spec.js';
  * ```ts
  * .step('post', script(parseMessage, { returns: { channel: 'string', threadTs: 'string' } }))
  *
- * function parseMessage(vars: FlowVars) {
- *   const m = /archives\/([A-Z0-9]+)\/p(\d{10})(\d{6})/.exec(String(vars.start.output.message));
+ * function parseMessage($vars: FlowVars) {
+ *   const m = /archives\/([A-Z0-9]+)\/p(\d{10})(\d{6})/.exec(String($vars.start.output.message));
  *   if (!m) throw new Error('not a Slack permalink');
  *   return { channel: m[1], threadTs: m[2] + '.' + m[3] };
  * }
  * ```
  *
- * @param fn - The script, as a function of the variable scope (or of nothing).
+ * @param fn - The script, as a function of the variable scope and the instance metadata (or of fewer).
  * @param options - What the function returns (`returns`), as `script({ returns })` takes it.
  * @returns An action spec to pass to `.step(name, …)`.
  */
-export declare function script<V, const R extends ScriptReturns>(fn: (vars: V) => ScriptValue<R>, options: {
+export declare function script<V, const R extends ScriptReturns, M = unknown>(fn: (vars: V, metadata: M) => ScriptValue<R>, options: {
     returns: R;
 }): ActionSpec;
 /**
  * Declare an inline script action, as a TypeScript function, with no declared
  * return: the body's type is inferred as it is for a string body.
  *
- * @param fn - The script, as a function of the variable scope (or of nothing).
+ * @param fn - The script, as a function of the variable scope and the instance metadata (or of fewer).
  * @param options - No `returns`; pass one to have tsc check the function against it.
  * @returns An action spec to pass to `.step(name, …)`.
  */
-export declare function script<V>(fn: (vars: V) => unknown, options?: {
+export declare function script<V, M = unknown>(fn: (vars: V, metadata: M) => unknown, options?: {
     returns?: never;
 }): ActionSpec;
 /**

package/dist/nodes/script/flow/node-type.js

@@ -6,6 +6,7 @@
  */
 import { declaredScriptShape, inferScriptShape } from '../../../core/script-return.js';
 import { jsonClone } from '../../../core/json-clone.js';
+import { unknownMetadataKeys } from '../../../core/flow-metadata.js';
 import { scriptBodyEarlyError, scriptBodySyntaxError, scriptBodyTypeScriptSyntax, tryLowerScriptFunction } from '../../../core/script-function.js';
 import { FLOW_SCRIPT_RUNTIME } from './runtime.js';
 import { checkScript } from './check.js';
@@ -106,12 +107,15 @@ const UNCHANGED = 'its text would not come back unchanged as a function body (a
  *      this holds for nearly every body that passes the others; it is checked
  *      because it is cheap, and a line comment on the last line is the case that
  *      fails it (it would swallow the closing brace);
- *   5. the engine compiles it as a strict function of `$vars`: an early error
- *      (a duplicate `let`, a `const $vars`, an octal literal) that TypeScript's
- *      parser does not report would make the whole module unloadable.
+ *   5. the engine compiles it as a strict function of its parameters: an early
+ *      error (a duplicate `let`, a `const $vars`, an octal literal) that
+ *      TypeScript's parser does not report would make the whole module
+ *      unloadable.
  *
- * The parameter is named `$vars`, so nothing is renamed and the body's text is
- * the node's text.
+ * The parameters are named `$vars` and, when the body reads it, `$metadata`, so
+ * nothing is renamed and the body's text is the node's text. A body that binds
+ * its own `$metadata` in the function's scope reads that, and prints without
+ * the parameter, which would clash with it.
  */
 function printAsFunction(code, ctx) {
     if (ctx.scripts !== 'function')
@@ -130,7 +134,7 @@ function printAsFunction(code, ctx) {
     // With authoring's own rules: the printed function is lowered by `script(fn)`
     // when the source is compiled back, so a body that rule refuses (`$vars?.x`,
     // `$vars['x']`, an alias) must stay a string here, or compile would refuse it.
-    const lowered = tryLowerScriptFunction(`function ${name}($vars) {${code}}`, FLOW_SCRIPT_RUNTIME, { scopeReadsOnly: true });
+    const lowered = tryLowerScriptFunction(`function ${name}($vars, $metadata) {${code}}`, FLOW_SCRIPT_RUNTIME, { scopeReadsOnly: true });
     if (!lowered.ok) {
         // Worded as the SDK's list, not as a fault: whether a string body that reads
         // the name really fails in the run is what #1411 has yet to establish.
@@ -144,11 +148,21 @@ function printAsFunction(code, ctx) {
     }
     if (lowered.code !== code)
         return keep(UNCHANGED);
+    // A body that binds its own `$metadata` in the function's scope (`const`, or a
+    // `var`, which is no early error but would not type-check beside a
+    // `FlowMetadata` parameter) reads that local, so it prints without one.
+    const metadata = lowered.scopesRead.includes('$metadata') && !lowered.scopesDeclared.includes('$metadata');
     // Last, on what will actually be printed: an early error makes the module unloadable.
-    const early = scriptBodyEarlyError(code, FLOW_SCRIPT_RUNTIME);
+    const early = scriptBodyEarlyError(code, metadata ? ['$vars', '$metadata'] : ['$vars']);
     if (early)
         return keep(`as a function in an ES module (strict code) it would not load: ${early}.`);
-    ctx.declareFunction(`function ${name}($vars: ${ctx.typeHelper('FlowVars')}) {${code}}`);
+    // A key the engine does not set (a case may set it) is not on `FlowMetadata`,
+    // so the type is widened for it, or the printed module would not type-check.
+    const metadataType = () => (unknownMetadataKeys(code).length > 0
+        ? `${ctx.typeHelper('FlowMetadata')} & Record<string, any>`
+        : ctx.typeHelper('FlowMetadata'));
+    const params = [`$vars: ${ctx.typeHelper('FlowVars')}`, ...(metadata ? [`$metadata: ${metadataType()}`] : [])];
+    ctx.declareFunction(`function ${name}(${params.join(', ')}) {${code}}`);
     return name;
 }
 /** Key-sorted copy, so a property map compares by content and not by order. */

package/dist/nodes/script/flow/runtime.d.ts

@@ -5,7 +5,14 @@
 import type { ScriptRuntime } from '../../../core/script-function.js';
 /**
  * What a Flow script body can read: the language's ES2020 built-ins, the
- * globals the engine registers, `console`, and the runtime's `$vars`.
+ * globals the engine registers, `console`, and the runtime's `$vars` and
+ * `$metadata`.
+ *
+ * The two scopes are the script task's two base inputs: Flow's converter gives
+ * every script task `vars = "=vars"` and `metadata = "=metadata"`, and rewrites
+ * `$vars`/`$metadata` in the body to those names (UiPath/flow-workbench,
+ * `bpmn-to-xml.ts` and `expression-transform.ts`); the engine binds each input
+ * as a global. A script function takes them as its parameters, in that order.
  *
  * Measured against UiPath/PO.BpmnEngine, which runs a script body with
  * Jint 4.4.0 (`ScriptTaskService.InvokeScriptAsync`,

package/dist/nodes/script/flow/runtime.js

@@ -20,7 +20,14 @@ const FLOW_SCRIPT_GLOBAL_MEMBERS = new Map([
 ]);
 /**
  * What a Flow script body can read: the language's ES2020 built-ins, the
- * globals the engine registers, `console`, and the runtime's `$vars`.
+ * globals the engine registers, `console`, and the runtime's `$vars` and
+ * `$metadata`.
+ *
+ * The two scopes are the script task's two base inputs: Flow's converter gives
+ * every script task `vars = "=vars"` and `metadata = "=metadata"`, and rewrites
+ * `$vars`/`$metadata` in the body to those names (UiPath/flow-workbench,
+ * `bpmn-to-xml.ts` and `expression-transform.ts`); the engine binds each input
+ * as a global. A script function takes them as its parameters, in that order.
  *
  * Measured against UiPath/PO.BpmnEngine, which runs a script body with
  * Jint 4.4.0 (`ScriptTaskService.InvokeScriptAsync`,
@@ -45,7 +52,16 @@ const FLOW_SCRIPT_GLOBAL_MEMBERS = new Map([
  * there is evidence the list is complete (#1411).
  */
 export const FLOW_SCRIPT_RUNTIME = {
-    scopeGlobal: '$vars',
+    scopes: [
+        {
+            global: '$vars', param: 'vars', holds: 'the variable scope', reads: 'step', example: 'start.output.x',
+            checkedBy: 'the step renaming and reference checks',
+        },
+        {
+            global: '$metadata', param: 'metadata', holds: 'the instance metadata', reads: 'key', example: 'InstanceId',
+            checkedBy: 'the metadata key check',
+        },
+    ],
     name: 'the Flow script runtime',
     constGlobals: FLOW_SCRIPT_CONST_GLOBALS,
     globalMembers: FLOW_SCRIPT_GLOBAL_MEMBERS,

package/dist/nodes/script/flow/spec.d.ts

@@ -60,6 +60,39 @@ export interface ScriptInputs {
  * ```
  */
 export type FlowVars = Record<string, any>;
+/**
+ * The instance metadata, as a script function's second parameter sees it.
+ *
+ * Like `$vars`, `$metadata` is the Flow runtime's own global: `script(fn)`
+ * renames the second parameter to it. Unlike `$vars` its shape does not depend
+ * on the flow: these are the keys the engine sets on every instance
+ * (UiPath/PO.BpmnEngine, `BpmnGeneric.workflow.cs` `MapToMetadataScopeData`, and
+ * `BpmnDataManager.UpsertElementCountDatum`). `check` warns on a read of any
+ * other key (`UNKNOWN_METADATA_KEY`).
+ *
+ * A case that starts the flow may set more. To read one of those, widen the
+ * parameter's type (`$metadata: FlowMetadata & { Region?: string }`).
+ *
+ * ```ts
+ * .step('tag', script(tag, { returns: 'string' }))
+ *
+ * function tag($vars: FlowVars, $metadata: FlowMetadata) {
+ *   return $metadata.InstanceId + ':' + $vars.start.output.id;
+ * }
+ * ```
+ */
+export interface FlowMetadata {
+    /** The key (UUID) of the Orchestrator folder the instance runs in. */
+    FolderKey: string;
+    /** The instance's id (UUID). */
+    InstanceId: string;
+    /** The key of the process the instance runs. */
+    ProcessKey: string;
+    /** The external id a case gives the instance; unset for a flow no case started. */
+    ExternalId?: string;
+    /** How many times each element has run, by element id; unset until the first count. */
+    ElementCount?: Record<string, number>;
+}
 /** The TypeScript type one of {@link ScriptReturnType}'s names stands for. */
 export type ScriptValueOf<T extends ScriptReturnType> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? readonly unknown[] : T extends 'object' ? object : unknown;
 /**