@uipath/maestro-builder-sdk 5.2.0

package/dist/flow-variables.d.ts

@@ -0,0 +1,13 @@
+export interface FlowGlobalDeclaration {
+    id: string;
+    name?: string;
+    direction: 'in' | 'out' | 'inout';
+    type: string;
+    defaultValue?: unknown;
+    triggerNodeId?: string;
+    description?: string;
+    subType?: string;
+    schema?: Record<string, unknown>;
+}
+/** Read both supported Flow variable spellings into one declaration table. */
+export declare function readFlowGlobals(variables: unknown, strict?: boolean): FlowGlobalDeclaration[];

package/dist/flow-variables.js

@@ -0,0 +1,42 @@
+const CONTAINER_KEYS = new Set(['globals', 'nodes', 'variableUpdates']);
+const DIRECTIONS = new Set(['in', 'out', 'inout']);
+/** Read both supported Flow variable spellings into one declaration table. */
+export function readFlowGlobals(variables, strict = false) {
+    if (variables === undefined || variables === null)
+        return [];
+    if (typeof variables !== 'object' || Array.isArray(variables)) {
+        if (strict)
+            throw new Error('decompile: variables must be an object.');
+        return [];
+    }
+    const source = variables;
+    const globals = Array.isArray(source.globals)
+        ? source.globals.filter((value) => value !== null && typeof value === 'object')
+        : [];
+    const seen = new Set(globals.map((global) => global.id));
+    const unknown = [];
+    if (source.globals !== undefined && !Array.isArray(source.globals))
+        unknown.push('globals');
+    for (const [id, value] of Object.entries(source)) {
+        if (CONTAINER_KEYS.has(id))
+            continue;
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            unknown.push(id);
+            continue;
+        }
+        const declaration = value;
+        if (typeof declaration.type !== 'string' || !DIRECTIONS.has(String(declaration.direction))) {
+            unknown.push(id);
+            continue;
+        }
+        if (!seen.has(id)) {
+            globals.push({ ...declaration, id });
+            seen.add(id);
+        }
+    }
+    if (strict && unknown.length > 0) {
+        throw new Error(`decompile: unrecognized variables key${unknown.length === 1 ? '' : 's'}: `
+            + `${unknown.map((key) => JSON.stringify(key)).join(', ')}.`);
+    }
+    return globals;
+}

package/dist/format-profile.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The Flow file-format profile — serializer-owned (design §5.4).
+ *
+ * Top-level `version` in a `.flow` file is the FILE-FORMAT version, not an
+ * author-controlled artifact version: every supported reader accepts the fleet
+ * write floor, and each migration hop validates its input against that
+ * version's schema. The profile pins what this SDK build writes BY DEFAULT;
+ * `.version()` never reached the file and is deprecated, and compiling the same
+ * source with the same SDK build is deterministic.
+ *
+ * `.schemaVersion(v)` declares a different target for one flow, out of the set
+ * this build can actually write ({@link FLOW_SCHEMA_VERSIONS}) — that is what
+ * lets a decompile PRESERVE the version it read instead of quietly rewriting a
+ * 1.10 file as 1.9. See `schema-version.ts`.
+ *
+ * The pinned value tracks `flow-workbench`'s `MINIMUM_SUPPORTED_SCHEMA_VERSION`
+ * (the fleet write floor), snapshotted in `flow-workbench-ootb.snapshot.json`
+ * — `scripts/audit-flow-coverage.mjs` reports drift between the two on every
+ * run, so a floor bump upstream becomes visible here without a sibling
+ * checkout.
+ */
+import type { SchemaVersionPolicy } from './schema-version.js';
+export declare const FLOW_FORMAT_PROFILE: {
+    /**
+     * The file-format version an emitted `.flow` declares when the author does
+     * not say otherwise. `1.9` is the current fleet write floor; it is
+     * structurally identical to `1.8` (the 1.8→1.9 migration only annotates
+     * stored Dynamic Extract definitions, which this SDK never emits), so
+     * emitting it skips a no-op migration hop on every open.
+     */
+    readonly version: "1.9";
+};
+/**
+ * Which Flow file-format versions `.schemaVersion()` may declare.
+ *
+ * **The band is 1.6 through 1.10, and it was read out of `flow-workbench`
+ * rather than assumed.** Every schema in it is the previous one plus a new
+ * version literal:
+ *
+ * ```ts
+ * export const workflowSchemaV1_10 = workflowSchemaV1_9.extend({ version: z.literal('1.10') });
+ * ```
+ *
+ * — and the same line, one version down, defines 1.9, 1.8, 1.7 and 1.6
+ * (`packages/flow-schema/src/versions/v1.*.ts`). So the bytes this SDK emits
+ * satisfy all five schemas, and declaring one of them is a claim the serializer
+ * can actually back. Each hop between them is a DATA migration, and each targets
+ * something this SDK either never emits or already emits in its post-hop form:
+ * 1.6→1.7 rewrites three HITL sub-type node types, 1.7→1.8 reshapes
+ * document-validation HITL inputs, 1.8→1.9 annotates stored Dynamic Extract
+ * definitions, 1.9→1.10 repairs connector binding names.
+ *
+ * **Why the floor is 1.6.** Below it the shape genuinely differs: expressions
+ * are legacy `=js:` strings rather than the `{ type, expression, fieldType }`
+ * envelope this SDK writes (the envelope arrives with the 1.2→1.3 hop), and the
+ * 1.3→1.4 hop REVERTS agent and inline-agent-resource node inputs to the legacy
+ * string form. A target below 1.6 would hand a reader a document its own hops
+ * would reshape, so it is refused rather than stamped. That is the same line
+ * `migrate.ts`'s `VERSION_CONDITIONAL` ladder draws at `from: '1.6'` — the
+ * ladder gate and this floor are the same fact stated twice, which is why the
+ * gate is inert today and becomes live the day a lower target is supported.
+ *
+ * **Why 1.9 stays the DEFAULT** rather than the newest version: the floor is a
+ * deployed-reader boundary, not a quality ranking. `flow-workbench`'s own
+ * `MINIMUM_SUPPORTED_SCHEMA_VERSION` comment says not to advance it "until every
+ * deployed reader — including the CLI, Studio Web, and VS Code — can read the
+ * target version". So declaring 1.10 buys currency at the cost of reader
+ * compatibility and declaring 1.8 buys compatibility at the cost of a migration
+ * hop on every open; `check()` names the trade in both directions rather than
+ * picking for the author.
+ */
+export declare const FLOW_SCHEMA_VERSIONS: SchemaVersionPolicy;

package/dist/format-profile.js

@@ -0,0 +1,97 @@
+export const FLOW_FORMAT_PROFILE = {
+    /**
+     * The file-format version an emitted `.flow` declares when the author does
+     * not say otherwise. `1.9` is the current fleet write floor; it is
+     * structurally identical to `1.8` (the 1.8→1.9 migration only annotates
+     * stored Dynamic Extract definitions, which this SDK never emits), so
+     * emitting it skips a no-op migration hop on every open.
+     */
+    version: '1.9',
+};
+/**
+ * Which Flow file-format versions `.schemaVersion()` may declare.
+ *
+ * **The band is 1.6 through 1.10, and it was read out of `flow-workbench`
+ * rather than assumed.** Every schema in it is the previous one plus a new
+ * version literal:
+ *
+ * ```ts
+ * export const workflowSchemaV1_10 = workflowSchemaV1_9.extend({ version: z.literal('1.10') });
+ * ```
+ *
+ * — and the same line, one version down, defines 1.9, 1.8, 1.7 and 1.6
+ * (`packages/flow-schema/src/versions/v1.*.ts`). So the bytes this SDK emits
+ * satisfy all five schemas, and declaring one of them is a claim the serializer
+ * can actually back. Each hop between them is a DATA migration, and each targets
+ * something this SDK either never emits or already emits in its post-hop form:
+ * 1.6→1.7 rewrites three HITL sub-type node types, 1.7→1.8 reshapes
+ * document-validation HITL inputs, 1.8→1.9 annotates stored Dynamic Extract
+ * definitions, 1.9→1.10 repairs connector binding names.
+ *
+ * **Why the floor is 1.6.** Below it the shape genuinely differs: expressions
+ * are legacy `=js:` strings rather than the `{ type, expression, fieldType }`
+ * envelope this SDK writes (the envelope arrives with the 1.2→1.3 hop), and the
+ * 1.3→1.4 hop REVERTS agent and inline-agent-resource node inputs to the legacy
+ * string form. A target below 1.6 would hand a reader a document its own hops
+ * would reshape, so it is refused rather than stamped. That is the same line
+ * `migrate.ts`'s `VERSION_CONDITIONAL` ladder draws at `from: '1.6'` — the
+ * ladder gate and this floor are the same fact stated twice, which is why the
+ * gate is inert today and becomes live the day a lower target is supported.
+ *
+ * **Why 1.9 stays the DEFAULT** rather than the newest version: the floor is a
+ * deployed-reader boundary, not a quality ranking. `flow-workbench`'s own
+ * `MINIMUM_SUPPORTED_SCHEMA_VERSION` comment says not to advance it "until every
+ * deployed reader — including the CLI, Studio Web, and VS Code — can read the
+ * target version". So declaring 1.10 buys currency at the cost of reader
+ * compatibility and declaring 1.8 buys compatibility at the cost of a migration
+ * hop on every open; `check()` names the trade in both directions rather than
+ * picking for the author.
+ */
+export const FLOW_SCHEMA_VERSIONS = {
+    family: 'flow',
+    mode: 'enumerated',
+    method: '.schemaVersion',
+    default: FLOW_FORMAT_PROFILE.version,
+    latestKnown: '1.10',
+    migration: 'Moving a document between versions is `uip maestro flow migrate`\'s job — it owns the hops, '
+        + 'including data repairs this SDK cannot reproduce from the source alone.',
+    writable: [
+        {
+            version: '1.6',
+            evidence: 'The oldest version whose shape this SDK emits: the `{ type, expression, fieldType }` envelope form. '
+                + '`workflowSchemaV1_6` is `workflowSchemaV1_5.extend({ version })`, and the 1.5→1.6 hop only renames the '
+                + 'built-in `deeprag` agent tool node type to `summarize` (MST-10301) — a node type this SDK does not emit.',
+        },
+        {
+            version: '1.7',
+            sameBytesAs: '1.6',
+            evidence: '`workflowSchemaV1_7 = workflowSchemaV1_6.extend({ version })`. The 1.6→1.7 hop is data-only, over the '
+                + 'three HITL sub-type node types (quick-form, coded-action-app, document-validation).',
+        },
+        {
+            version: '1.8',
+            sameBytesAs: '1.6',
+            evidence: '`workflowSchemaV1_8 = workflowSchemaV1_7.extend({ version })`. The 1.7→1.8 hop is data-only, over '
+                + 'document-validation HITL inputs (drops `inputs.documentId`, adds the Action App section). The deployed '
+                + 'corpus this SDK is measured against is largely 1.8, so preserving it is the common brownfield case.',
+        },
+        {
+            version: '1.9',
+            sameBytesAs: '1.6',
+            evidence: 'The fleet write floor (`MINIMUM_SUPPORTED_SCHEMA_VERSION`) and what this SDK has emitted and validated '
+                + 'all along. `workflowSchemaV1_9 = workflowSchemaV1_8.extend({ version })`; the 1.8→1.9 hop only '
+                + 'annotates stored Dynamic Extract definitions, which this SDK never emits.',
+        },
+        {
+            version: '1.10',
+            sameBytesAs: '1.6',
+            evidence: '`workflowSchemaV1_10 = workflowSchemaV1_9.extend({ version: z.literal("1.10") })` — the 1.10 schema '
+                + 're-declares only the version literal. Its hop (`migrations/src/migrations/v1.9-to-v1.10.ts`) is a DATA '
+                + "REPAIR: it renames a connector's single `ConnectionId` binding to `<connector> connection`, and its "
+                + '`down()` restores only the version marker. That repair targets a defect this SDK cannot produce — '
+                + 'connection binding names come from the definition verbatim (`model.bindings.values[].name`, else the '
+                + '`<bindings.…>` placeholder in `model.context`), never built from the connector key (card G22: the '
+                + 'shortcut is wrong for 892 of 2,648 registry definitions).',
+        },
+    ],
+};

package/dist/generators/_connections.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Find the connection for a connector, and write its bindings.
+
+`prepare` already knows which connector it is preparing. Making the author go
+and find that connector's connection id by hand — and then its folder key, and
+then hand-write `bindings.json` around both — is work the command can do itself
+from information it already has.
+
+Measured on the eval corpus, that hand-work was 4 to 7 tool calls per task:
+listing connections, filtering them, then (because nothing said the folder key
+was on the connection record) three or four more spent searching Orchestrator
+folders for one matching the symbolic name in the prompt.
+
+THE ONE THING THIS MUST NOT DO IS GUESS. A tenant can carry several connections
+for the same connector — this repo's test tenant has five for Slack — and they
+are not interchangeable: a user who exists in one workspace does not exist in
+another, so picking the wrong one makes a lookup unresolvable for a reason that
+points nowhere near the actual mistake. That failure was observed directly
+(`skill-flow-slack-dm-lookup` named the wrong workspace and burned its whole
+turn budget), which is why ambiguity here is an error listing the candidates and
+never a silent choice.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+__all__ = [
+    "ConnectionError_",
+    "byoa_connections",
+    "byoa_listing",
+    "discover_connection",
+    "lookup_connection",
+    "merge_bindings",
+]
+
+
+class ConnectionError_(Exception):
+    """No usable connection, with the reason and the way forward."""
+
+
+def _list(all_folders: bool, byoa: bool = False) -> list[dict]:
+    command = ["uip", "is", "connections", "list", "--output", "json"]
+    if all_folders:
+        command.insert(4, "--all-folders")
+    if byoa:
+        command.insert(4, "--byoa")
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise ConnectionError_(
+            "listing connections failed: "
+            f"{result.stderr.strip() or 'no output'}"
+        )
+    try:
+        payload = json.loads(result.stdout)
+    except ValueError as error:
+        raise ConnectionError_(f"connection listing was not JSON: {error}") from error
+    data = payload.get("Data")
+    if isinstance(data, dict):
+        data = data.get("items")
+    return data if isinstance(data, list) else []
+
+
+def _matching(rows: list[dict], connector_key: str, name: str | None) -> list[dict]:
+    out = [
+        row for row in rows
+        if row.get("ConnectorKey") == connector_key
+        # A Failed connection is listed like any other and cannot serve a
+        # request; selecting one produces an error about the operation rather
+        # than about the connection, which sends the reader the wrong way.
+        and str(row.get("State", "")).lower() == "enabled"
+    ]
+    if name:
+        out = [row for row in out if row.get("Name") == name]
+    return out
+
+
+def discover_connection(connector_key: str, name: str | None = None) -> dict:
+    """The one enabled connection for `connector_key`, or raise.
+
+    Tries the DEFAULT listing first and only widens to `--all-folders` if that
+    finds nothing. That order matters and is not just politeness to the API: the
+    default listing is the caller's own folder, which on a real tenant is one
+    connection where the tenant-wide view is many. Widening first would turn an
+    unambiguous case into an ambiguous one.
+    """
+    rows = _matching(_list(all_folders=False), connector_key, name)
+    scope = "your folder"
+    if not rows:
+        rows = _matching(_list(all_folders=True), connector_key, name)
+        scope = "the tenant"
+
+    if not rows:
+        qualifier = f" named {name!r}" if name else ""
+        raise ConnectionError_(
+            f"no enabled {connector_key} connection{qualifier} found in {scope}. "
+            f"List what exists with:\n"
+            f"  uip is connections list --all-folders"
+        )
+    if len(rows) > 1:
+        # Every candidate line carries its id: a NAME is not a key on a tenant.
+        # The eval tenant holds three Slack connections all named
+        # `is-sandboxes` (two Enabled, in different folders), so the old remedy —
+        # "name the one you want with --connection <name>" — handed back the very
+        # flag the caller had just used, and the doc-following author dead-ended
+        # (skill-flow-e2e-escalation-orchestrator-paths, 2026-09-01: placeholder
+        # GUIDs hand-written into bindings.json, 401 at the Slack node).
+        listed = "\n".join(
+            f"    {row.get('Name')}  --connection-id {row.get('Id')}"
+            f"  (folder: {row.get('Folder')})"
+            for row in rows
+        )
+        names = {str(row.get("Name")) for row in rows}
+        if name is not None or len(names) < len(rows):
+            remedy = (
+                "They share a name, so --connection <name> cannot pick one; pass "
+                "the id of the one in the folder you mean with --connection-id:"
+            )
+        else:
+            remedy = (
+                "Name the one you want with --connection <name>, or pass its id "
+                "with --connection-id:"
+            )
+        raise ConnectionError_(
+            f"{len(rows)} enabled {connector_key} connections in {scope}, and they "
+            f"are not interchangeable — a record that exists in one workspace need "
+            f"not exist in another. {remedy}\n{listed}"
+        )
+    return rows[0]
+
+
+def _enabled_listing(rows: list[dict], connector_key: str) -> str:
+    """The enabled connections for `connector_key`, one per line, pasteable."""
+    enabled = _matching(rows, connector_key, None)
+    if not enabled:
+        return (
+            f"    (none — this tenant has no Enabled {connector_key} connection; "
+            "repair or create one in Integration Service first)"
+        )
+    return "\n".join(
+        f"    {row.get('Name')}  --connection-id {row.get('Id')}"
+        f"  (folder: {row.get('Folder')})"
+        for row in enabled
+    )
+
+
+def lookup_connection(connector_key: str, connection_id: str) -> dict:
+    """The record for an explicitly named connection, or raise unless it can serve.
+
+    An explicit `--connection-id` used to skip every check discovery applies, and
+    that skip is where a whole class of silent failures came from. A connection
+    in `State: Failed` is listed like any other, and `uip is resources describe`
+    against it answers `Result: Success` with NO request fields — the tenant has
+    no schema to give for a connection it cannot reach. `prepare` then wrote an
+    overlay with zero body inputs, printed "0 input field(s)" as a success, and
+    the next `compile` rejected every real field as unknown, sending the author
+    hunting through the SDK for a flag that does not exist.
+
+    Measured on the eval tenant (Salesforce `Opportunity` / `Update`): the Failed
+    connection returned 0 request fields, the Enabled one 13 (`StageName` among
+    them). The state was visible in the same `connections list` the author had
+    already run; a projection that dropped the `State` column hid it.
+
+    So: resolve the id against the tenant-wide listing, and refuse — naming the
+    state found and the enabled alternatives — rather than describe through it.
+    """
+    rows = _list(all_folders=True)
+    match = next(
+        (row for row in rows if str(row.get("Id", "")) == str(connection_id)), None
+    )
+    alternatives = _enabled_listing(rows, connector_key)
+    if match is None:
+        raise ConnectionError_(
+            f"connection {connection_id} is not in this tenant's listing "
+            f"(`uip is connections list --all-folders`). Enabled {connector_key} "
+            f"connections:\n{alternatives}\n"
+            "Or omit --connection-id and prepare selects the connection itself."
+        )
+    actual_key = match.get("ConnectorKey")
+    if actual_key and actual_key != connector_key:
+        raise ConnectionError_(
+            f"connection {match.get('Name')} ({connection_id}) belongs to connector "
+            f"{actual_key}, not {connector_key}. Enabled {connector_key} "
+            f"connections:\n{alternatives}\n"
+            "Or omit --connection-id and prepare selects the connection itself."
+        )
+    state = str(match.get("State", "") or "")
+    if state.lower() != "enabled":
+        shown = state or "in an unknown state"
+        raise ConnectionError_(
+            f"connection {match.get('Name')} ({connection_id}) is {shown}, not "
+            "Enabled. A connection that is not Enabled answers field discovery "
+            "with an EMPTY schema, so the overlay would carry no fields and the "
+            "next compile would still reject every input as unknown. Enabled "
+            f"{connector_key} connections:\n{alternatives}\n"
+            "Or omit --connection-id and prepare selects the connection itself."
+        )
+    return match
+
+
+def byoa_connections(connector_key: str) -> list[dict]:
+    """The enabled BYOA connections for `connector_key`.
+
+    RAISES on a failed listing rather than answering an empty list. The
+    difference is the whole point: "you have no BYOA connection" tells the
+    caller to go create one, and a listing that failed says nothing of the
+    kind. Answering [] for both turns a broken call into confident, wrong
+    advice — the failure-is-not-emptiness rule this module already applies to
+    ordinary discovery.
+    """
+    return _matching(_list(all_folders=True, byoa=True), connector_key, None)
+
+
+def byoa_listing(rows: list[dict], connector_key: str) -> str:
+    """The BYOA candidates, one pasteable line each, or why there are none."""
+    if not rows:
+        return (
+            f"    (none — this tenant has no enabled BYOA {connector_key} "
+            "connection; create one in Integration Service with your own "
+            "OAuth app, then re-run)"
+        )
+    return "\n".join(
+        f"    {row.get('Name')}  --connection-id {row.get('Id')}"
+        f"  (folder: {row.get('Folder')})"
+        for row in rows
+    )
+
+
+def merge_bindings(
+    path: str,
+    connection: dict,
+    connection_name: str,
+    folder_name: str,
+) -> tuple[bool, bool]:
+    """Add connection + folder entries to `bindings.json`, in place.
+
+    ADDITIVE AND IDEMPOTENT. An existing entry under the same symbolic name is
+    updated, never duplicated, and every other entry is left exactly as it was —
+    `bindings.json` is an authored file that may already carry bindings for
+    connectors this run knows nothing about.
+
+    Returns `(wrote_connection, wrote_folder)` describing what changed, so the
+    caller can report the specific thing rather than "updated bindings".
+    """
+    import os
+
+    document: dict = {"schemaVersion": "1", "bindings": []}
+    if os.path.exists(path):
+        try:
+            with open(path, encoding="utf-8") as handle:
+                loaded = json.load(handle)
+            if isinstance(loaded, dict):
+                document = loaded
+                document.setdefault("schemaVersion", "1")
+                document.setdefault("bindings", [])
+        except (OSError, ValueError):
+            # A malformed bindings.json is the author's file and not ours to
+            # discard: refuse rather than overwrite work we cannot read.
+            raise ConnectionError_(
+                f"{path} exists but is not readable JSON. Fix or remove it; "
+                "this command will not overwrite a file it cannot parse."
+            )
+
+    def upsert(symbolic: str, key: str, attribute: str) -> bool:
+        for entry in document["bindings"]:
+            if entry.get("name") == symbolic or entry.get("id") == symbolic:
+                changed = entry.get("resourceKey") != key
+                entry.update({
+                    "id": entry.get("id", symbolic), "name": symbolic,
+                    "resource": "Connection", "resourceKey": key,
+                    "default": key, "propertyAttribute": attribute,
+                })
+                return changed
+        document["bindings"].append({
+            "id": symbolic, "name": symbolic, "resource": "Connection",
+            "resourceKey": key, "default": key, "propertyAttribute": attribute,
+        })
+        return True
+
+    wrote_connection = upsert(connection_name, str(connection["Id"]), "ConnectionId")
+    wrote_folder = upsert(folder_name, str(connection["FolderKey"]), "FolderKey")
+
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(document, handle, indent=2)
+        handle.write("\n")
+    return wrote_connection, wrote_folder