@uipath/maestro-builder-sdk 6.8.0 → 6.8.2

package/dist/check.js

@@ -1250,7 +1250,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
             const declared = specs?.[named];
             const by = value.__lookup.by;
             if (declared && typeof by === 'string' && !declared.by.includes(by)) {
-                const { target, call } = lookupPhrases(named, declared);
+                const { target, call } = lookupPhrases(named, declared, spec);
                 diags.push({
                     level: 'error',
                     code: 'LOOKUP_UNKNOWN_MATCH_KEY',
@@ -1302,7 +1302,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
-        const { target, call } = lookupPhrases(field, lookup);
+        const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
             code: 'LOOKUP_LITERAL_ID',
@@ -1439,13 +1439,32 @@ function checkConnectorContract(step, spec, opts, diags) {
         }
     }
 }
-/** The two phrases every lookup diagnostic needs: what the field sends, and how to resolve it. */
-function lookupPhrases(field, lookup) {
+/**
+ * The two phrases every lookup diagnostic needs: what the field sends, and how
+ * to resolve it.
+ *
+ * The `call` names BOTH authoring forms, and names which one the alias belongs
+ * to. Printing `lookup(<Descriptor>, 'entityName').byDisplayName('<value>')`
+ * alone — the old text — was a remedy with an unstated precondition: aliases
+ * are generated onto the descriptor, and `<Descriptor>` is a placeholder the
+ * reader has to fill from somewhere. An author holding the connector key and
+ * action instead (the form the library's Generic CRUD half is authored in, and
+ * the majority of its lookup fields) substitutes those for the placeholder,
+ * keeps the alias, and gets `lookup(...).byDisplayName is not a function`. Six
+ * flow-eval tasks did precisely that, each losing a check-edit-check round to
+ * a message that had told them to.
+ */
+function lookupPhrases(field, lookup, spec) {
     const target = `${lookup.objectName ?? lookup.path}.${lookup.value}`;
+    const by = lookup.by[0] ?? 'id';
     const alias = Object.keys(lookup.aliases)[0];
+    // The key/action form first: it needs no import, so it is the one line that
+    // is paste-ready from the message alone.
+    const generic = `lookup('${spec.key}', '${spec.action}', '${field}').by('${by}', '<value>')`;
     const call = alias
-        ? `lookup(<Descriptor>, '${field}').${alias}('<value>')`
-        : `lookup(<Descriptor>, '${field}').by('${lookup.by[0] ?? 'id'}', '<value>')`;
+        ? `${generic}\n  or \`lookup(D, '${field}').${alias}('<value>')\`, where D is the `
+            + `descriptor \`${prepareCommand(spec.key, spec.action)}\` generates — the aliases exist only there`
+        : generic;
     return { target, call };
 }
 /**
@@ -1502,7 +1521,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         || leaf.toLowerCase() === valueLeaf.toLowerCase()
         || (valueIsEmail && EMAIL_LEAF.test(leaf))))
         return undefined;
-    const { target, call } = lookupPhrases(field, lookup);
+    const { target, call } = lookupPhrases(field, lookup, spec);
     const searchesByEmail = lookup.by.some((b) => EMAIL_LEAF.test(b));
     const isEmail = !!leaf && EMAIL_LEAF.test(leaf) && !valueIsEmail && !searchesByEmail;
     const message = `Connector step "${step}": \`${field}\` is a lookup field bound to the runtime expression `

package/dist/core/lookups.js

@@ -46,7 +46,53 @@ export function isLookupToken(v) {
 export function lookupKey(nodeType, field, by, value) {
     return JSON.stringify([nodeType, field, by, value]);
 }
-function makeBuilder(nodeType, field, spec) {
+/**
+ * An alias-shaped property: `byEmail`, `byDisplayName`, `byAccountId`.
+ *
+ * Narrow on purpose. The builder is handed to whatever inspects it next —
+ * `util.inspect`, a `then` probe on an accidental `await`, a spread — and a
+ * trap that answered for EVERY absent name would turn those into throws. Only
+ * a name the author could have meant as an alias is intercepted.
+ */
+const ALIAS_SHAPE = /^by[A-Z]/;
+/**
+ * Why `.byDisplayName()` is absent, in the terms of the form that was used.
+ *
+ * Aliases are generated from the descriptor's own `lookups` table, so the
+ * string form — which has no table to read — offers only `.by(name, value)`.
+ * That is a deliberate trade (see the overload's `@remarks`), but the author
+ * who trips it learns it as `lookup(...).byDisplayName is not a function`: a
+ * bare `TypeError` naming neither the field, the form, nor the way out. Six
+ * flow-eval tasks lost turns to exactly that message, every one of them having
+ * copied an alias out of a diagnostic or a descriptor's doc comment and pasted
+ * it onto the key/action form they happened to be holding.
+ */
+function missingAliasMessage(nodeType, field, alias, spec, generic) {
+    const head = `lookup(${nodeType}, '${field}'): \`.${alias}()\` does not exist. `;
+    if (!spec) {
+        // The remedy names the author's OWN key and action rather than a
+        // placeholder: a remedy with a hole in it is what produced this call.
+        const here = generic
+            ? `lookup('${generic.key}', '${generic.action}', '${field}')`
+            : `lookup(…, '${field}')`;
+        return head
+            + `Aliases are generated onto the descriptor, and this call has no descriptor `
+            + `to read them from, so only \`.by(name, value)\` exists here. Search by name:\n`
+            + `  ${here}.by('<searchable name>', <value>)\n`
+            + `\`check\` and \`${prepareCommand()}\` both print the names this field is `
+            + `searchable by. Or import the descriptor `
+            + (generic ? `\`${prepareCommand(generic.key, generic.action)}\` generates ` : '')
+            + `and call \`.${alias}(<value>)\` on that.`;
+    }
+    const aliases = Object.keys(spec.aliases);
+    return head
+        + (aliases.length
+            ? `Generated aliases for this field: ${aliases.map((a) => `\`.${a}()\``).join(', ')}. `
+            : `This field earns no alias — two of its names camelise to one, so both were dropped. `)
+        + `Every searchable name is reachable as `
+        + `\`.by(${spec.by.map((b) => `'${b}'`).join(' | ')}, <value>)\`.`;
+}
+function makeBuilder(nodeType, field, spec, generic) {
     const token = (by, value) => ({ __lookup: { nodeType, field, by, value } });
     const builder = {
         by(name, value) {
@@ -63,7 +109,19 @@ function makeBuilder(nodeType, field, spec) {
     for (const [alias, byName] of Object.entries(spec?.aliases ?? {})) {
         builder[alias] = (value) => token(byName, value);
     }
-    return builder;
+    // The throw is deferred to the CALL rather than raised on the property read,
+    // so the stack points at `.byDisplayName('Inbox')` — the line the author
+    // wrote — instead of at the property access the engine desugared it into.
+    return new Proxy(builder, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && !(prop in target) && ALIAS_SHAPE.test(prop)) {
+                return () => {
+                    throw new Error(missingAliasMessage(nodeType, field, prop, spec, generic));
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
 }
 export function lookup(a, b, c) {
     if (typeof a === 'string') {
@@ -71,7 +129,7 @@ export function lookup(a, b, c) {
             throw new Error("lookup(key, action, field) needs all three arguments; " +
                 "did you mean lookup(descriptor, field)?");
         }
-        return makeBuilder(`uipath.connector.${a}.${b}`, c);
+        return makeBuilder(`uipath.connector.${a}.${b}`, c, undefined, { key: a, action: b });
     }
     if (!('nodeType' in a) || a.nodeType === undefined) {
         const event = a;

package/dist/decompile.js

@@ -1247,7 +1247,11 @@ function emitAgentCluster(node, imp, inputNames, graph) {
     if (node.type === T.conversationalAgent) {
         const st = (i.conversationalAgentSettings ?? {});
         const settingExpr = (k) => {
-            const raw = typeof st[k] === 'string' ? st[k] : undefined;
+            // `unwrapSource` rather than a string test: since the envelope reaches
+            // these five keys (migrate's `NESTED_BINDING_INPUTS`), a bare string is
+            // only what a pre-1.6 file carries. Reading strings alone made every
+            // modern file decompile to a conversational agent with no turn wiring.
+            const raw = unwrapSource(st[k]);
             if (raw === undefined || raw === '')
                 return undefined;
             const js = raw.startsWith('=js:') ? raw.slice(4) : raw;

package/dist/migrate.js

@@ -48,6 +48,82 @@ function isUnwrappedInput(nodeType, key) {
         return false;
     return UNWRAPPED_INPUTS.some((r) => nodeType.startsWith(r.typePrefix) && r.keys.has(key));
 }
+/**
+ * Inputs whose value is an OBJECT of bindings, wrapped one level down.
+ *
+ * `wrapNodes` walks `n.inputs` one level and skips anything that is not a
+ * string, so a sub-object of bindings is never reached. For almost every input
+ * that is correct — a connector's `entityConfig` is a payload, not a binding
+ * table, and wrapping its leaves would corrupt it. `conversationalAgentSettings`
+ * is the exception: its five keys are per-turn BINDINGS, and the platform's own
+ * writer envelopes each one.
+ *
+ * **`uipath.agent.conversational` → `conversationalAgentSettings`** (measured
+ * 2026-09-23 against the same-ground A/B run):
+ *
+ *   - Every binding written by the PRODUCT carries the envelope: 5 of 5 across
+ *     the v1 arm's `conversationalAgentSettings`, each a
+ *     `{ type: 'jsExpression', expression, fieldType }`. Every binding written
+ *     by this SDK is a bare `=js:` string: 5 of 5 in the v2 arm. No mixed case
+ *     anywhere in the corpus.
+ *   - The bare string is the pre-1.3 spelling, and Studio Web renders it as
+ *     literal text rather than evaluating it — so the flow deploys, validates
+ *     `Valid`, and shows the author the text `$vars.listen.output…` where the
+ *     transcript should be.
+ *   - `uip maestro flow validate` accepts both, which is why this survived: the
+ *     SDK's own `check`, `compile` and the product's static validator all passed
+ *     on the broken shape. `skill-flow-conversational-chat-loop` scored 0.61
+ *     with a green ladder.
+ *
+ * The `fieldType`s are a table rather than a schema read because the node's own
+ * manifest declares `conversationalAgentSettings` as an untyped `object`
+ * (`uipath.agent.conversational@1.6` and `@1.7`, `inputDefinition.properties`),
+ * so there is nothing underneath it to read. They are the types the product
+ * writes, from the same measurement.
+ *
+ * `mode` is deliberately absent: it is an editor-state enum (`'simple'` /
+ * `'custom'`), not a binding, and the product leaves it a plain string.
+ */
+const NESTED_BINDING_INPUTS = [
+    {
+        typePrefix: 'uipath.agent.conversational',
+        key: 'conversationalAgentSettings',
+        fieldTypes: {
+            context: 'object',
+            conversationId: 'string',
+            exchangeId: 'string',
+            messages: 'array',
+            userSettings: 'object',
+        },
+    },
+];
+/**
+ * Wrap the binding leaves of an object-valued input, in place.
+ *
+ * Only the keys the table names are touched. An unknown key is left exactly as
+ * it is: the table is evidence about specific fields, and a key nobody measured
+ * is not covered by it.
+ */
+function wrapNestedBindings(node) {
+    if (typeof node.type !== 'string')
+        return;
+    for (const rule of NESTED_BINDING_INPUTS) {
+        if (!node.type.startsWith(rule.typePrefix))
+            continue;
+        const settings = node.inputs?.[rule.key];
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+            continue;
+        for (const [key, fieldType] of Object.entries(rule.fieldTypes)) {
+            const v = settings[key];
+            if (typeof v !== 'string' || isWrappedSource(v))
+                continue;
+            // The same rule the top-level loop applies: an expression always, and a
+            // literal whenever the field is not string-typed.
+            if (v.startsWith('=') || fieldType !== 'string')
+                settings[key] = wrap(v, fieldType);
+        }
+    }
+}
 /**
  * The only `fieldType` values `@uipath/flow-schema`'s `expressionValueSchema`
  * accepts (it is `.strict()`, so anything else fails the file's schema and with
@@ -155,6 +231,7 @@ function wrapNodes(nodes, schemaByType, globalTypeByName, subflows = {}) {
                 if (v.startsWith('=') || declared !== 'string')
                     n.inputs[k] = wrap(v, declared);
             }
+            wrapNestedBindings(n);
         }
         if (n.outputs) {
             for (const [k, vobj] of Object.entries(n.outputs)) {

package/dist/serialize.js

@@ -1628,7 +1628,17 @@ function conversationalAgentJson(spec) {
             // agent's — a debug run without both is refused before it starts.
             maxTokens: spec.maxTokenPerResponse ?? 16384,
             temperature: spec.temperature ?? 0,
-            engine: 'basic-v2',
+            // `basic-v2` is the NON-conversational inline agent's engine (the other
+            // `agent.json` writer in this file, 100 lines down), and it was copied in
+            // with the rest of that shape. Every instance of THIS node is
+            // conversational — `metadata.isConversational` below says so
+            // unconditionally — and `voiceAgentJson`, the sibling conversational
+            // family, already spells it the other way. Measured across the 2026-09-23
+            // A/B run: every product-written `agent.json` with `isConversational: true`
+            // carries `conversational-v1` (3 of 3) and every one with `false` carries
+            // `basic-v2` (6 of 6). The SDK's own voice path agreed (2 of 2); only this
+            // path disagreed, and its task graded the sidecar as not conversational.
+            engine: 'conversational-v1',
             ...(spec.maxIterations === undefined ? {} : { maxIterations: spec.maxIterations }),
             mode: 'standard',
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.0",
+  "version": "6.8.2",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "de2812e18734552a112d97deec05fc9ae2244caa"
+  "gitref": "34be5c196660ad049240339a969f508f67898e19"
 }