@uipath/maestro-builder-sdk 6.32.8 → 6.33.0

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.0",
   "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": "8875d03ffd74e131e88778405d2eb401dd13d0e9"
 }