@uipath/maestro-builder-sdk 6.49.2 → 6.50.0

package/dist/check.d.ts

@@ -29,6 +29,11 @@ export interface ListEnvelopeFields {
 export interface CheckOpts extends ConnectorCheckOpts, EventCheckOpts {
     /** Resolve the measured collection envelope for one connector operation. */
     listEnvelope?: (connector: string, operation: string, version?: string, object?: string) => ListEnvelopeFields | undefined;
+    /**
+     * The library's definition for one connector operation, the one compile places:
+     * whether it grants an error port is then the same answer in both rungs.
+     */
+    connectorDefinition?: (connector: string, operation: string, version?: string, object?: string) => unknown;
 }
 export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
 /**

package/dist/check.js

@@ -230,7 +230,6 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
     // Step name → the read rule for its output, bound to its inputs. Filled from
     // OUTPUT_READ_RULES for every kind whose inputs take a `returns`.
     const outputReaders = new Map();
-    const connectorSteps = new Map();
     // Subflow step name → the child flow it runs. A subflow's output is the
     // OBJECT of the child's declared outputs, so a read of it is checked against
     // that child rather than waved through (see SUBFLOW_* below).
@@ -346,7 +345,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                         declared.add(v);
             }
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'error')
-                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), carriedLookup([built, ...ancestors]));
+                checkOnError(s, prevPortSource, diags, prevPortSource && checkedSteps.get(prevPortSource.name), opts, carriedLookup([built, ...ancestors]));
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port.startsWith('branch-')) {
                 const want = s.port.slice('branch-'.length);
                 const prevSpec = prevAction?.spec;
@@ -465,12 +464,6 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                 else {
                     collectActionExprs(s, exprs, errorSource);
                 }
-                if (s.spec.kind === 'connector') {
-                    connectorSteps.set(s.name, s.spec);
-                    checkConnectorLookups(s.name, s.spec, opts, diags);
-                    checkConnectorSchema(s.name, s.spec, opts, diags);
-                    checkConnectorContract(s.name, s.spec, opts, diags);
-                }
                 // A custom FlowAction subclass has no `kind`: the family rules below
                 // don't apply, and it reports through its own diagnostics() hook.
                 const maybeCustom = s.spec;
@@ -715,7 +708,7 @@ function checkFlow(built, ancestors, opts = {}, ledger = newResourceIdLedger())
                 // handle); it is not a legal source for anything else.
                 prevPortSource = s;
                 addExpr(s.collection.js, s.name);
-                checkLoopListEnvelope(s, connectorSteps, opts, diags);
+                checkLoopListEnvelope(s, registeredSteps, opts, diags);
                 if (s.options?.completionCondition)
                     addExpr(s.options.completionCondition.js, s.name);
                 // The same refusal serialize throws, from the same helper: an option or
@@ -1377,16 +1370,18 @@ function checkConnectorContract(step, spec, opts, diags) {
     coreCheckConnectorContract(where, spec, opts, report, step);
     checkBindingPresence(`connector "${step}"`, spec, (code, message) => report({ level: 'error', code, message }), { key: spec.key, action: spec.action });
 }
-/** Reject a wrapper hop when the runtime shape of a list has been measured. */
-function checkLoopListEnvelope(loop, connectors, opts, diags) {
+/**
+ * Reject a wrapper hop when the runtime shape of a list has been measured: the
+ * step the loop reads says what its list output looks like (`listShape`, a
+ * connector operation's measured envelope).
+ */
+function checkLoopListEnvelope(loop, registered, opts, diags) {
     const read = /^\$vars\.([^.]+)\.output\.([A-Za-z_$][\w$]*)$/.exec(loop.collection.js);
-    if (!read || !opts.listEnvelope)
+    if (!read)
         return;
     const [, step, field] = read;
-    const connector = connectors.get(step);
-    if (!connector)
-        return;
-    const measured = opts.listEnvelope(connector.key, connector.action, connector.version, connector.object);
+    const source = registered.get(step);
+    const measured = source?.impl.listShape?.(source.spec, opts);
     if (!measured || measured.envelope === field)
         return;
     const shape = measured.envelope === null
@@ -2723,6 +2718,12 @@ function checkRegisteredStep(entry, s, exprs, errorSource, opts, diags, typeOf,
             },
             options: opts,
             bindingLabels: (where, labels, use, target) => checkBindingLabels(where, labels, opts, (code, message) => diags.push({ level: 'error', code, step: s.name, message }), target, use),
+            connector: (c) => {
+                const spec = c;
+                checkConnectorLookups(s.name, spec, opts, diags);
+                checkConnectorSchema(s.name, spec, opts, diags);
+                checkConnectorContract(s.name, spec, opts, diags);
+            },
             resources: {
                 derivedNodeId: (id, what) => { if (!ledger.taken.has(id))
                     ledger.taken.set(id, what); },
@@ -2861,39 +2862,7 @@ function collectActionExprs(s, out, errorSource) {
             push(val);
         return;
     }
-    if (s.spec.kind === 'connector') {
-        // Same gap on the connector surface: `messageToSend: tmpl`…${v('typo')}``
-        // reached the runtime unchecked.
-        pushDeep(s.spec.inputs);
-    }
 }
-/**
- * The families with no definition this SDK can ask, and an error port anyway:
- * an Integration Service connector activity's definition comes from the
- * connector library, and every connector activity declares the `error` handle.
- *
- * Every other family is decided by a definition, never by a list:
- *
- *  - a bundled family by its bundled definition (`bundledActionNodeType` +
- *    `bundledDefinition`, #1011: `documentClassify` was missing from the old
- *    list although `uipath.document.classify@1.0` sets the flag);
- *  - a per-tenant family by the definition serialize synthesizes for it: a
- *    registered one (the process family, `agent` among it) through its node
- *    type's `errorPort`, which asks that definition, and `ixpExtract` through
- *    `perCallDefinition` (#1040: `publishedFunction` was refused here although
- *    `publishedFunctionDef` sets the flag).
- *
- * `publishedFunction`'s flag is measured, not assumed: on 2026-10-08 four
- * `flow debug` jobs on alpha/codereval called `acme-echo` with a non-string
- * `message` (null, object, number, array). In each, the function job failed
- * (`Python.FUNCTION_EXECUTION_ERROR`, category User, status 502), the node's
- * error boundary fired, and the handler's `err('message')` read
- * "Failure in the Orchestrator Job".
- *
- * A kind in none of these (`waitEvent`) has no error port: an event wait
- * resumes or does not.
- */
-const NO_DEFINITION_ERROR_PORT_KINDS = new Set(['connector']);
 /**
  * The ONERROR_NO_ERROR_PORT sentence for a typed step — a built-in family or a
  * registered node type — whose node type has no error port. One spelling for
@@ -2913,10 +2882,33 @@ const ERROR_ENVELOPE_FIELDS = ['code', 'message', 'detail', 'category', 'status'
  * `.onError(...)`-specific checks. The surface already refuses the structural
  * mistakes at build time (no previous step, two handlers on one node, an empty
  * handler); these are the ones only a checker can see.
+ *
+ * Whether the step has an error port at all: every family is decided by a
+ * definition, never by a list:
+ *
+ *  - a bundled family by its bundled definition (`bundledActionNodeType` +
+ *    `bundledDefinition`, #1011: `documentClassify` was missing from the old
+ *    list although `uipath.document.classify@1.0` sets the flag);
+ *  - a per-tenant family — every one is registered — through its node type's
+ *    `errorPort`, which asks the definition serialize synthesizes (#1040:
+ *    `publishedFunction` was refused here although `publishedFunctionDef` sets
+ *    the flag), or for a connector the library's definition, which check reads
+ *    through `connectorDefinition` and, without a library, assumes grants the
+ *    port, as every operation the library serves does.
+ *
+ * `publishedFunction`'s flag is measured, not assumed: on 2026-10-08 four
+ * `flow debug` jobs on alpha/codereval called `acme-echo` with a non-string
+ * `message` (null, object, number, array). In each, the function job failed
+ * (`Python.FUNCTION_EXECUTION_ERROR`, category User, status 502), the node's
+ * error boundary fired, and the handler's `err('message')` read
+ * "Failure in the Orchestrator Job".
+ *
+ * A kind in none of these (`waitEvent`) has no error port: an event wait
+ * resumes or does not.
  */
 function checkOnError(_handler, step, diags, 
 /** The step's registry record, when its kind is registered and its version resolved. */
-placed, carried) {
+placed, opts, carried) {
     // The builder refuses a handler with no eligible step before it, so a missing
     // source here means a hand-built `BuiltFlow`; there is nothing to say about it.
     if (!step)
@@ -2986,11 +2978,17 @@ placed, carried) {
             }
         }
         else if (impl.definition === 'per-tenant') {
-            const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
+            // The definition serialize will be supplied, when check's options can name
+            // it (a connector's, from the library); the type answers without it otherwise.
+            const def = impl.checkDefinition?.(placed.spec, opts);
+            const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec, def) : impl.errorPort === true;
             if (!port) {
+                const named = def !== undefined && typeof def.nodeType === 'string' && typeof def.version === 'string';
                 diags.push({
                     level: 'error', code: 'ONERROR_NO_ERROR_PORT', step: step.name,
-                    message: declaredErrorPortRefusal(step.name, impl.typeName, impl.version),
+                    message: named
+                        ? declaredErrorPortRefusal(step.name, def.nodeType, def.version)
+                        : declaredErrorPortRefusal(step.name, impl.typeName, impl.version),
                 });
                 return;
             }
@@ -3025,7 +3023,7 @@ placed, carried) {
     // a carried definition); what is left is bundled, or has no definition here.
     const noPort = bundledDef !== undefined
         ? !definitionHasErrorPort(bundledDef)
-        : !bundledType && !NO_DEFINITION_ERROR_PORT_KINDS.has(spec.kind);
+        : !bundledType;
     if (noPort) {
         diags.push({
             level: 'error',

package/dist/cli-library.js

@@ -25,5 +25,13 @@ export function flowCheckOpts(library, bindings) {
                 return undefined; // an unresolvable operation is connectorResolveError's to report
             }
         },
+        connectorDefinition: (connector, operation, version, object) => {
+            try {
+                return library.resolve(connector, operation, version, object).v1def;
+            }
+            catch {
+                return undefined; // as above
+            }
+        },
     };
 }

package/dist/core/connector-inputs.d.ts

@@ -46,6 +46,8 @@ export interface ConnectorInputOpts {
 }
 /** Flow's dialect, re-exported so `serialize.ts` need not reach past this module. */
 export { FLOW_EXPR_DIALECT } from './connector-checks.js';
+/** A required connector input left empty — the one draft code with no error class of its own. */
+export declare const CONNECTOR_INPUT_MISSING = "CONNECTOR_INPUT_MISSING";
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — the SAME code path `buildConnectorInputs` runs at emit time,

package/dist/core/connector-inputs.js

@@ -30,6 +30,8 @@ export { FLOW_EXPR_DIALECT } from './connector-checks.js';
 import { FLOW_EXPR_DIALECT as FLOW_DIALECT } from './connector-checks.js';
 import { ownEntry } from './own-entry.js';
 import { isRecord } from './node-envelope.js';
+/** A required connector input left empty — the one draft code with no error class of its own. */
+export const CONNECTOR_INPUT_MISSING = 'CONNECTOR_INPUT_MISSING';
 /**
  * Validate a connector's activity inputs against its declared field list and
  * return them ROUTED to the wire slots the platform reads. Catches the three
@@ -106,10 +108,12 @@ export function buildConnectorInputs(rc, inputs, opts) {
     // container the runtime composes from `bodyParameters`, so it is listed without
     // a value and is never an author input — see `readFields` in core/library.ts.
     const partValues = new Map();
+    const bare = bareArraySpellings(fields, byName);
     for (const f of fields) {
-        const flat = Object.prototype.hasOwnProperty.call(inputs, f.name);
+        const flatKey = flatInputKey(inputs, f.name, bare, dialect);
+        const flat = flatKey !== undefined;
         let nested = flat
-            ? { found: true, value: inputs[f.name], projectedArrays: 0 }
+            ? { found: true, value: inputs[flatKey], projectedArrays: 0 }
             : readConnectorPath(inputs, f.name, dialect);
         if (!nested.found) {
             // A required LOOKUP field is missing far more often because the author does
@@ -326,6 +330,51 @@ function place(target, parts, index, value) {
     target[part.key] = next;
     place(next, parts, index + 1, value);
 }
+/**
+ * The flat key the product writes for each array LEAF field, by its wire name:
+ * `fields.components_arrayRemap_name` for `fields.components_arrayRemap_name[*]`.
+ *
+ * Product-authored flows key `bodyParameters` either way (86 Slack
+ * `create-group-direct-message` nodes in the eval archive, almost all from the v1
+ * CLI arm, carry bare `users`; 85 carry `users[*]`; a Studio Web save in
+ * #1402 carried a bare Jira key), and the runtime reads both the same for an array
+ * value (flow-v1 `convertDotNotationToNested`). The nested reader already strips
+ * the marker, so `{ users: [...] }` compiled, but a DOTTED bare key reached only
+ * the exact flat lookup and was refused as unknown — so a designer-saved Jira
+ * flow decompiled to source that did not compile back (#1402).
+ *
+ * Only a trailing `[*]` with none before it: `contacts.id` is not `contacts[*].id`
+ * (the runtime nests it as an object, not a list). A bare name that is itself a
+ * declared field keeps its own meaning.
+ */
+function bareArraySpellings(fields, declared) {
+    const bare = new Map();
+    for (const f of fields) {
+        if (!f.name.endsWith('[*]'))
+            continue;
+        const key = f.name.slice(0, -3);
+        if (key.includes('[*]') || declared.has(key))
+            continue;
+        bare.set(f.name, key);
+    }
+    return bare;
+}
+/**
+ * The flat key `inputs` carries field `name` under: its wire name, or its bare
+ * spelling when the value there is an array or opaque. A bare SCALAR is left to
+ * the nested reader, which refuses it ("expected array"), as before: under
+ * `users[*]` the runtime would wrap `"U1,U2"` into `["U1,U2"]`, a different
+ * request from the one the bare key sends.
+ */
+function flatInputKey(inputs, name, bare, dialect) {
+    if (Object.prototype.hasOwnProperty.call(inputs, name))
+        return name;
+    const key = bare.get(name);
+    if (key === undefined || !Object.prototype.hasOwnProperty.call(inputs, key))
+        return undefined;
+    const value = inputs[key];
+    return Array.isArray(value) || dialect.isOpaque(value) ? key : undefined;
+}
 function connectorPath(name) {
     return name.split('.').map((raw) => ({
         key: raw.endsWith('[*]') ? raw.slice(0, -3) : raw,
@@ -385,6 +434,7 @@ function buildConnectorInputTrie(fields) {
 function validateNestedConnectorKeys(fields, inputs, exact, dialect) {
     const root = buildConnectorInputTrie(fields);
     const errs = [];
+    const bare = new Set(bareArraySpellings(fields, exact).values());
     const visit = (value, node, path) => {
         if (dialect.isOpaque(value))
             return;
@@ -422,6 +472,13 @@ function validateNestedConnectorKeys(fields, inputs, exact, dialect) {
         if (exact.has(key))
             continue; // backwards-compatible flat authoring
         const node = root.children.get(key);
+        // A dotted bare array key (`fields.labels` for `fields.labels[*]`); a
+        // top-level one (`users`) is a trie child and is checked by `visit` below.
+        if (!node && bare.has(key)) {
+            if (!Array.isArray(value) && !dialect.isOpaque(value))
+                errs.push(`input "${key}" expected array, got ${typeof value}`);
+            continue;
+        }
         if (!node) {
             const near = nearestField(key, [...exact.keys()]);
             errs.push(`unknown input "${key}"${near ? ` — did you mean "${near}"?` : ''}`);

package/dist/core/nodes/node-type.d.ts

@@ -106,6 +106,8 @@ export interface FactoryCall {
     readonly factory: string;
     readonly positional?: readonly string[];
     readonly options?: ReadonlyArray<readonly [name: string, source: string | undefined]>;
+    /** A note for the reader, written as a block comment after the call (the artifact escapes it). */
+    readonly comment?: string;
 }
 /** The contexts an artifact lends its node types, one per job. */
 export interface ArtifactContexts {
@@ -131,8 +133,11 @@ export interface NodeType<Spec, Serialized, Ctx extends ArtifactContexts> {
      * Whether the node has an error port. A `bundled` type must omit it — the answer
      * is the definition's, at this version. A `per-tenant` type must declare it,
      * because there is no definition to ask. The registry refuses either mistake.
+     * Serialize passes the definition the type supplied as `definition`, for a type
+     * whose definition comes from outside the SDK (a connector's, from its
+     * library); check, which has no definition, passes none.
      */
-    readonly errorPort?: boolean | ((spec: Spec) => boolean);
+    readonly errorPort?: boolean | ((spec: Spec, definition?: unknown) => boolean);
     /** Spec → the node's type-owned fields. The artifact still owns id, label, layout, edges and dedupe. */
     serialize(spec: Spec, ctx: Ctx['serialize']): Serialized;
     /** The lift: one serialized node → the spec it came from, or `undefined` when it is not this type's. */

package/dist/core/nodes/versioned.d.ts

@@ -33,6 +33,13 @@ Impl extends NodeType<Spec, Serialized, Ctx> = NodeType<Spec, Serialized, Ctx>>
      * exact name sit under the prefix as long as this rejects it.
      */
     typeNameMatches?(typeName: string): boolean;
+    /**
+     * One implementation answers for every version: the definition the type
+     * supplies names the node's version, as a connector operation's library entry
+     * does (1.0.0 for most, 4.0.0 for some). The registry then neither defaults nor
+     * refuses a `{ version }`; serialize holds the pin to that definition.
+     */
+    readonly versionedByDefinition?: boolean;
     readonly factory: string;
     /** The version used when the author names none. Changing it is a breaking change. */
     readonly defaultVersion: string;

package/dist/core/nodes/versioned.js

@@ -25,6 +25,11 @@ export function asVersioned(t) {
  * node type's bug, not the author's, and throws as an internal SDK error.
  */
 export function resolveVersion(t, spec, requested, where) {
+    if (t.versionedByDefinition) {
+        const only = ownEntry(t.versions, t.defaultVersion);
+        if (only)
+            return only;
+    }
     const selected = requested === undefined ? t.select?.(spec) : undefined;
     const version = requested ?? selected ?? t.defaultVersion;
     const impl = ownEntry(t.versions, version);
@@ -63,6 +68,12 @@ export function resolveVersion(t, spec, requested, where) {
  * implementation.
  */
 export function resolveVersionCarried(t, spec, requested, where, carried) {
+    // The definition names the version (see versionedByDefinition): a pin is the
+    // definition's to accept or refuse, not the registry's.
+    if (t.versionedByDefinition) {
+        const impl = resolveVersion(t, spec, undefined, where);
+        return { impl, version: requested ?? impl.version };
+    }
     if (requested !== undefined && !ownEntry(t.versions, requested)) {
         const def = carried?.(t.typeName, requested);
         if (def !== undefined) {

package/dist/decompile.js

@@ -774,7 +774,8 @@ function emitRegisteredSpec(node, imp, inputNames, graph) {
     };
     const options = opts((call.options ?? []).map(([k, v]) => [k, v]));
     const args = [...(call.positional ?? []), ...(options ? [options] : [])];
-    return `${imp.use(call.factory)}(${args.join(', ')})`;
+    return `${imp.use(call.factory)}(${args.join(', ')})`
+        + (call.comment !== undefined ? ` /* ${commentText(call.comment)} */` : '');
 }
 /**
  * Emit the action-spec argument for a `.step(id, <spec>)` call — e.g.
@@ -789,11 +790,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         return lifted;
     switch (node.type) {
         default:
-            // A connector action node: `uipath.connector.<key>.<action>` (but NOT the
-            // event nodes `uipath.connector.event.*` / `.trigger.*`, which are triggers).
-            if (node.type.startsWith('uipath.connector.') && !node.type.startsWith('uipath.connector.event.') && !node.type.startsWith('uipath.connector.trigger.')) {
-                return emitConnector(node, imp, inputNames, o);
-            }
             // A mid-flow connector EVENT wait (`uipath.connector.event.<key>.<event>`
             // placed as a step rather than as the start node).
             if (node.type.startsWith('uipath.connector.event.')) {
@@ -809,30 +805,6 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
             return unsupportedSpec(node, imp, o);
     }
 }
-/**
- * Split a connector `nodeType` (`uipath.connector.<key>.<action>`) into key +
- * action. Mirrors `core/connectors.ts`'s `splitConnectorNodeType`.
- */
-function splitConnector(nodeType) {
-    const rest = nodeType.replace(/^uipath\.connector\./, '');
-    const dot = rest.lastIndexOf('.');
-    if (dot <= 0)
-        return undefined;
-    return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
-}
-/** Pull `objectName` out of a connector's `=jsonString:` configuration blob, if present. */
-function connectorObjectName(configuration) {
-    if (typeof configuration !== 'string' || !configuration.startsWith('=jsonString:'))
-        return undefined;
-    try {
-        const cfg = JSON.parse(configuration.slice('=jsonString:'.length));
-        const name = cfg?.instanceParameters?.objectName ?? cfg?.objectName;
-        return typeof name === 'string' ? name : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Invert a connector action node into a `connector(key, action, inputs, opts)`
  * call. serialize routes author inputs into `detail.bodyParameters` /
@@ -948,41 +920,6 @@ function emitEventSubscription(node, imp, inputNames) {
         ['folder', folder !== undefined ? tsLiteral(folder) : undefined],
     ]) + unboundMarker(node, { connection: conn, folder }, connector, event);
 }
-function emitConnector(node, imp, inputNames, o) {
-    const split = splitConnector(node.type);
-    const detail = (node.inputs?.detail ?? {});
-    if (!split)
-        return unsupportedSpec(node, imp, o);
-    const slots = ['bodyParameters', 'queryParameters', 'pathParameters'];
-    const flat = [];
-    for (const s of slots) {
-        const m = detail[s];
-        if (m && typeof m === 'object' && !Array.isArray(m)) {
-            for (const [k, v] of Object.entries(m))
-                flat.push([k, emitVal(v, imp, inputNames)]);
-        }
-    }
-    const multipart = detail.multipartParameters;
-    if (Array.isArray(multipart)) {
-        for (const part of multipart) {
-            if (typeof part?.name === 'string' && Object.prototype.hasOwnProperty.call(part, 'value')) {
-                flat.push([part.name, emitVal(part.value, imp, inputNames)]);
-            }
-        }
-    }
-    const connection = typeof detail.connectionId === 'string' ? detail.connectionId : undefined;
-    const folder = typeof detail.connectionFolderKey === 'string' ? detail.connectionFolderKey : undefined;
-    const object = connectorObjectName(detail.configuration);
-    const optsSrc = opts([
-        ['connection', connection !== undefined ? tsLiteral(connection) : undefined],
-        ['folder', folder !== undefined ? tsLiteral(folder) : undefined],
-        ['object', object !== undefined ? tsLiteral(object) : undefined],
-    ]);
-    const inputsSrc = objLit(flat) || '{}';
-    const args = [tsLiteral(split.key), tsLiteral(split.action), inputsSrc, ...(optsSrc ? [optsSrc] : [])];
-    return `${imp.use('connector')}(${args.join(', ')})`
-        + unboundMarker(node, { connection, folder }, split.key, split.action);
-}
 /** Best-effort placeholder for a node type the reverse-map does not yet cover. */
 function unsupportedSpec(node, imp, o) {
     // The file's own definition for this node — the manifest the platform served.

package/dist/flow-node-registry.js

@@ -10,6 +10,7 @@ import { NodeTypeRegistry } from './core/nodes/registry.js';
 import { hasBundledDefinition } from './flow-definitions.js';
 import { agentFlowFamily } from './nodes/agent/flow/family.js';
 import { aiPatternsFlowFamily } from './nodes/ai-patterns/flow/family.js';
+import { connectorFlowFamily } from './nodes/connector/flow/family.js';
 import { conversationFlowFamily } from './nodes/conversation/flow/family.js';
 import { dataFabricFlowFamily } from './nodes/data-fabric/flow/family.js';
 import { delayFlowFamily } from './nodes/delay/flow/family.js';
@@ -22,5 +23,5 @@ import { queueFlowFamily } from './nodes/queue/flow/family.js';
 import { scriptFlowFamily } from './nodes/script/flow/family.js';
 import { transformFlowFamily } from './nodes/transform/flow/family.js';
 /** The families, in no significant order. Adding one is the whole of registering it. */
-export const FLOW_NODE_FAMILIES = [agentFlowFamily, aiPatternsFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
+export const FLOW_NODE_FAMILIES = [agentFlowFamily, aiPatternsFlowFamily, connectorFlowFamily, conversationFlowFamily, dataFabricFlowFamily, delayFlowFamily, documentFlowFamily, hitlFlowFamily, httpFlowFamily, mockFlowFamily, processFlowFamily, queueFlowFamily, scriptFlowFamily, transformFlowFamily];
 export const FLOW_NODE_TYPES = new NodeTypeRegistry('flow', FLOW_NODE_FAMILIES, { hasBundledDefinition });

package/dist/flow-node-type.d.ts

@@ -87,6 +87,19 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
         /** Display fields set over the definition's, after `shape: 'circle'` (a tool's `description`). */
         readonly display?: Readonly<Record<string, unknown>>;
     }>;
+    /**
+     * In a draft compile ({@link FlowSerializeContext.drafting}), the node the type
+     * cannot build — a generic connector operation saved before its object was
+     * picked has no definition — written as this stand-in: the given type,
+     * `typeVersion` and inputs (written as given), the step's label, no definition,
+     * `ui` or `model`. Merge restores the original when it is untouched. Everything
+     * else in the contribution is ignored but `port`.
+     */
+    standIn?: {
+        readonly type: string;
+        readonly typeVersion: string;
+        readonly inputs: Readonly<Record<string, unknown>>;
+    };
 }
 /** What `serialize` may ask of the serializer, for one placement. */
 export interface FlowSerializeContext {
@@ -213,6 +226,21 @@ export interface FlowSerializeContext {
     emitted(typeName: string, version: string): unknown;
     /** The connector library serialize was given, for a type that resolves a connector operation. */
     readonly library: SerializeOpts['library'];
+    /**
+     * Render a value and every `Expr` nested in its objects and arrays, as a
+     * connector's inputs are. A `lookup()` token is refused: it belongs only where a
+     * connector input resolves it (the whole value of a field, or an array element).
+     * An object result is a JSON copy that placement writes as is, so a `lit()`'s
+     * contents are not rendered a second time.
+     */
+    renderDeep(value: unknown): unknown;
+    /**
+     * Whether this is a draft compile (merge's): a refusal the author can still fix
+     * is reported through {@link draft} and the step emitted as far as it can be.
+     */
+    readonly drafting: boolean;
+    /** Report a draft finding on this node: what a non-draft compile would have refused. Only when {@link drafting}. */
+    draft(code: string, message: string): void;
 }
 /** What `deserialize` may ask of the decompiler, for one serialized node. */
 export interface FlowDeserializeContext {
@@ -349,6 +377,22 @@ export interface FlowCheckContext {
      * An explicit id equal to one another node gets is reported once the whole
      * file is checked (`INLINE_AGENT_RESOURCE_NODE_ID`).
      */
+    /**
+     * Run the rules every Integration Service operation shares — its lookups, its
+     * schema readiness, its contract against the library facts check was given
+     * (`options`), and BINDING_MISSING — on this step. Their codes are the
+     * pipeline's, shared with an event subscription's, so they belong to no
+     * family catalog; each is reported at its own severity.
+     */
+    connector(spec: {
+        key: string;
+        action: string;
+        version?: string;
+        object?: string;
+        connection?: unknown;
+        folder?: unknown;
+        inputs?: unknown;
+    }): void;
     readonly resources: {
         /** An id compile derives for one of this step's resources, and what it is, for that report. */
         derivedNodeId(id: string, what: string): void;
@@ -461,6 +505,21 @@ export interface FlowNodeType<Spec> extends NodeType<Spec, FlowNodeContribution,
      * the definition, an exit of the type, nor derived.
      */
     derivesPort?(spec: Spec, port: string): boolean;
+    /**
+     * The measured runtime shape of this step's LIST output, when it has one: a
+     * bare array (`envelope: null`) or an object holding it under `envelope`. A
+     * loop over the output checks its read against it (LIST_OUTPUT_WRAPPER).
+     * `options` are check's (a connector's measured list envelopes among them).
+     */
+    listShape?(spec: Spec, options: CheckOpts): {
+        envelope: string | null;
+    } | undefined;
+    /**
+     * The definition serialize will be supplied for a per-tenant type, when check's
+     * `options` can name it (a connector's, from the library). Check passes it to
+     * `errorPort`, so the two rungs give one answer; undefined when it cannot.
+     */
+    checkDefinition?(spec: Spec, options: CheckOpts): unknown;
 }
 /** A Flow node type with several versions. */
 export type FlowVersionedNodeType<Spec> = VersionedNodeType<Spec, FlowNodeContribution, FlowContexts, FlowNodeType<Spec>>;

package/dist/nodes/connector/flow/family.d.ts

@@ -0,0 +1,3 @@
+/** The connector node family, as flow-node-registry.ts lists it: an Integration Service connector operation. */
+import type { FlowNodeFamily } from '../../../flow-node-type.js';
+export declare const connectorFlowFamily: FlowNodeFamily;

package/dist/nodes/connector/flow/family.js

@@ -0,0 +1,8 @@
+import { connectorNodeType } from './node-type.js';
+export const connectorFlowFamily = {
+    id: 'connector',
+    title: 'Integration Service connector',
+    types: [connectorNodeType],
+    // Its rules' codes are the pipeline's, shared with an event subscription (ctx.connector).
+    diagnostics: {},
+};

package/dist/nodes/connector/flow/node-type.d.ts

@@ -0,0 +1,25 @@
+/**
+ * An Integration Service connector operation — `connector(key, action, inputs,
+ * opts)`, a node type per operation: `uipath.connector.<connectorKey>.<action>`.
+ * The type owns every name under `uipath.connector.` that is an operation
+ * (`typeNameMatches`): not an event subscription's `uipath.connector.event.*` or a
+ * trigger's `uipath.connector.trigger.*`, which belong to `waitForEvent()` and
+ * `onEvent()`. Per-tenant: the definition is the library entry's, and so is its
+ * version (`versionedByDefinition`; most operations are at 1.0.0, some at 4.0.0).
+ *
+ * The spec and `connector()` stay in core/actions.ts: Case imports the spec, and
+ * Case may not import a node family. The rules the connector shares with an event
+ * subscription — lookups, schema readiness, the library contract, the binding
+ * labels — stay in core and run through `ctx.connector`, with their codes.
+ *
+ * Moved from serialize.ts / check.ts / decompile.ts in Phase 4 of
+ * docs/NODE_TYPE_ARCHITECTURE_DESIGN.md; serialized output, printed source,
+ * codes and messages unchanged except for the three deliberate changes its 4o
+ * entry lists.
+ */
+import type { ActionSpec } from '../../../core/actions.js';
+import type { FlowVersionedNodeType } from '../../../flow-node-type.js';
+export type ConnectorSpec = Extract<ActionSpec, {
+    kind: 'connector';
+}>;
+export declare const connectorNodeType: FlowVersionedNodeType<ConnectorSpec>;

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

@@ -0,0 +1,294 @@
+import { BindingRefusal, bindingMissingMessage, missingBindingLabels } from '../../../core/binding-messages.js';
+import { prepareCommand } from '../../../core/cli-spelling.js';
+import { buildConfiguration } from '../../../core/connector-configuration.js';
+import { CONNECTOR_INPUT_MISSING, FLOW_EXPR_DIALECT, buildConnectorInputs, transportHttpMethod } from '../../../core/connector-inputs.js';
+import { ConnectorResolveError } from '../../../core/connector-resolve-error.js';
+import { definitionHasErrorPort } from '../../../core/error-port.js';
+import { Expr } from '../../../core/expr.js';
+import { jsonClone } from '../../../core/json-clone.js';
+import { subNodeId } from '../../../core/node-id-placeholder.js';
+import { synthesizedDefinitionRefusal } from '../../../core/synthesized-definition.js';
+import { tsLiteral, tsObject } from '../../../core/ts-literal.js';
+const CONNECTOR_PREFIX = 'uipath.connector.';
+/** `<key>.<action>` after the prefix, split on the last dot; undefined for an event, a trigger, or a name with no action. */
+function splitOperation(typeName) {
+    if (!typeName.startsWith(CONNECTOR_PREFIX))
+        return undefined;
+    const rest = typeName.slice(CONNECTOR_PREFIX.length);
+    if (rest.startsWith('event.') || rest.startsWith('trigger.'))
+        return undefined;
+    const dot = rest.lastIndexOf('.');
+    if (dot <= 0)
+        return undefined;
+    return { key: rest.slice(0, dot), action: rest.slice(dot + 1) };
+}
+/**
+ * The node's `output` slot for a LIST operation, declared as the ARRAY it is when
+ * the ledger has MEASURED that it is one ([#203](https://github.com/UiPath/flow-builder-sdk/issues/203)).
+ *
+ * Every connector definition declares `outputs.output.type: 'object'` — list
+ * operations included, and **0 of 544 deployed connector nodes declare `array`
+ * anywhere** (card CLEANUP's corpus scan). For most of the library that is the
+ * honest thing to emit, because the SDK does not know better. For an operation in
+ * the list-envelope ledger it does:
+ *
+ *   · `envelope: null` (a measured BARE array) ⇒ **`type: 'array'`**;
+ *   · a measured WRAPPER ⇒ `object`, unchanged — the value IS an object then;
+ *   · UNDECLARED ⇒ untouched, which is #202's status quo.
+ *
+ * Why this matters beyond tidiness: `typeAgentInputSchemas` builds an agent's
+ * pydantic input model from these declarations, and card ga7's scored run r2 died
+ * at `AGENT_STARTUP.INPUT_VALIDATION_ERROR` because a Data Service list node said
+ * `object` and the runtime sent 8 rows. #202 made that property TYPELESS, which
+ * unblocked the agent without asserting anything; this says the true thing.
+ *
+ * ## And deliberately NO item schema
+ *
+ * #203 suggested emitting the item fields alongside. They are not emitted, and the
+ * reason is a measurement rather than caution: a list operation's declared fields
+ * are **neither a superset nor a subset** of the real response (card LT, three live
+ * responses — ServiceNow `incident` declares 0 of the 103 fields it returns; Entra
+ * declares 20, returns 15, misses 2; Jira declares 253, returns 116, misses 42).
+ * Asserting them into an agent's pydantic model would reject real rows — the exact
+ * fault class above, moved rather than fixed. The library lift stays a READ-checking
+ * aid, where it fails open by design (lesson 26). The emitted bytes claim only what
+ * is certain: this is an array.
+ */
+function listOutputs(rc, nodeId) {
+    if (!rc.listEnvelope || rc.listEnvelope.envelope !== null)
+        return undefined;
+    const out = rc.v1def?.outputDefinition?.output;
+    if (!out || typeof out !== 'object' || out.type !== 'object')
+        return undefined;
+    return { output: { ...subNodeId(jsonClone(out), nodeId), type: 'array' } };
+}
+function serializeConnector(spec, ctx) {
+    const step = ctx.step;
+    if (!ctx.library)
+        throw new Error(`connector "${step}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
+    let rc;
+    try {
+        rc = ctx.library.resolve(spec.key, spec.action, spec.version, spec.object);
+    }
+    catch (error) {
+        if (!ctx.drafting || !(error instanceof ConnectorResolveError) || error.code !== 'CONNECTOR_OBJECT_REQUIRED')
+            throw error;
+        // A generic operation saved before its object was picked has no definition
+        // to emit against. Draft tolerance emits a stable stand-in under the node's
+        // id; merge restores the original when it is untouched and refuses it
+        // otherwise. It leaves on the port every connector action leaves on, so the
+        // no-edit round trip rewires nothing. Its inputs carry what the author wrote,
+        // so an edit to the node (an input, a connection) shows up as a change and
+        // merge refuses it instead of restoring the original.
+        ctx.draft(error.code, error.message);
+        return {
+            inputs: {},
+            port: 'output',
+            standIn: {
+                type: `${CONNECTOR_PREFIX}${spec.key}.${spec.action}`,
+                typeVersion: spec.version ?? '1.0.0',
+                inputs: {
+                    draft: true,
+                    spec: ctx.renderDeep(spec.inputs ?? {}),
+                    ...(spec.connection !== undefined ? { connection: spec.connection } : {}),
+                    ...(spec.folder !== undefined ? { folder: spec.folder } : {}),
+                },
+            },
+        };
+    }
+    // An entry `prepare` synthesized from Integration Service compiles in BPMN only.
+    const noDefinition = synthesizedDefinitionRefusal(rc);
+    if (noDefinition)
+        throw noDefinition;
+    const where = `connector "${step}"`;
+    const target = { key: spec.key, action: spec.action };
+    // A connector-bound node needs both labels (#890); check says so first
+    // (BINDING_MISSING). A draft that names no connection gets no binding rows
+    // either: there is nothing to bind, and rows with an empty resourceKey would
+    // leak into the merged file through merge's bindings union.
+    let unbound = false;
+    const missing = missingBindingLabels(spec);
+    if (missing.length > 0) {
+        const refusal = new BindingRefusal('BINDING_MISSING', bindingMissingMessage(where, missing, target));
+        if (!ctx.drafting)
+            throw refusal;
+        ctx.draft(refusal.code, refusal.message);
+        unbound = true;
+    }
+    const conn = ctx.resolveBinding(spec.connection, 'connection', where, target);
+    const folder = ctx.resolveBinding(spec.folder, 'folder', where, target);
+    // The platform reaches the connection through the flow's `bindings[]`, never
+    // through `inputs.detail` — without this pair the run faults with `[102010]`
+    // (board G-19).
+    if (!unbound) {
+        ctx.bindConnection({
+            model: rc.v1def?.model,
+            connectorKey: rc.connectorKey, connectionId: conn,
+            ...(folder !== undefined ? { folderKey: folder } : {}),
+        });
+    }
+    const library = ctx.library;
+    const connectorInputs = buildConnectorInputs(rc, spec.inputs, {
+        ...(ctx.drafting
+            ? { onMissingRequired: (m) => ctx.draft(CONNECTOR_INPUT_MISSING, `connector ${rc.nodeType}: ${m}`) }
+            : {}),
+        dialect: FLOW_EXPR_DIALECT,
+        render: (value) => ctx.renderDeep(value),
+        resolutions: library.lookupResolutions ?? {},
+        // Only for the missing-required hint; a test double that is not a full
+        // Library simply gets the plain message.
+        lookups: typeof library.lookupSpecs === 'function'
+            ? library.lookupSpecs(spec.key, spec.action, spec.version, spec.object)
+            : {},
+    });
+    const replayInputs = {
+        ...(connectorInputs.bodyParameters ?? {}),
+        ...(connectorInputs.pathParameters ?? {}),
+        ...(connectorInputs.queryParameters ?? {}),
+    };
+    const detail = {
+        connector: rc.connectorKey,
+        method: transportHttpMethod(rc.httpMethod),
+        endpoint: rc.endpoint,
+        // The op's object identity, as a SIBLING of the copy inside `configuration`
+        // — the designer emits both, and every connector node in a product-exported
+        // flow carries it. Conditional because the library defaults a missing
+        // `operation.objectName` to '' — an op that names no object gets no key.
+        ...(rc.objectName ? { objectName: rc.objectName } : {}),
+        inputMetadata: {},
+        errorState: { hasError: false },
+        telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
+        configuration: buildConfiguration(rc.entry, rc.version, replayInputs, ctx.nodeId),
+        ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
+        ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
+        ...(folder ? { connectionFolderKey: folder } : {}),
+    };
+    // Each input in the slot its LOCATION names — body → detail.bodyParameters,
+    // query → queryParameters, path → pathParameters, multipart →
+    // multipartParameters — checked against the operation's field list.
+    // `bodyParameters` is emitted unconditionally (3 of 1,283 deployed connector
+    // nodes carry an empty one); the others only when the op has inputs there.
+    Object.assign(detail, connectorInputs);
+    // The node is the operation the author named (`rc.nodeType`); a definition
+    // naming another — a library entry that borrowed one, as a synthetic test
+    // library does — is written under that name, so the node and its
+    // definitions[] entry agree.
+    const v1def = rc.v1def;
+    const def = v1def.nodeType === rc.nodeType ? v1def : { ...v1def, nodeType: rc.nodeType };
+    const outputs = listOutputs(rc, ctx.nodeId);
+    return {
+        definition: { source: 'snapshot', nodeType: def.nodeType, version: def.version, manifest: def },
+        inputs: { detail },
+        // Every connector operation leaves on `output`, named: a definition with no
+        // handles has no default to fall back on.
+        port: 'output',
+        ...(outputs !== undefined ? { outputs } : {}),
+    };
+}
+/** A connector input's value as decompile reads it: an expression back to an `Expr`, wire text as text, any other JSON as is. */
+function liftValue(v, ctx) {
+    const raw = Array.isArray(v) ? undefined : ctx.sourceText(v);
+    if (raw === undefined)
+        return v;
+    return raw.startsWith('=js:') ? new Expr(raw.slice(4)) : raw;
+}
+/** Pull `objectName` out of a connector's `=jsonString:` configuration blob, if present. */
+function configurationObjectName(configuration) {
+    if (typeof configuration !== 'string' || !configuration.startsWith('=jsonString:'))
+        return undefined;
+    try {
+        const cfg = JSON.parse(configuration.slice('=jsonString:'.length));
+        const name = cfg?.instanceParameters?.objectName ?? cfg?.objectName;
+        return typeof name === 'string' ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function liftConnector(node, ctx) {
+    const n = node;
+    const split = splitOperation(n.type);
+    if (!split)
+        return undefined;
+    const detail = (n.inputs?.detail ?? {});
+    const inputs = [];
+    for (const slot of ['bodyParameters', 'queryParameters', 'pathParameters']) {
+        const m = detail[slot];
+        if (m && typeof m === 'object' && !Array.isArray(m)) {
+            for (const [k, v] of Object.entries(m))
+                inputs.push([k, liftValue(v, ctx)]);
+        }
+    }
+    const multipart = detail.multipartParameters;
+    if (Array.isArray(multipart)) {
+        for (const part of multipart) {
+            if (typeof part?.name === 'string' && Object.prototype.hasOwnProperty.call(part, 'value')) {
+                inputs.push([part.name, liftValue(part.value, ctx)]);
+            }
+        }
+    }
+    const connection = typeof detail.connectionId === 'string' ? detail.connectionId : undefined;
+    const folder = typeof detail.connectionFolderKey === 'string' ? detail.connectionFolderKey : undefined;
+    // A connection the file never picked (`connectionId: null`): the source cannot
+    // invent labels for it, and compile refuses a node without both
+    // (BINDING_MISSING, flow-builder-sdk#890), so the source says so at the node
+    // and the run warns once.
+    const missing = missingBindingLabels({ connection, folder });
+    if (missing.length > 0) {
+        ctx.warn(`node ${tsLiteral(n.id)} (${n.type}) has no ${missing.join(' or ')} in the .flow (an unbound draft). `
+            + `The source leaves ${missing.length > 1 ? 'them' : 'it'} out, and compile refuses the node (BINDING_MISSING) `
+            + `until it names both labels: run \`${prepareCommand(split.key, split.action)}\`, then pass `
+            + `\`connection\` and \`folder\`.`);
+    }
+    return {
+        kind: 'connector', ...split, inputs, connection, folder,
+        object: configurationObjectName(detail.configuration),
+        missing,
+    };
+}
+function printConnector(l, ctx) {
+    // A present input whose value is `undefined` (the inputs check accepts one, and
+    // serialize keeps it in memory) prints as `undefined`, as it did before the port.
+    const value = (v) => (v === undefined ? 'undefined' : v instanceof Expr ? ctx.value(v) : ctx.json(v));
+    const optional = (v) => (v === undefined ? undefined : ctx.string(v));
+    return {
+        factory: 'connector',
+        positional: [ctx.string(l.key), ctx.string(l.action), tsObject(l.inputs.map(([k, v]) => [k, value(v)])) || '{}'],
+        options: [
+            ['connection', optional(l.connection)],
+            ['folder', optional(l.folder)],
+            ['object', optional(l.object)],
+        ],
+        ...(l.missing.length > 0
+            ? { comment: `TODO: bind ${l.missing.join(' and ')}; compile refuses this node until it has both labels (BINDING_MISSING)` }
+            : {}),
+    };
+}
+const connector10 = {
+    kind: 'connector', typeName: `${CONNECTOR_PREFIX}*`, version: '1.0.0', factory: 'connector',
+    definition: 'per-tenant',
+    // The library's definition answers, in serialize and, given a library, in check
+    // (checkDefinition). Without one check assumes the port every operation the
+    // library serves declares.
+    errorPort: (_spec, definition) => definition === undefined || definitionHasErrorPort(definition),
+    checkDefinition: (spec, options) => {
+        const def = options.connectorDefinition?.(spec.key, spec.action, spec.version, spec.object);
+        // Named as serialize places it: under the operation the author named.
+        return def !== null && typeof def === 'object' ? { ...def, nodeType: `${CONNECTOR_PREFIX}${spec.key}.${spec.action}` } : undefined;
+    },
+    serialize: (spec, ctx) => serializeConnector(spec, ctx),
+    deserialize: (node, ctx) => liftConnector(node, ctx),
+    print: (spec, ctx) => printConnector(spec, ctx),
+    check: (spec, ctx) => ctx.connector(spec),
+    // Every Expr in the inputs, nested ones included, resolves against the flow's names.
+    expressions: (spec) => [{ value: spec.inputs }],
+    output: () => ({ kind: 'opaque' }),
+    listShape: (spec, options) => options.listEnvelope?.(spec.key, spec.action, spec.version, spec.object),
+};
+export const connectorNodeType = {
+    kind: 'connector', typeName: `${CONNECTOR_PREFIX}*`, typeNamePrefix: CONNECTOR_PREFIX, factory: 'connector',
+    typeNameMatches: (typeName) => splitOperation(typeName) !== undefined,
+    versionedByDefinition: true,
+    defaultVersion: connector10.version,
+    versions: { [connector10.version]: connector10 },
+};

package/dist/serialize.d.ts

@@ -3,7 +3,7 @@ import type { BuiltFlow } from './flow-sdk.js';
 import type { Library } from './library.js';
 import { type BindingRefusalCode } from './core/binding-messages.js';
 import type { Bindings } from './bindings.js';
-import { connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
+import { CONNECTOR_INPUT_MISSING, connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — Flow's binding of the shared validator.
@@ -23,8 +23,7 @@ export interface SerializeWarning {
     code: string;
     message: string;
 }
-/** A required connector input left empty — the one draft code with no error class of its own. */
-export declare const CONNECTOR_INPUT_MISSING = "CONNECTOR_INPUT_MISSING";
+export { CONNECTOR_INPUT_MISSING } from './core/connector-inputs.js';
 /** The refusals a draft-tolerant compile reports instead of throwing. */
 export type DraftCode = BindingRefusalCode | typeof CONNECTOR_INPUT_MISSING | 'CONNECTOR_OBJECT_REQUIRED';
 /** A refusal a draft-tolerant compile reported instead of throwing (see {@link SerializeOpts.draft}). */

package/dist/serialize.js

@@ -18,8 +18,6 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
 import { resolveVersionCarried } from './core/nodes/versioned.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
-import { ConnectorResolveError } from './core/connector-resolve-error.js';
-import { synthesizedDefinitionRefusal } from './core/synthesized-definition.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
 import { ByoaRefusal, byoaUnverified } from './core/byoa.js';
@@ -30,11 +28,10 @@ import { placeholderPosition } from './node-placement.js';
 import { hasExits } from './core/step-ports.js';
 import { stopsAtEnd } from './flow-step-tree.js';
 import { assertNodeEnvelope } from './core/node-envelope.js';
-import { buildConfiguration } from './core/connector-configuration.js';
 import { fnv1aX4Uuid, stableId } from './core/stable-id.js';
 import { readEventFilter, eventFilterProblem, eventFilterJmes, eventFilterTreeLeaf, jmesString, jmesStringProblem } from './core/event-filters.js';
 import { FLOW_EXPR_DIALECT } from './core/connector-checks.js';
-import { buildConnectorInputs, connectorInputErrors as coreConnectorInputErrors, transportHttpMethod } from './core/connector-inputs.js';
+import { connectorInputErrors as coreConnectorInputErrors } from './core/connector-inputs.js';
 /**
  * What `compile` would refuse these connector inputs with, or `undefined` when it
  * would accept them — Flow's binding of the shared validator.
@@ -118,48 +115,6 @@ const SUBFLOW_OUTPUT = {
     source: '=result.response',
     var: 'output',
 };
-/** The inline (autonomous) agent's node type — fixed, not per-instance. */
-/**
- * Declare a LIST operation's output as the ARRAY it is, when the ledger has
- * MEASURED that it is one ([#203](https://github.com/UiPath/flow-builder-sdk/issues/203)).
- *
- * Every connector definition declares `outputs.output.type: 'object'` — list
- * operations included, and **0 of 544 deployed connector nodes declare `array`
- * anywhere** (card CLEANUP's corpus scan). For most of the library that is the
- * honest thing to emit, because the SDK does not know better. For an operation in
- * the list-envelope ledger it does:
- *
- *   · `envelope: null` (a measured BARE array) ⇒ **`type: 'array'`**;
- *   · a measured WRAPPER ⇒ `object`, unchanged — the value IS an object then;
- *   · UNDECLARED ⇒ untouched, which is #202's status quo.
- *
- * Why this matters beyond tidiness: `typeAgentInputSchemas` builds an agent's
- * pydantic input model from these declarations, and card ga7's scored run r2 died
- * at `AGENT_STARTUP.INPUT_VALIDATION_ERROR` because a Data Service list node said
- * `object` and the runtime sent 8 rows. #202 made that property TYPELESS, which
- * unblocked the agent without asserting anything; this says the true thing.
- *
- * ## And deliberately NO item schema
- *
- * #203 suggested emitting the item fields alongside. They are not emitted, and the
- * reason is a measurement rather than caution: a list operation's declared fields
- * are **neither a superset nor a subset** of the real response (card LT, three live
- * responses — ServiceNow `incident` declares 0 of the 103 fields it returns; Entra
- * declares 20, returns 15, misses 2; Jira declares 253, returns 116, misses 42).
- * Asserting them into an agent's pydantic model would reject real rows — the exact
- * fault class above, moved rather than fixed. The library lift stays a READ-checking
- * aid, where it fails open by design (lesson 26). The emitted bytes claim only what
- * is certain: this is an array.
- */
-function declareListOutputType(node, rc) {
-    const declared = rc.listEnvelope;
-    if (!declared || declared.envelope !== null)
-        return;
-    const out = node.outputs?.output;
-    if (!out || typeof out !== 'object' || out.type !== 'object')
-        return;
-    out.type = 'array';
-}
 /**
  * Read a connector definition's connection requirements without collapsing
  * three distinct states:
@@ -315,8 +270,7 @@ function scheduleInputs(inputs, nodeId) {
         ...(isPreset ? {} : { timerValue: every }),
     };
 }
-/** A required connector input left empty — the one draft code with no error class of its own. */
-export const CONNECTOR_INPUT_MISSING = 'CONNECTOR_INPUT_MISSING';
+export { CONNECTOR_INPUT_MISSING } from './core/connector-inputs.js';
 /**
  * `serialize`, plus the extra files the flow needs on disk beside it.
  *
@@ -2346,6 +2300,14 @@ export function serialize(built, opts = {}) {
         if (impl.errorEnvelope)
             scope.rename.errorEnvelopes.set(step.name, impl.errorEnvelope);
         const rendered = new WeakSet();
+        // A rendered value's JSON copy, marked as the file's: placement writes it as
+        // is instead of rendering it again. Both renderers below go through it.
+        const fileCopy = (out) => {
+            const copy = jsonClone(out);
+            if (copy !== null && typeof copy === 'object')
+                rendered.add(copy);
+            return copy;
+        };
         const ctx = {
             step: step.name,
             nodeId: id,
@@ -2357,13 +2319,7 @@ export function serialize(built, opts = {}) {
                 // Only a `lit` unwraps to a new value. Its JSON copy is the file's: a
                 // copy, so an object the author also passes outside the `lit` is not
                 // mistaken for this one and still has its expressions rendered.
-                if (out !== value && out !== null && typeof out === 'object') {
-                    const copy = JSON.parse(JSON.stringify(out));
-                    if (copy !== null && typeof copy === 'object')
-                        rendered.add(copy);
-                    return copy;
-                }
-                return out;
+                return out !== value && out !== null && typeof out === 'object' ? fileCopy(out) : out;
             },
             renameRefs: (js) => renameRefs(js, scope.rename),
             stepNodeId: (name) => scope.stepNodeId.get(name) ?? name,
@@ -2397,9 +2353,34 @@ export function serialize(built, opts = {}) {
             resourceNodeId: (explicit, seed, at) => resourceNodeId(scope, explicit, seed, at),
             emitted: (typeName, v) => emittedDefs.get(`${typeName}@${v}`),
             library: opts.library,
+            // Rendered once: placement renders the contribution's inputs again, so the
+            // result is marked as the file's, as `render` marks a `lit`'s copy. A copy,
+            // so an author object the walk returned as is (a `lit`'s own) stays unmarked
+            // where it is also used outside the `lit`.
+            renderDeep: (value) => {
+                const out = renderDeep(value, scope.rename, rendered);
+                return out !== null && typeof out === 'object' ? fileCopy(out) : out;
+            },
+            drafting: opts.draft !== undefined,
+            draft: (code, message) => opts.draft?.({ nodeId: id, code: code, message }),
         };
         const bound = [];
         const contribution = impl.serialize(spec, ctx);
+        if (contribution.standIn !== undefined) {
+            // A draft stand-in: the node as the draft has it, with no definition to
+            // place it against (see FlowNodeContribution.standIn).
+            if (!ctx.drafting)
+                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName} returned a draft stand-in outside a draft compile.`);
+            const { type, typeVersion, inputs } = contribution.standIn;
+            scope.nodes.push({
+                id, type, typeVersion,
+                ...(parentId ? { parentId } : {}), display: { label: step.name },
+                inputs: { ...inputs },
+            });
+            for (const t of tails)
+                addEdge(scope, t, id);
+            return [{ node: id, port: contribution.port ?? 'output' }];
+        }
         // The definition contract, both halves: a per-tenant type supplies its
         // definition, and a bundled type does not (its definition is the bundle's, and
         // makeNode records it, so the error-edge refusal and check ask the same one).
@@ -2414,7 +2395,9 @@ export function serialize(built, opts = {}) {
         // instance's edits (a queue step's own resourceKey, for instance). Only a type
         // that supplies none at a carried version takes the carried definition as is.
         if (contribution.definition !== undefined) {
-            def = resolveContributionDefinition(contribution.definition, version, where);
+            // A type whose definition names its version is held to the author's pin by
+            // makeNode, with the message every definition's mismatch gets.
+            def = resolveContributionDefinition(contribution.definition, entry.type.versionedByDefinition ? undefined : version, where);
         }
         else if (impl.definition === 'per-tenant' && resolved.carried === undefined) {
             throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${version} returned no definition.`);
@@ -2436,14 +2419,14 @@ export function serialize(built, opts = {}) {
             // tenant definition (an inline agent at 1.1) may have no error handle.
             const port = resolved.carried !== undefined
                 ? definitionHasErrorPort(def ?? resolved.carried)
-                : typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
+                : typeof impl.errorPort === 'function' ? impl.errorPort(spec, def) : impl.errorPort === true;
             // The declaration answers for check, which has no definition; here the
             // definition is in hand, and the two must agree (#1011).
             if (port && def !== undefined && !definitionHasErrorPort(def)) {
                 throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} declares an error port, `
                     + 'but the definition it supplied has no error handle and no supportsErrorHandling.');
             }
-            declaredErrorPorts.set(id, { port, typeName: nodeType, version });
+            declaredErrorPorts.set(id, { port, typeName: nodeType, version: def?.version ?? version });
         }
         // A forward port is a handle the definition declares, one of the type's
         // author-named exits, or one the product derives (`derivesPort`: a human
@@ -2462,7 +2445,11 @@ export function serialize(built, opts = {}) {
         if (resolved.carried !== undefined)
             bundledNodeDefs.set(id, def ?? resolved.carried);
         return placeStepNode({
-            where, stepName: step.name, id, typeName: nodeType, requestedVersion: version, def, contribution, bound, tails, scope, parentId,
+            where, stepName: step.name, id, typeName: nodeType,
+            // A type whose definition names its version is placed at that version,
+            // held to the author's pin, as makeNode holds any definition to one.
+            requestedVersion: entry.type.versionedByDefinition ? step.options?.version : version,
+            def, contribution, bound, tails, scope, parentId,
             trackOutcomes: true,
             rendered,
         });
@@ -2501,129 +2488,6 @@ export function serialize(built, opts = {}) {
             subflows[id] = emitSubflowBody(spec.child, id);
             return [{ node: id, port: successPort(NODE_TYPE.subflow) }];
         }
-        if (spec.kind === 'connector') {
-            if (!opts.library)
-                throw new Error(`connector "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);
-            let rc;
-            try {
-                rc = opts.library.resolve(spec.key, spec.action, spec.version, spec.object);
-            }
-            catch (error) {
-                if (!opts.draft || !(error instanceof ConnectorResolveError) || error.code !== 'CONNECTOR_OBJECT_REQUIRED')
-                    throw error;
-                // A generic operation saved before its object was picked has no
-                // definition to emit against. Draft tolerance emits a stable stand-in
-                // under the node's id; merge restores the original when it is untouched
-                // and refuses it otherwise.
-                const id = stepUid(scope, step.name);
-                opts.draft({ nodeId: id, code: error.code, message: error.message });
-                // It leaves on the port every connector action leaves on, so the
-                // no-edit round trip rewires nothing. Its inputs carry what the author
-                // wrote, so an edit to the node (an input, a connection) shows up as a
-                // change and merge refuses it instead of restoring the original.
-                const type = `uipath.connector.${spec.key}.${spec.action}`;
-                scope.nodes.push({
-                    id, type, typeVersion: spec.version ?? '1.0.0',
-                    ...(parentId ? { parentId } : {}), display: { label: step.name },
-                    inputs: {
-                        draft: true,
-                        spec: renderDeep(spec.inputs ?? {}, scope.rename),
-                        ...(spec.connection !== undefined ? { connection: spec.connection } : {}),
-                        ...(spec.folder !== undefined ? { folder: spec.folder } : {}),
-                    },
-                });
-                for (const t of tails)
-                    addEdge(scope, t, id);
-                return [{ node: id, port: successPort(type) }];
-            }
-            // An entry `prepare` synthesized from Integration Service compiles in BPMN only.
-            const noDefinition = synthesizedDefinitionRefusal(rc);
-            if (noDefinition)
-                throw noDefinition;
-            const id = stepUid(scope, step.name);
-            const node = makeNode(rc.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def: rc.v1def });
-            declareListOutputType(node, rc);
-            // A draft that names no connection gets no binding rows either: there
-            // is nothing to bind, and rows with an empty resourceKey would leak into
-            // the merged file through merge's bindings union.
-            let unbound = false;
-            try {
-                requireBindingPair(`connector "${step.name}"`, spec, { key: spec.key, action: spec.action });
-            }
-            catch (error) {
-                if (!opts.draft || !(error instanceof BindingRefusal))
-                    throw error;
-                opts.draft({ nodeId: id, code: error.code, message: error.message });
-                unbound = true;
-            }
-            const conn = resolveBinding(opts, spec.connection, 'connection', `connector "${step.name}"`, { key: spec.key, action: spec.action });
-            const folder = resolveBinding(opts, spec.folder, 'folder', `connector "${step.name}"`, { key: spec.key, action: spec.action });
-            // The platform reaches the connection through the flow's `bindings[]`,
-            // never through `inputs.detail` — without this pair the run faults with
-            // `[102010]` (board G-19; see connectionResourceBindings).
-            const { entries: connBindings } = connectionResourceBindings({ def: rc.v1def, connectorKey: rc.connectorKey, connectionId: conn, folderKey: folder }, resourceBindings);
-            if (!unbound)
-                for (const b of connBindings)
-                    resourceBindings.set(b.id, b);
-            const connectorInputs = buildConnectorInputs(rc, spec.inputs, {
-                ...(opts.draft
-                    ? { onMissingRequired: (m) => opts.draft({ nodeId: id, code: CONNECTOR_INPUT_MISSING, message: `connector ${rc.nodeType}: ${m}` }) }
-                    : {}),
-                dialect: FLOW_EXPR_DIALECT,
-                render: (value) => renderDeep(value, scope.rename),
-                resolutions: opts.library.lookupResolutions ?? {},
-                // Only for the missing-required hint; a test double that is not a full
-                // Library simply gets the plain message.
-                lookups: typeof opts.library.lookupSpecs === 'function'
-                    ? opts.library.lookupSpecs(spec.key, spec.action, spec.version, spec.object)
-                    : {},
-            });
-            const replayInputs = {
-                ...(connectorInputs.bodyParameters ?? {}),
-                ...(connectorInputs.pathParameters ?? {}),
-                ...(connectorInputs.queryParameters ?? {}),
-            };
-            const detail = {
-                connector: rc.connectorKey,
-                method: transportHttpMethod(rc.httpMethod),
-                endpoint: rc.endpoint,
-                // The op's object identity, as a SIBLING of the copy inside
-                // `configuration` — the designer emits both, and every connector node in
-                // a product-exported flow carries it (`curated_create_issue`,
-                // `Company__c`, `send_message_to_channel_v2` on the reference export).
-                // The event path already did; this action path had dropped it.
-                // Conditional because the library defaults a missing
-                // `operation.objectName` to '' — an op that names no object gets no key,
-                // not an empty one.
-                ...(rc.objectName ? { objectName: rc.objectName } : {}),
-                inputMetadata: {},
-                errorState: { hasError: false },
-                telemetryData: { connectorKey: rc.connectorKey, connectorName: rc.connectorName },
-                configuration: buildConfiguration(rc.entry, rc.version, replayInputs, id),
-                ...(rc.activityTypeId ? { uiPathActivityTypeId: rc.activityTypeId } : {}),
-                ...(conn ? { connectionId: conn, connectionResourceId: conn } : {}),
-                ...(folder ? { connectionFolderKey: folder } : {}),
-            };
-            // Validate activity inputs against the connector's field list and place
-            // each one in the slot its LOCATION names — body → detail.bodyParameters,
-            // query → detail.queryParameters, path → detail.pathParameters, multipart
-            // → detail.multipartParameters (where the runtime looks) — so
-            // a schema-valid-but-contract-wrong connector node fails at compile with
-            // an actionable message instead of silently at run time.
-            //
-            // `bodyParameters` is emitted unconditionally, as it always has been (3 of
-            // 1,283 deployed connector nodes carry an empty one, so it is a legal
-            // shape); the other three appear only when the op has inputs there, which
-            // is the platform's dominant convention — of those 1,283 nodes, 899 omit
-            // `pathParameters` entirely and NONE carries an empty one. That also keeps
-            // every body-only connector's emission byte-identical to before.
-            Object.assign(detail, connectorInputs);
-            node.inputs = { detail };
-            scope.nodes.push(node);
-            for (const t of tails)
-                addEdge(scope, t, id);
-            return [{ node: id, port: successPort(rc.nodeType) }];
-        }
         if (spec.kind === 'waitEvent') {
             if (!opts.library)
                 throw new Error(`waitForEvent "${step.name}" needs a library (pass --library / set $FLOW_SDK_LIBRARY_JSON).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.49.2",
+  "version": "6.50.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "72292af393e64e04ffe0ce42e31992e3ea9a3980"
+  "gitref": "d674fc1a9ed1b8aa61dcc0b30a95a434503eb61b"
 }