@uipath/maestro-builder-sdk 6.71.1 → 6.72.0

package/dist/api-index.md

@@ -37,7 +37,7 @@ could hand you spans for a version you do not have.
 
 ## `@uipath/maestro-builder-sdk`
 
-245 symbol(s). Import from `@uipath/maestro-builder-sdk`.
+247 symbol(s). Import from `@uipath/maestro-builder-sdk`.
 
 | Symbol | Kind | Declaration | Area | Summary |
 | --- | --- | --- | --- | --- |
@@ -143,10 +143,12 @@ could hand you spans for a version you do not have.
 | `FlowActionSpecs` | interface | `dist/core/actions.d.ts:813-846` | Supporting types | Every action kind, keyed by kind, to the body of its spec — the arm's fields other than `kind`. |
 | `FlowBuilder` | class | `dist/flow-sdk.d.ts:1411-1791` | Builders | 15 member(s) |
 | `FlowLayout` | interface | `dist/flow-sdk.d.ts:830-843` | Supporting types | Designer layout for a flow, keyed by AUTHOR-level ids: node entries by step name (plus the trigger id and `end`), edge… |
+| `FlowMetadata` | interface | `dist/nodes/script/flow/spec.d.ts:63-95` | Actions | The instance metadata, as a script function's second parameter sees it. |
 | `FlowNode` | class | `dist/core/node-classes.d.ts:126-161` | Supporting types | The abstract root of every definition-backed node the builder can place. |
 | `FlowResource` | class | `dist/core/node-classes.d.ts:176-183` | Supporting types | A node attached to another semantic node — an inline agent's tool, context, memory, or escalation. |
 | `FlowTrigger` | class | `dist/core/node-classes.d.ts:169-175` | Supporting types | A node that starts the flow — pass an instance to `.trigger(…)`. |
 | `FlowTypeDesc` | type | `dist/flow-types.d.ts:45-51` | Supporting types | A `types.*` descriptor a Flow variable may declare: every member of `types` but the Case-only `float`, `double`, `date`,… |
+| `FlowVars` | type | `dist/nodes/script/flow/spec.d.ts:45-62` | Actions | The runtime's variable scope, as a script function's parameter sees it. |
 | `FormField` | type | `dist/core/actions.d.ts:259` | Supporting types |  |
 | `FormFieldCondition` | interface | `dist/core/actions.d.ts:113-133` | Supporting types | One condition of a form-field rule (`@uipath/hitl-schema-types` `fieldConditionSchema`): `when` names the field it… |
 | `FormFieldControlType` | type | `dist/core/actions.d.ts:105-112` | Supporting types | How a form field renders (`@uipath/hitl-schema-types` `controlType`). |
@@ -236,14 +238,14 @@ could hand you spans for a version you do not have.
 | `ScheduledInputs` | interface | `dist/flow-sdk.d.ts:153-165` | Option shapes | 1 field(s) |
 | `ScheduleEvery` | type | `dist/flow-sdk.d.ts:141-152` | Supporting types | How often a scheduled flow runs, as an ISO-8601 repeating interval: `R/` followed by a duration. |
 | `SchedulePreset` | type | `dist/flow-sdk.d.ts:140` | Supporting types |  |
-| `script` | function | `dist/nodes/script/flow/factories.d.ts:8-36` | Actions | Declare an inline script action, as a TypeScript function the compiler checks. |
-| `script` | function | `dist/nodes/script/flow/factories.d.ts:37-47` | Actions | Declare an inline script action, as a TypeScript function, with no declared return: the body's type is inferred as it is… |
-| `script` | function | `dist/nodes/script/flow/factories.d.ts:48-55` | Actions | Declare an inline script action. |
-| `ScriptInputs` | interface | `dist/nodes/script/flow/spec.d.ts:7-44` | Option shapes | 2 field(s) |
+| `script` | function | `dist/nodes/script/flow/factories.d.ts:8-38` | Actions | Declare an inline script action, as a TypeScript function the compiler checks. |
+| `script` | function | `dist/nodes/script/flow/factories.d.ts:39-49` | Actions | Declare an inline script action, as a TypeScript function, with no declared return: the body's type is inferred as it is… |
+| `script` | function | `dist/nodes/script/flow/factories.d.ts:50-57` | Actions | Declare an inline script action. |
+| `ScriptInputs` | interface | `dist/nodes/script/flow/spec.d.ts:7-44` | Actions | 2 field(s) |
 | `ScriptReturns` | type | `dist/core/script-return.d.ts:42-48` | Supporting types | What an author may write for `script({ returns })`: the type outright, or — for an object return — the FIELDS, which is… |
 | `ScriptReturnType` | type | `dist/core/script-return.d.ts:31-41` | Supporting types | The vocabulary a script's output can be declared as. |
-| `ScriptValue` | type | `dist/nodes/script/flow/spec.d.ts:65-75` | Supporting types | What a script function must return for a given `returns`: the type a name stands for, or, for a field map, an object… |
-| `ScriptValueOf` | type | `dist/nodes/script/flow/spec.d.ts:63-64` | Supporting types | The TypeScript type one of ScriptReturnType's names stands for. |
+| `ScriptValue` | type | `dist/nodes/script/flow/spec.d.ts:98-108` | Actions | What a script function must return for a given `returns`: the type a name stands for, or, for a field map, an object… |
+| `ScriptValueOf` | type | `dist/nodes/script/flow/spec.d.ts:96-97` | Actions | The TypeScript type one of ScriptReturnType's names stands for. |
 | `sendMessage` | function | `dist/nodes/conversation/flow/factories.d.ts:8-26` | Actions | Post an assistant message into a live conversation (`uipath.conversational.send-message`). |
 | `SendMessageInputs` | interface | `dist/nodes/conversation/flow/spec.d.ts:8-27` | Option shapes | 4 field(s) |
 | `ShownField` | interface | `dist/core/actions.d.ts:205-220` | Supporting types | A value the reviewer READS: shown on the form, filled in from the flow. |

package/dist/api-members.md

@@ -5,13 +5,13 @@
 
 # Maestro Builder SDK — member index
 
-**A lookup table of 1238 rows — match one name in it, do not read it.**
+**A lookup table of 1243 rows — match one name in it, do not read it.**
 Grep or search for the member you have; the row it lands on is the whole
 answer. Reading top to bottom costs ~20x what the one row does and tells you
 nothing you asked for.
 
-Every field and method of every exported shape — 1238 across
-228 interfaces and classes — keyed by the MEMBER's own name.
+Every field and method of every exported shape — 1243 across
+229 interfaces and classes — keyed by the MEMBER's own name.
 
 **Use this when the name you have is a field or a method**, which is usually
 the case: the reference pages are "one line per field", so you arrive holding
@@ -28,7 +28,7 @@ truncated summary would, for less. Read the span.
 Member names repeat across shapes (`name` is declared on 69 of them), so the
 `Declared on` column is what makes a match actionable. For the whole shape
 rather than the one field, look that name up in [`api-index.md`](api-index.md) —
-which is why its span is not repeated on all 1238 rows here.
+which is why its span is not repeated on all 1243 rows here.
 
 **A name that misses both indexes is probably not part of the API.** The one
 that comes up is a RUNTIME output key — a human task's `Action`, a step's
@@ -299,6 +299,7 @@ not find it either.
 | `effects` | property | `FormFieldRule` | `dist/core/actions.d.ts:159-160` |
 | `element` | property | `PlainTaskOpts` | `dist/bpmn/bpmn-sdk.d.ts:1712-1713` |
 | `element` | property | `RegistryTypeSpec` | `dist/bpmn/typed-node.d.ts:87-88` |
+| `ElementCount` | property | `FlowMetadata` | `dist/nodes/script/flow/spec.d.ts:93-94` |
 | `elementId` | property | `BpmnVarDecl` | `dist/bpmn/bpmn-sdk.d.ts:396-403` |
 | `elementId` | property | `VarOpts` | `dist/bpmn/bpmn-sdk.d.ts:1741-1764` |
 | `enabledForEvals` | property | `BuiltInValidatorGuardrail` | `dist/core/actions.d.ts:360` |
@@ -372,6 +373,7 @@ not find it either.
 | `external` | property | `BuiltTask` | `dist/case/case-sdk.d.ts:720-721` |
 | `externalAgent` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2942-2978` |
 | `externalAgent` | method | `TaskBuilder` | `dist/case/case-sdk.d.ts:1095-1102` |
+| `ExternalId` | property | `FlowMetadata` | `dist/nodes/script/flow/spec.d.ts:91-92` |
 | `externalWorkflow` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2979-2995` |
 | `externalWorkflow` | method | `TaskBuilder` | `dist/case/case-sdk.d.ts:1103-1110` |
 | `extractionResult` | property | `DocValidationInputs` | `dist/nodes/hitl/flow/spec.d.ts:82-87` |
@@ -424,6 +426,7 @@ not find it either.
 | `folderKey` | property | `McpToolRef` | `dist/core/actions.d.ts:457-458` |
 | `folderKey` | property | `OrchestratorOpts` | `dist/bpmn/bpmn-sdk.d.ts:1300-1308` |
 | `folderKey` | property | `RemoteA2aToolRef` | `dist/core/actions.d.ts:489` |
+| `FolderKey` | property | `FlowMetadata` | `dist/nodes/script/flow/spec.d.ts:85-86` |
 | `folderName` | property | `IxpExtractInputs` | `dist/nodes/document/flow/spec.d.ts:108-114` |
 | `folderPath` | property | `AgenticProcessInputsBase` | `dist/nodes/process/flow/spec.d.ts:214-221` |
 | `folderPath` | property | `AgentInputs` | `dist/nodes/process/flow/spec.d.ts:317-328` |
@@ -542,6 +545,7 @@ not find it either.
 | `inputSchema` | property | `AppRef` | `dist/nodes/hitl/flow/spec.d.ts:245-253` |
 | `inputSchema` | property | `ScriptTaskOpts` | `dist/bpmn/bpmn-sdk.d.ts:953-964` |
 | `inputTarget` | property | `RegistryTypeSpec` | `dist/bpmn/typed-node.d.ts:93` |
+| `InstanceId` | property | `FlowMetadata` | `dist/nodes/script/flow/spec.d.ts:87-88` |
 | `intermediateCatchEvent` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2326-2333` |
 | `intermediateThrowEvent` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2334-2341` |
 | `internal` | property | `BpmnVarDecl` | `dist/bpmn/bpmn-sdk.d.ts:410-411` |
@@ -883,6 +887,7 @@ not find it either.
 | `process` | property | `OrchestratorOpts` | `dist/bpmn/bpmn-sdk.d.ts:1267-1285` |
 | `process` | method | `TaskBuilder` | `dist/case/case-sdk.d.ts:959-968` |
 | `processId` | property | `SugarRegistry` | `dist/bpmn/bpmn-sdk.d.ts:2060-2065` |
+| `ProcessKey` | property | `FlowMetadata` | `dist/nodes/script/flow/spec.d.ts:89-90` |
 | `project` | property | `IxpExtractInputs` | `dist/nodes/document/flow/spec.d.ts:76-89` |
 | `projectId` | property | `AgenticProcessInputsBase` | `dist/nodes/process/flow/spec.d.ts:222-229` |
 | `projectId` | property | `AgentInputs` | `dist/nodes/process/flow/spec.d.ts:329-334` |
@@ -1010,7 +1015,7 @@ not find it either.
 | `schemaVersion` | method | `FlowBuilder` | `dist/flow-sdk.d.ts:1604-1643` |
 | `scope` | property | `EscalationRecipient` | `dist/case/case-sdk.d.ts:160` |
 | `scopes` | property | `GuardrailSelector` | `dist/core/actions.d.ts:290` |
-| `script` | property | `FlowActionSpecs` | `dist/nodes/script/flow/spec.d.ts:78-81` |
+| `script` | property | `FlowActionSpecs` | `dist/nodes/script/flow/spec.d.ts:111-114` |
 | `script` | property | `ScriptTaskOpts` | `dist/bpmn/bpmn-sdk.d.ts:880-896` |
 | `scriptFormat` | property | `ScriptTaskOpts` | `dist/bpmn/bpmn-sdk.d.ts:897-898` |
 | `scriptTask` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2387-2395` |

package/dist/check.js

@@ -24,6 +24,7 @@ import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
 import { planSharedInputs, sharedInputRoots } from './flow-variables.js';
 import { VARS_READ_RE } from './core/vars-read.js';
+import { FLOW_METADATA_KEYS, unknownMetadataKeys } from './core/flow-metadata.js';
 import { endContentKey } from './flow-end-content.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
@@ -942,6 +943,24 @@ function checkFlow(built, ancestors, opts = {}) {
             }
         }
     }
+    // A `$metadata` key the engine does not set. Its shape is fixed, unlike
+    // `$vars` (core/flow-metadata.ts), so a typo (`$metadata.instanceId`) reads
+    // `undefined`. A warning, not an error: a case can set other keys on an
+    // instance it starts, and the flow cannot tell whether one does. Read from
+    // the parsed code, so a local `$metadata` or a comment is not a read.
+    for (const { js, step } of exprs) {
+        for (const key of unknownMetadataKeys(js)) {
+            const near = FLOW_METADATA_KEYS.find((k) => k.toLowerCase() === key.toLowerCase());
+            diags.push({
+                level: 'warning',
+                code: 'UNKNOWN_METADATA_KEY',
+                step,
+                message: `"${step}" reads $metadata.${key}, which the engine does not set: it sets ${FLOW_METADATA_KEYS.join(', ')}. `
+                    + 'Unless a case that starts this flow sets it, it reads undefined.',
+                ...(near ? { suggestion: `$metadata.${near}` } : {}),
+            });
+        }
+    }
     // A reference that reaches a step through a BRACKET instead of a dot.
     //
     // Both forms resolve at run time — measured, `$vars.call["output"].x` and

package/dist/core/flow-metadata.d.ts

@@ -0,0 +1,18 @@
+/** The keys the engine sets on every instance's `$metadata`. */
+export declare const FLOW_METADATA_KEYS: readonly string[];
+/**
+ * Every `$metadata` key `code` reads by name, in source order: a property
+ * access (`$metadata.InstanceId`, `?.`, with any whitespace or comment around
+ * the dot) or a string-literal element access (`$metadata['InstanceId']`).
+ *
+ * Read from the parsed code, with names resolved by a one-file checker, so only
+ * the runtime's own global counts: a local or parameter named `$metadata`, a
+ * member of that name (`o.$metadata.Region`), and text in a comment or string
+ * are not reads. A computed key reads nothing knowable and is skipped.
+ *
+ * `code` is a script body (top-level `return` allowed) or an expression; one
+ * that parses as neither is read as far as the parser recovers.
+ */
+export declare function metadataReads(code: string): string[];
+/** The keys `code` reads that the engine does not set, each once, in order of first read. */
+export declare function unknownMetadataKeys(code: string): string[];

package/dist/core/flow-metadata.js

@@ -0,0 +1,63 @@
+import { typescript } from './typescript-module.js';
+import { isReference, isUndefinedSymbol, oneFileChecker } from './script-function.js';
+/** The keys the engine sets on every instance's `$metadata`. */
+export const FLOW_METADATA_KEYS = ['FolderKey', 'InstanceId', 'ProcessKey', 'ExternalId', 'ElementCount'];
+const METADATA = '$metadata';
+/**
+ * Every `$metadata` key `code` reads by name, in source order: a property
+ * access (`$metadata.InstanceId`, `?.`, with any whitespace or comment around
+ * the dot) or a string-literal element access (`$metadata['InstanceId']`).
+ *
+ * Read from the parsed code, with names resolved by a one-file checker, so only
+ * the runtime's own global counts: a local or parameter named `$metadata`, a
+ * member of that name (`o.$metadata.Region`), and text in a comment or string
+ * are not reads. A computed key reads nothing knowable and is skipped.
+ *
+ * `code` is a script body (top-level `return` allowed) or an expression; one
+ * that parses as neither is read as far as the parser recovers.
+ */
+export function metadataReads(code) {
+    if (!code.includes(METADATA))
+        return [];
+    const ts = typescript();
+    const sf = parseBodyOrExpression(ts, code);
+    const checker = oneFileChecker(ts, sf);
+    const out = [];
+    const visit = (n) => {
+        if (ts.isIdentifier(n) && n.text === METADATA && isReference(ts, n)) {
+            const symbol = checker.getSymbolAtLocation(n);
+            const key = symbol && !isUndefinedSymbol(symbol) ? undefined : keyRead(ts, n);
+            if (key !== undefined)
+                out.push(key);
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(sf);
+    return out;
+}
+/** The keys `code` reads that the engine does not set, each once, in order of first read. */
+export function unknownMetadataKeys(code) {
+    return [...new Set(metadataReads(code).filter((k) => !FLOW_METADATA_KEYS.includes(k)))];
+}
+/** The key `id` (the global) is read with: `.key`, `?.key`, or `['key']`. */
+function keyRead(ts, id) {
+    const p = id.parent;
+    if (ts.isPropertyAccessExpression(p) && p.expression === id && ts.isIdentifier(p.name))
+        return p.name.text;
+    if (ts.isElementAccessExpression(p) && p.expression === id && ts.isStringLiteralLike(p.argumentExpression))
+        return p.argumentExpression.text;
+    return undefined;
+}
+/**
+ * `code` as a function body, or, when that does not parse and the expression
+ * does (a bare `{ a: $metadata.X }` is a block otherwise), as an expression.
+ */
+function parseBodyOrExpression(ts, code) {
+    const parse = (text) => ts.createSourceFile('metadata-reads.ts', text, ts.ScriptTarget.ES2020, true, ts.ScriptKind.TS);
+    const errors = (sf) => (sf.parseDiagnostics ?? []).length;
+    const body = parse(`function __body() {\n${code}\n}`);
+    if (errors(body) === 0)
+        return body;
+    const expression = parse(`(${code}\n)`);
+    return errors(expression) === 0 ? expression : body;
+}

package/dist/core/refusals.d.ts

@@ -683,6 +683,7 @@ export declare const REFUSALS: {
     readonly UNKNOWN_ESCALATION_REF: "lowering";
     readonly UNKNOWN_EXIT_STAGE: "lowering";
     readonly UNKNOWN_LOOP_FIELD: "lint";
+    readonly UNKNOWN_METADATA_KEY: "lint";
     readonly UNKNOWN_REF: "lint";
     readonly UNKNOWN_RULE: "lowering";
     readonly UNKNOWN_SLA_REF: "lowering";

package/dist/core/refusals.js

@@ -735,6 +735,7 @@ export const REFUSALS = {
     UNKNOWN_ESCALATION_REF: 'lowering',
     UNKNOWN_EXIT_STAGE: 'lowering',
     UNKNOWN_LOOP_FIELD: 'lint',
+    UNKNOWN_METADATA_KEY: 'lint',
     UNKNOWN_REF: 'lint',
     UNKNOWN_RULE: 'lowering',
     UNKNOWN_SLA_REF: 'lowering',

package/dist/core/script-function.d.ts

@@ -10,27 +10,46 @@
  * artifact goes to a designer, and the author expects to see the script they
  * wrote. Only two edits are made, both because the runtime requires them:
  *
- *   1. the parameter is renamed to the runtime's own scope global (`$vars` in
- *      Flow). The parameter is an authoring-time name for that global; the SDK
- *      never calls the function or passes it anything.
+ *   1. each parameter is renamed to the runtime's own global for its scope
+ *      (`$vars`, then `$metadata`, in Flow). A parameter is an authoring-time
+ *      name for that global; the SDK never calls the function or passes it
+ *      anything.
  *   2. esbuild's `keepNames` wrappers (`__name(fn, "fn")`) are removed. A loader
  *      such as tsx adds them, and the script runtime has no `__name`.
  *
  * Everything else that would make the lowered body behave differently from the
  * function is refused rather than rewritten: a name the runtime does not
- * provide, a `$vars` binding that would capture the rename, a destructured
- * parameter whose step reads `renameRefs` could not see, a reference to the
- * function's own name, which only the body loses.
+ * provide, a `$vars` (or `$metadata`) binding that would capture the rename, a
+ * destructured parameter whose step reads `renameRefs` could not see, a
+ * reference to the function's own name, which only the body loses.
  *
  * Names are resolved with the checker of a one-file program over the function's
  * source, not by text: `a.vars`, `{ vars: 1 }` and an inner `(vars) => …` are
  * not references to the parameter, and only a checker knows that.
  */
 import type * as TS from 'typescript';
-/** How a runtime receives a lowered script: its scope global, and every other name it provides. */
+/** One scope a runtime binds to a global, which a script function takes as a parameter. */
+export interface ScriptScope {
+    /** The identifier the runtime binds it to: `$vars`. */
+    global: string;
+    /** The plain parameter name errors suggest for it: `vars`. */
+    param: string;
+    /** What it holds, as errors name it: `the variable scope`. */
+    holds: string;
+    /** What a dotted read of it names, as errors name it: `step` (`$vars.<step>`). */
+    reads: string;
+    /** A dotted read's tail, as errors show it: `start.output.x`. */
+    example: string;
+    /** What sees only a dotted read, as errors name it: `the step renaming and reference checks`. */
+    checkedBy: string;
+}
+/** How a runtime receives a lowered script: its scope globals, and every other name it provides. */
 export interface ScriptRuntime {
-    /** The identifier the runtime binds the variable scope to (`$vars` in Flow). */
-    scopeGlobal: string;
+    /**
+     * The scopes the runtime binds, in parameter order (`$vars`, then `$metadata`,
+     * in Flow): a script function takes one parameter per scope, or fewer.
+     */
+    scopes: readonly ScriptScope[];
     /** Every other global name the runtime provides: the language built-ins it has, `console`. */
     globals: ReadonlySet<string>;
     /**
@@ -75,19 +94,30 @@ export declare function scriptFunctionLowerings(): readonly string[];
 /** Options for {@link tryLowerScriptFunction}. */
 export interface LowerOptions {
     /**
-     * Refuse any use of the parameter other than a dotted read (`vars.start…`):
+     * Refuse any use of a parameter other than a dotted read (`vars.start…`):
      * an alias (`const v = vars`), a computed read (`vars['start']`), an optional
      * read (`vars?.start`), or passing it on (`pick(vars)`, `{ vars }`) each hides
      * the step it reads from `renameRefs` and the reference check, which see only
-     * `$vars.<name>`. Authoring (`script(fn)`) sets it; decompile's gate does not,
-     * because there the text is the node's own either way.
+     * `$vars.<name>` (and, for `$metadata`, the key it reads from the key check).
+     * Authoring (`script(fn)`) sets it; decompile's gate does not, because there
+     * the text is the node's own either way.
      */
     scopeReadsOnly?: boolean;
 }
 /** What lowering a function's source produced: its body, or every problem with it. */
-export type LoweredScript = {
+export type LoweredScript = 
+/**
+ * `scopesRead` is the scope globals whose parameter the body reads, and
+ * `scopesDeclared` the ones the body binds in the function's own scope (a
+ * top-level `let`, `const`, `class` or `function`, or a `var` outside a nested
+ * function), each in scope order. A body that binds one reads its own local,
+ * and a parameter of that name printed beside it would clash.
+ */
+{
     ok: true;
     code: string;
+    scopesRead: string[];
+    scopesDeclared: string[];
 }
 /**
  * `free` is the names the runtime would not have, also described in `problems`;
@@ -111,18 +141,18 @@ export declare function tryLowerScriptFunction(source: string, runtime: ScriptRu
 export declare function scriptBodySyntaxError(code: string): string | undefined;
 /**
  * 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 declare function scriptBodyEarlyError(code: string, runtime: ScriptRuntime): string | undefined;
+export declare function scriptBodyEarlyError(code: string, params: readonly string[]): string | undefined;
 /**
  * The first piece of TypeScript-only syntax in a body, described, or undefined.
  *
@@ -134,5 +164,9 @@ export declare function scriptBodyEarlyError(code: string, runtime: ScriptRuntim
  * string form.
  */
 export declare function scriptBodyTypeScriptSyntax(code: string): string | undefined;
+/** The checker of a one-file program over `sf`, with no default library: globals resolve to nothing. */
+export declare function oneFileChecker(ts: typeof TS, sf: TS.SourceFile): TS.TypeChecker;
+/** The checker's own symbol for `undefined`, which a no-lib program still binds. */
+export declare function isUndefinedSymbol(s: TS.Symbol): boolean;
 /** Whether `id` is read as a value, not a property name, label, or type. */
 export declare function isReference(ts: typeof TS, id: TS.Identifier): boolean;

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/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;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.71.1",
+  "version": "6.72.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "7cd35a2caf9c3ca33c5f5f8c0caae6577d6dc77d"
+  "gitref": "3b667059d0108eba01cb0e82fbb049ae0ad04588"
 }