@uipath/maestro-builder-sdk 6.32.8 → 6.33.1

package/dist/decompile.js

@@ -38,6 +38,7 @@ import { commentText } from './core/comment-text.js';
 import { tsLiteral, tsNumber, tsText } from './core/ts-literal.js';
 import { ownEntry } from './core/own-entry.js';
 import { CONTEXT_INDEX_DEFAULTS, CONTEXT_INDEX_DEFAULT_FILE_EXTENSION, contextIndexSlug, parseContextIndexType, } from './core/context-index.js';
+import { derivedContextSource, derivedEscalationSource, derivedResourceNodeId, derivedToolSource, } from './core/agent-resource-identity.js';
 import { wireExprBody } from './core/wire-expr.js';
 import { hasExits } from './core/step-ports.js';
 import { parseIxpProjectType } from './core/actions.js';
@@ -107,6 +108,12 @@ let runWarned = new Set();
  * `.layout()` key, must use the id compile will produce, not the file's.
  */
 let runAbsorbed = new Map();
+/**
+ * The id the recompiled flow will have: the `flow(...)` argument decompile
+ * writes. Compile derives a resource's directory from it, so decompile needs it
+ * to tell a derived directory from one the file chose.
+ */
+let runFlowId = 'flow';
 /** `DecompileOptions.readSidecar` for the current run. */
 let runReadSidecar;
 function warnOnce(message) {
@@ -1160,20 +1167,45 @@ function emitAgentCluster(node, imp, inputNames, graph) {
     // spec order is this edge order: the first is `<agent><Kind>`, the n-th
     // `<agent><Kind><n>` (claimId's dedupe). Only the first memory is recovered,
     // so every further memory maps to `undefined`.
+    //
+    // When a port's nodes do not ALL carry those ids (the canvas or the CLI named
+    // them), every resource on the port is written with its own `nodeId`, and
+    // compile keeps the file's ids. All of them, not only the odd one: compile
+    // numbers the derived ids in order, so a derived id after an explicit one
+    // would come out one lower than the file's.
     // This reads the edges directly, not through `resource()`: it must see EVERY
     // artifact edge, including ones the spec does not carry, and it must not
     // account for any edge.
+    const keepIds = new Set();
     for (const [port, kind, emittedCount] of [
         ['context', 'Context', Infinity], ['tool', 'Tool', Infinity],
         ['escalation', 'Escalation', Infinity], ['memory', 'Memory', 1],
     ]) {
-        const base = `${node.id}${kind}`.replace(/[^A-Za-z0-9_]/g, '_');
-        (graph?.outEdges(node.id) ?? [])
+        const targets = (graph?.outEdges(node.id) ?? [])
             .filter((e) => e.sourcePort === port && graph.byId.has(e.targetNodeId))
-            .forEach((e, k) => {
-            runAbsorbed.set(e.targetNodeId, k >= emittedCount ? undefined : k === 0 ? base : `${base}${k + 1}`);
+            .map((e) => e.targetNodeId);
+        const keep = port !== 'memory'
+            && targets.some((id, k) => id !== derivedResourceNodeId(node.id, kind, k));
+        targets.forEach((id, k) => {
+            if (keep)
+                keepIds.add(id);
+            runAbsorbed.set(id, keep ? id : k >= emittedCount ? undefined : derivedResourceNodeId(node.id, kind, k));
         });
     }
+    /**
+     * The `nodeId` / `source` entries for resource node `r`: each only when it
+     * differs from what compile derives (`derivedSource`), so a flow compile
+     * wrote decompiles without them.
+     */
+    const placement = (r, derivedSource) => {
+        const source = unwrapSource((r.inputs ?? {}).source);
+        return [
+            ['nodeId', keepIds.has(r.id) ? tsLiteral(r.id) : undefined],
+            ['source', source !== undefined && source !== '' && source !== derivedSource ? tsLiteral(source) : undefined],
+        ];
+    };
+    /** A tool's options plus its placement; `seed` is the ref compile derives the tool's directory from. */
+    const toolOpts = (t, seed, entries) => opts([...entries, ...placement(t, derivedToolSource(runFlowId, node.id, seed))]);
     const rInputs = (n) => (n.inputs ?? {});
     const rPlain = (n, k) => {
         const raw = unwrapSource(rInputs(n)[k]);
@@ -1189,7 +1221,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
                     return undefined;
                 return objLit(Object.entries(props).map(([k, x]) => [k, tsLiteral(String(x?.type ?? 'string'))]));
             };
-            return opts([
+            return toolOpts(t, { kind: 'clientside', name: rPlain(t, 'name') ?? '' }, [
                 ['kind', tsLiteral('clientside')],
                 ['name', tsLiteral(rPlain(t, 'name') ?? '')],
                 ['description', rPlain(t, 'description') !== undefined ? tsLiteral(rPlain(t, 'description')) : undefined],
@@ -1206,7 +1238,8 @@ function emitAgentCluster(node, imp, inputNames, graph) {
                 const v = row.textValue;
                 return typeof v === 'number' ? String(v) : typeof v === 'string' ? tsLiteral(v) : JSON.stringify(v);
             };
-            return opts([
+            // `name` is not recovered, so compile derives the directory from the default.
+            return toolOpts(t, { kind: 'httpRequest' }, [
                 ['kind', tsLiteral('httpRequest')],
                 ['url', fixed('url')], ['method', fixed('method')],
                 ['headers', fixed('headers')], ['params', fixed('params')],
@@ -1214,7 +1247,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ]);
         }
         if (type.startsWith('uipath.agent.resource.tool.mcp.')) {
-            return opts([
+            return toolOpts(t, { kind: 'mcp', name: '', key: rPlain(t, 'referenceKey') ?? '' }, [
                 ['kind', tsLiteral('mcp')],
                 ['name', tsLiteral(rPlain(t, 'name') ?? '')],
                 ['key', tsLiteral(rPlain(t, 'referenceKey') ?? '')],
@@ -1225,7 +1258,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ]);
         }
         if (type.startsWith('uipath.agent.resource.tool.a2a.')) {
-            return opts([
+            return toolOpts(t, { kind: 'a2a', name: '', slug: '', key: rPlain(t, 'referenceKey') ?? '' }, [
                 ['kind', tsLiteral('a2a')],
                 ['name', tsLiteral(rPlain(t, 'name') ?? '')],
                 ['key', tsLiteral(rPlain(t, 'referenceKey') ?? '')],
@@ -1234,17 +1267,19 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ]);
         }
         if (type.startsWith('uipath.agent.resource.tool.builtin.')) {
-            return opts([
+            const tool = type.slice('uipath.agent.resource.tool.builtin.'.length);
+            return toolOpts(t, { kind: 'builtin', tool }, [
                 ['kind', tsLiteral('builtin')],
-                ['tool', tsLiteral(type.slice('uipath.agent.resource.tool.builtin.'.length))],
+                ['tool', tsLiteral(tool)],
                 ['description', rPlain(t, 'description') !== undefined ? tsLiteral(rPlain(t, 'description')) : undefined],
             ]);
         }
         if (type.startsWith('uipath.agent.resource.tool.ixp.')) {
             const tail = type.slice('uipath.agent.resource.tool.ixp.'.length);
-            return opts([
+            const projectId = tail.slice(tail.indexOf('.') + 1);
+            return toolOpts(t, { kind: 'ixp', name: '', projectId }, [
                 ['kind', tsLiteral('ixp')],
-                ['projectId', tsLiteral(tail.slice(tail.indexOf('.') + 1))],
+                ['projectId', tsLiteral(projectId)],
                 ['name', tsLiteral(rPlain(t, 'name') ?? '')],
             ]);
         }
@@ -1266,9 +1301,10 @@ function emitAgentCluster(node, imp, inputNames, graph) {
                 const row = values.find((v) => v.name === n);
                 return typeof row?.default === 'string' ? row.default : undefined;
             };
-            return opts([
+            const key = type.slice(ns[0].length);
+            return toolOpts(t, { kind: 'process', name: '', folderPath: '', key }, [
                 ['kind', tsLiteral(ns[1])],
-                ['key', tsLiteral(type.slice(ns[0].length))],
+                ['key', tsLiteral(key)],
                 ['name', tsLiteral(bound('name') ?? rPlain(t, 'name') ?? '')],
                 ['folderPath', tsLiteral(bound('folderPath') ?? '')],
             ]);
@@ -1277,6 +1313,9 @@ function emitAgentCluster(node, imp, inputNames, graph) {
     });
     const contextSrc = resource('context').map((c) => {
         const { name, id, folderPath, sidecar } = contextIndexIdentity(node, c, rPlain);
+        // Compile labels the node with `name`; a canvas rename is kept as `label`.
+        const label = typeof c.display?.label === 'string' && c.display.label !== '' && c.display.label !== name
+            ? c.display.label : undefined;
         return opts([
             ['name', tsLiteral(name)],
             ['id', tsLiteral(id)],
@@ -1284,6 +1323,8 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ['folderKey', rPlain(c, 'folderKey') !== undefined ? tsLiteral(rPlain(c, 'folderKey')) : undefined],
             // `query` and the retrieval settings, from resource.json or the node (#1183).
             ...contextIndexSettings(node, c, sidecar),
+            ['label', label !== undefined ? tsLiteral(label) : undefined],
+            ...placement(c, derivedContextSource(runFlowId, node.id, id)),
         ]);
     });
     const escalationSrc = resource('escalation').map((e) => {
@@ -1323,6 +1364,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ['taskTitle', typeof extra.taskTitle === 'string' && extra.taskTitle !== '' ? tsLiteral(extra.taskTitle) : undefined],
             // 'medium' is the platform default.
             ['priority', typeof extra.priority === 'string' && extra.priority !== 'medium' ? tsLiteral(extra.priority) : undefined],
+            ...placement(e, derivedEscalationSource(runFlowId, node.id, rPlain(e, 'name') ?? '')),
         ]);
     });
     const mem = resource('memory', 1)[0];
@@ -3249,6 +3291,7 @@ export function decompile(flow, options = {}) {
     runDefs = new Map();
     runRawManifests = [];
     runAbsorbed = new Map();
+    runFlowId = slugId(flow);
     for (const d of (flow.definitions ?? [])) {
         if (typeof d?.nodeType !== 'string')
             continue;

package/dist/serialize.js

@@ -34,6 +34,7 @@ import { stopsAtEnd } from './flow-step-tree.js';
 import { assertNodeEnvelope } from './core/node-envelope.js';
 import { buildConfiguration } from './config.js';
 import { fnv1aX4Uuid, schemaId, stableId } from './core/stable-id.js';
+import { derivedContextSource, derivedEscalationSource, derivedToolSource, } from './core/agent-resource-identity.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, multipartBodyFieldName, transportHttpMethod } from './core/connector-inputs.js';
@@ -4398,6 +4399,26 @@ export function serialize(built, opts = {}) {
      * gets them and one that does not is unaffected.
      */
     const sidecars = opts.sidecars ?? [];
+    /** The sidecar paths a resource's explicit `source` chose. */
+    const explicitSidecars = new Set();
+    /**
+     * Add one sidecar file. A resource whose explicit `source` names a directory
+     * another resource also writes would have the second file silently replace
+     * the first: index A's node would read B's settings. That is refused; `check`
+     * reports it first (INLINE_AGENT_RESOURCE_SOURCE_DUP). The same file twice (a
+     * subflow body emitted for two callers) is not a clash.
+     */
+    const addSidecar = (file, explicitSource = false) => {
+        const earlier = sidecars.find((f) => f.path === file.path);
+        if (earlier !== undefined && JSON.stringify(earlier.json) !== JSON.stringify(file.json)
+            && (explicitSource || explicitSidecars.has(file.path))) {
+            throw Object.assign(new Error(`two resources would both write "${file.path}" with different content, so the second would replace the first. `
+                + 'Give each resource its own `source`, or omit `source` to derive one.'), { code: 'INLINE_AGENT_RESOURCE_SOURCE_DUP' });
+        }
+        if (explicitSource)
+            explicitSidecars.add(file.path);
+        sidecars.push(file);
+    };
     /**
      * An agent step's folder uuid (`source`): the one the step carries, else one
      * derived from the flow id + step name rather than random, so a recompile is
@@ -4566,6 +4587,24 @@ export function serialize(built, opts = {}) {
         }
         return prefix;
     }
+    /**
+     * The node id of an agent resource: the author's `nodeId` exactly as written
+     * (decompile writes the id the original file had, and a changed id is a
+     * dropped node plus an added one to merge), else `uid`'s derived one. A
+     * `nodeId` another node already holds is refused rather than renamed, for
+     * the same reason; check reports it first (INLINE_AGENT_RESOURCE_NODE_ID).
+     */
+    function resourceNodeId(scope, nodeId, derivedBase, where) {
+        if (nodeId === undefined)
+            return uid(scope, derivedBase);
+        if (nodeId.trim() === '' || takenIds.has(nodeId)) {
+            throw Object.assign(new Error(`${where}: \`nodeId\` ${JSON.stringify(nodeId)} `
+                + (nodeId.trim() === '' ? 'is blank.' : 'is already the id of another node in this flow.')
+                + ' Give the resource node an id no other node has, or omit `nodeId` to derive one.'), { code: 'INLINE_AGENT_RESOURCE_NODE_ID' });
+        }
+        takenIds.add(nodeId);
+        return nodeId;
+    }
     /**
      * The node id of an author's step: the one `claimStepIds` claimed for it,
      * recorded so `.stepToRef('<step>')` can find it.
@@ -5419,7 +5458,7 @@ export function serialize(built, opts = {}) {
                 source,
                 name: step.name,
             });
-            sidecars.push({ path: `${source}/agent.json`, json: agentJson });
+            addSidecar({ path: `${source}/agent.json`, json: agentJson });
             // The schema's property TYPES need this scope's finished variables, which
             // do not exist yet — park them (the `properties` object is filled in
             // place when the scope closes). See `typeAgentInputSchemas`.
@@ -5443,11 +5482,12 @@ export function serialize(built, opts = {}) {
                         + `got ${JSON.stringify(cx?.id)}. \`uip solution resources list --kind Index --source remote --search "<name>"\` returns it as \`Key\`.`), { code: 'AGENT_CONTEXT_NO_ID' });
                 }
                 const cdef = contextIndexDef({ name: cx.name, id: cx.id });
-                // `<step>Context`, deduped by `uid` for a second index on the same agent.
-                // Not slugged from the index NAME: an id is the author's handle on the node
-                // and a 40-character one helps nobody.
-                const cid = uid(scope, `${step.name}Context`);
-                const cnode = makeNode(cdef.nodeType, cid, cx.name, { parentId, def: cdef });
+                // `<step>Context`, deduped by `uid` for a second index on the same agent,
+                // unless the author placed it (`nodeId`, which decompile writes for a
+                // node the canvas named). Not slugged from the index NAME: an id is the
+                // author's handle on the node and a 40-character one helps nobody.
+                const cid = resourceNodeId(scope, cx.nodeId, `${step.name}Context`, `inline agent "${step.name}": context index "${cx.name}"`);
+                const cnode = makeNode(cdef.nodeType, cid, cx.label ?? cx.name, { parentId, def: cdef });
                 // A resource is drawn as a circle, and `makeNode` copies only the icon.
                 cnode.display = { ...cnode.display, shape: 'circle' };
                 // Same rule as the agent's: the resource `model` lives on the DEFINITION.
@@ -5459,7 +5499,7 @@ export function serialize(built, opts = {}) {
                 // resource's `id` are the same uuid, because that is what joins them. The
                 // platform validator says so in its own refusal text — *"the resource id
                 // from the parent inline agent's `resources[]`"*.
-                const contextResourceId = fnv1aX4Uuid(`${built.id}/${step.name}/context/${cx.id}`);
+                const contextResourceId = cx.source ?? derivedContextSource(built.id, step.name, cx.id);
                 const contextQuery = renderContextQuery(cx.query, scope.rename);
                 cnode.inputs = {
                     // REQUIRED, and the platform's validator is what says so — measured
@@ -5469,6 +5509,7 @@ export function serialize(built, opts = {}) {
                     // node"* (MST-9265). It is the resource's own identity inside the
                     // project, so it is derived from flow + step + index rather than random,
                     // exactly like the agent's `source`: a recompile must not be a diff.
+                    // An author's `source` (a canvas directory decompile carried) wins.
                     source: contextResourceId,
                     indexId: cx.id,
                     indexName: cx.name,
@@ -5492,10 +5533,10 @@ export function serialize(built, opts = {}) {
                 addEdge(scope, { node: id, port: 'context' }, cid, 'input');
                 // The other half — without it the node is inert: see
                 // `contextResourceJson`.
-                sidecars.push({
+                addSidecar({
                     path: `${source}/resources/${contextResourceId}/resource.json`,
                     json: contextResourceJson(cx, { id: contextResourceId, query: contextQuery }),
-                });
+                }, cx.source !== undefined);
             }
             // TOOLS — one resource node per tool, joined to the agent's `tool` handle;
             // the same artifact shape as context (no incoming control flow, no output,
@@ -5660,7 +5701,7 @@ export function serialize(built, opts = {}) {
                     // copy puts it — emitting it on the node too would set inputs the
                     // def's own schema does not declare (our own output would be flagged).
                 }
-                const tid = uid(scope, `${step.name}Tool`);
+                const tid = resourceNodeId(scope, tr.nodeId, `${step.name}Tool`, `inline agent "${step.name}": ${tr.kind} tool "${label}"`);
                 const tnode = makeNode(tdef.nodeType, tid, label, { parentId, def: tdef });
                 tnode.display = { ...tnode.display, shape: 'circle' };
                 // `uip agent refresh` reads the tool's description off the node's display
@@ -5670,13 +5711,7 @@ export function serialize(built, opts = {}) {
                 // The resource model lives on the DEFINITION only (CX's rule for
                 // context, and what the deployed corpus carries for tools).
                 delete tnode.model;
-                const toolSeed = tr.kind === 'builtin' ? tr.tool
-                    : tr.kind === 'connector' ? `${tr.connector}.${tr.operation}`
-                        : tr.kind === 'ixp' ? tr.projectId
-                            : tr.kind === 'clientside' ? `clientside.${tr.name}`
-                                : tr.kind === 'httpRequest' ? `httprequest.${tr.name ?? 'default'}`
-                                    : tr.key;
-                const toolResourceId = fnv1aX4Uuid(`${built.id}/${step.name}/tool/${toolSeed}`);
+                const toolResourceId = tr.source ?? derivedToolSource(built.id, step.name, tr);
                 tnode.inputs = {
                     source: toolResourceId,
                     ...extraInputs,
@@ -5694,10 +5729,10 @@ export function serialize(built, opts = {}) {
                             ? httpRequestToolResourceJson(label, tnode.inputs, { id: toolResourceId, canvasNodeId: tid })
                             : toolResourceJson(tr, { id: toolResourceId });
                 if (toolResource !== undefined) {
-                    sidecars.push({
+                    addSidecar({
                         path: `${source}/resources/${toolResourceId}/resource.json`,
                         json: toolResource,
-                    });
+                    }, tr.source !== undefined);
                 }
             }
             // ESCALATION — the agent's TOP handle; an Action Center app task a human
@@ -5711,7 +5746,7 @@ export function serialize(built, opts = {}) {
                     // quick form carries, on the bundled `.quick-form` definition (the
                     // tenant registry does not serve the family).
                     const qdef = jsonClone(DEFS['uipath.agent.resource.escalation.quick-form@1.2']);
-                    const qid = uid(scope, `${step.name}Escalation`);
+                    const qid = resourceNodeId(scope, esc.nodeId, `${step.name}Escalation`, `inline agent "${step.name}": escalation "${esc.name}"`);
                     const qnode = makeNode(qdef.nodeType, qid, esc.name, { parentId, def: qdef });
                     qnode.display = { ...qnode.display, shape: 'circle' };
                     delete qnode.model;
@@ -5726,7 +5761,7 @@ export function serialize(built, opts = {}) {
                             ...(options !== undefined ? { options } : {}),
                         };
                     });
-                    const qsource = fnv1aX4Uuid(`${built.id}/${step.name}/escalation/${esc.name}`);
+                    const qsource = esc.source ?? derivedEscalationSource(built.id, step.name, esc.name);
                     qnode.inputs = {
                         source: qsource,
                         name: esc.name,
@@ -5758,23 +5793,23 @@ export function serialize(built, opts = {}) {
                     addEdge(scope, { node: id, port: 'escalation' }, qid, 'input');
                     // The other half — without it the escalation is inert: see
                     // `escalationResourceJson`.
-                    sidecars.push({
+                    addSidecar({
                         path: `${source}/resources/${qsource}/resource.json`,
                         json: escalationResourceJson(esc, {
                             id: qsource,
                             channelId: fnv1aX4Uuid(`${built.id}/${step.name}/escalation/${esc.name}/channel`),
                             quickFormSchema: qnode.inputs.schema,
                         }),
-                    });
+                    }, esc.source !== undefined);
                     continue;
                 }
                 const app = esc.app;
                 const edef = escalationDef();
-                const eid = uid(scope, `${step.name}Escalation`);
+                const eid = resourceNodeId(scope, esc.nodeId, `${step.name}Escalation`, `inline agent "${step.name}": escalation "${esc.name}"`);
                 const enode = makeNode(edef.nodeType, eid, esc.name, { parentId, def: edef });
                 enode.display = { ...enode.display, shape: 'circle' };
                 delete enode.model;
-                const esource = fnv1aX4Uuid(`${built.id}/${step.name}/escalation/${esc.name}`);
+                const esource = esc.source ?? derivedEscalationSource(built.id, step.name, esc.name);
                 enode.inputs = {
                     source: esource,
                     name: esc.name,
@@ -5807,13 +5842,13 @@ export function serialize(built, opts = {}) {
                 };
                 scope.nodes.push(enode);
                 addEdge(scope, { node: id, port: 'escalation' }, eid, 'input');
-                sidecars.push({
+                addSidecar({
                     path: `${source}/resources/${esource}/resource.json`,
                     json: escalationResourceJson(esc, {
                         id: esource,
                         channelId: fnv1aX4Uuid(`${built.id}/${step.name}/escalation/${esc.name}/channel`),
                     }),
-                });
+                }, esc.source !== undefined);
             }
             // MEMORY — one episodic-memory resource on the agent's `memory` handle
             // (the 1.4 definition selected above). Same artifact shape as context.
@@ -5946,7 +5981,7 @@ export function serialize(built, opts = {}) {
                 conversationalAgentSettings: settings,
             };
             scope.nodes.push(node);
-            sidecars.push({
+            addSidecar({
                 path: `${source}/agent.json`,
                 json: conversationalAgentJson({
                     model: s.model, systemPrompt: s.systemPrompt, temperature: s.temperature,
@@ -6023,7 +6058,7 @@ export function serialize(built, opts = {}) {
             // The sidecar half, in the voice dialect: `settings.voice` carries the
             // audio configuration (the storage layer's own StoredVoiceSettings
             // shape), and the messages carry the system prompt alone.
-            sidecars.push({
+            addSidecar({
                 path: `${source}/agent.json`,
                 json: voiceAgentJson({
                     systemPrompt: s.systemPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.32.8",
+  "version": "6.33.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "fad79d44a992f72b8a8d0ba0f9c61d8ea5705ed7"
+  "gitref": "a27439803ad2ab68ce5be0c4299649d3f4d92e0b"
 }