@uipath/maestro-builder-sdk 6.31.6 → 6.31.7

package/dist/merge-embedded-agent.d.ts

@@ -0,0 +1,90 @@
+/**
+ * merge-embedded-agent — keep an EMBEDDED agent embedded when a brownfield edit
+ * touches it (flow-builder-sdk#1220).
+ *
+ * An agent node stores its configuration (prompts, model, run settings) in one
+ * of two places:
+ *
+ *   - embedded: on the node itself (`inputs.systemPrompt`, `inputs.model`, …).
+ *     Older Studio Web saves, and any save with the self-contained flag on.
+ *   - shell: the node keeps only its structural keys (`source`,
+ *     `agentInputVariables`, `agentOutputVariables`, …) and the configuration
+ *     lives in `<source>/agent.json`.
+ *
+ * The runtime and Studio Web pick the copy by `hasEmbeddedAgentContent`
+ * (`@uipath/flow-schema`): any prompt string on the node makes the node win and
+ * the sidecar is never read. Since #927 compile emits only shells. So when an
+ * edit changed an embedded agent's node (an input, an output, the label), the
+ * old merge took the edited SHELL node whole, and the agent's storage form
+ * flipped: the runtime then read the project's `<source>/agent.json`, which an
+ * embedded node had been shadowing and which is often stale. On corpus fixture
+ * `01-agent-input-binding` that silently changed the model from
+ * `gpt-4o-2024-11-20` to `gpt-5.4` and emptied the system prompt.
+ *
+ * The rule here is the same delta rule merge applies everywhere: the original
+ * node, plus what the author changed (`edited` minus `baseline`). The baseline
+ * and the edited node are both shells, so the configuration keys never appear in
+ * that delta and stay exactly as the original has them. Only the structural
+ * keys the author changed are taken from the edit. Without a baseline (a two-way
+ * merge), the edited node is taken, and every key the original has that the
+ * shell does not (the configuration) is put back.
+ *
+ * A prompt or model edit in the source does NOT reach an embedded agent: it
+ * lands in the edited `<source>/agent.json`, which the embedded node shadows.
+ * Merge reports that ({@link embeddedAgentFindings}), and refuses under
+ * `strict` any merged node that would no longer carry the original's embedded
+ * configuration, or whose kept prompt names an input the node no longer
+ * declares.
+ */
+import type { MergeFinding } from './merge-roundtrip.js';
+interface AgentNode {
+    id: string;
+    type: string;
+    inputs?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/**
+ * Whether `node` is an agent whose configuration is on the node, by
+ * `@uipath/flow-schema`'s `hasEmbeddedAgentContent`: a prompt string, or, on
+ * the voice node only, a `voice` settings object.
+ */
+export declare function isEmbeddedAgent(node: {
+    type?: string;
+    inputs?: Record<string, unknown>;
+} | undefined): boolean;
+/**
+ * The merged node for an embedded original whose edited node is a shell: the
+ * original, plus the author's change to the node.
+ *
+ * @param orig - The original node (embedded).
+ * @param edited - The edited compile's node (a shell).
+ * @param base - The baseline compile's node, when the merge has a baseline.
+ * @returns The original node with the edit's changed structural inputs and changed top-level keys applied.
+ */
+export declare function mergeEmbeddedAgentNode<N extends AgentNode>(orig: N, edited: N, base: N | undefined): N;
+/**
+ * What a merged embedded agent needs said, per original embedded agent (root
+ * and subflows, matched by scope and node id):
+ *
+ * - `agent-storage` (refuses): the merged node no longer carries the original's
+ *   embedded configuration, so the runtime would read `<source>/agent.json`
+ *   instead — a model or prompt change the author never wrote.
+ * - `agent-prompt-input` (refuses): a kept prompt names `{{input.X}}` but the
+ *   merged node declares no input `X` (the edit removed or renamed it), so the
+ *   prompt would render the placeholder empty.
+ * - `agent-embedded-edit` (warns): the author edited the node; merge applied the
+ *   node change and kept the original's prompts, model and settings, so a
+ *   prompt or model edit in the source did not reach this agent.
+ *
+ * @param hasBaseline - Whether the merge had a baseline. Without one, merge
+ *   cannot tell the author's change from the round trip's, so the
+ *   `agent-embedded-edit` warning says the node may have been edited.
+ * @param scopes - Per scope (`''` = root, otherwise the subflow key): the original, merged and edited-node-ids.
+ */
+export declare function embeddedAgentFindings(hasBaseline: boolean, scopes: Array<{
+    scope: string;
+    original: AgentNode[];
+    merged: AgentNode[];
+    edited: ReadonlySet<string>;
+}>): MergeFinding[];
+export {};

package/dist/merge-embedded-agent.js

@@ -0,0 +1,260 @@
+/**
+ * merge-embedded-agent — keep an EMBEDDED agent embedded when a brownfield edit
+ * touches it (flow-builder-sdk#1220).
+ *
+ * An agent node stores its configuration (prompts, model, run settings) in one
+ * of two places:
+ *
+ *   - embedded: on the node itself (`inputs.systemPrompt`, `inputs.model`, …).
+ *     Older Studio Web saves, and any save with the self-contained flag on.
+ *   - shell: the node keeps only its structural keys (`source`,
+ *     `agentInputVariables`, `agentOutputVariables`, …) and the configuration
+ *     lives in `<source>/agent.json`.
+ *
+ * The runtime and Studio Web pick the copy by `hasEmbeddedAgentContent`
+ * (`@uipath/flow-schema`): any prompt string on the node makes the node win and
+ * the sidecar is never read. Since #927 compile emits only shells. So when an
+ * edit changed an embedded agent's node (an input, an output, the label), the
+ * old merge took the edited SHELL node whole, and the agent's storage form
+ * flipped: the runtime then read the project's `<source>/agent.json`, which an
+ * embedded node had been shadowing and which is often stale. On corpus fixture
+ * `01-agent-input-binding` that silently changed the model from
+ * `gpt-4o-2024-11-20` to `gpt-5.4` and emptied the system prompt.
+ *
+ * The rule here is the same delta rule merge applies everywhere: the original
+ * node, plus what the author changed (`edited` minus `baseline`). The baseline
+ * and the edited node are both shells, so the configuration keys never appear in
+ * that delta and stay exactly as the original has them. Only the structural
+ * keys the author changed are taken from the edit. Without a baseline (a two-way
+ * merge), the edited node is taken, and every key the original has that the
+ * shell does not (the configuration) is put back.
+ *
+ * A prompt or model edit in the source does NOT reach an embedded agent: it
+ * lands in the edited `<source>/agent.json`, which the embedded node shadows.
+ * Merge reports that ({@link embeddedAgentFindings}), and refuses under
+ * `strict` any merged node that would no longer carry the original's embedded
+ * configuration, or whose kept prompt names an input the node no longer
+ * declares.
+ */
+import { jsonClone } from './core/json-clone.js';
+/**
+ * The agent node types whose configuration can live on the node or in
+ * `<source>/agent.json`, and whether a `voice` settings object on the node
+ * counts as embedded configuration (flow-schema counts it on the voice node only).
+ */
+const SIDECAR_AGENT_TYPES = new Map([
+    ['uipath.agent.autonomous', { voiceSettings: false }],
+    ['uipath.agent.conversational', { voiceSettings: false }],
+    ['uipath.agent.voice', { voiceSettings: true }],
+]);
+/**
+ * The agent-node inputs that are flow-level and survive Studio Web's shell
+ * strip (`STRUCTURAL_AGENT_INPUT_KEYS`, `@uipath/flow-schema`). Every other
+ * input of an embedded node is agent configuration.
+ */
+const STRUCTURAL_AGENT_INPUT_KEYS = new Set([
+    'source',
+    'agentInputVariables',
+    'agentOutputVariables',
+    'conversationalAgentSettings',
+    'callContext',
+]);
+/** The descriptor arrays, merged entry by entry (keyed by `id`) rather than whole. */
+const VARIABLE_ARRAY_KEYS = new Set(['agentInputVariables', 'agentOutputVariables']);
+/** Node keys the delta never takes from the edit: identity, and the position merge re-attaches separately. */
+const NODE_KEYS_NOT_IN_DELTA = new Set(['id', 'ui', 'inputs']);
+/**
+ * Whether `node` is an agent whose configuration is on the node, by
+ * `@uipath/flow-schema`'s `hasEmbeddedAgentContent`: a prompt string, or, on
+ * the voice node only, a `voice` settings object.
+ */
+export function isEmbeddedAgent(node) {
+    const kind = node?.type === undefined ? undefined : SIDECAR_AGENT_TYPES.get(node.type);
+    if (!node || kind === undefined)
+        return false;
+    const i = node.inputs ?? {};
+    if (typeof i.systemPrompt === 'string' || typeof i.userPrompt === 'string')
+        return true;
+    return kind.voiceSettings && typeof i.voice === 'object' && i.voice !== null;
+}
+/** The original's agent-configuration inputs: everything but the structural keys. */
+function configInputs(node) {
+    return Object.fromEntries(Object.entries(node.inputs ?? {}).filter(([k]) => !STRUCTURAL_AGENT_INPUT_KEYS.has(k)));
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function entriesById(v) {
+    return new Map((Array.isArray(v) ? v : []).map((e) => [e?.id, e]));
+}
+/**
+ * A descriptor array (`agentInputVariables` / `agentOutputVariables`) in the
+ * edited order. An entry the author did not change (equal to its baseline
+ * entry) is the original's, so it keeps what only the original carries (an
+ * embedded entry's `description`, its binding spelling). A changed or added
+ * entry is the edited one, over the original entry's extra fields, except a
+ * `description` when the edit rebound the entry: the original's describes the
+ * old binding (for instance "Bound from $vars.prep1.output.ticket").
+ */
+function mergeVariableArray(orig, edited, base, hasBaseline) {
+    if (!Array.isArray(edited))
+        return jsonClone(edited);
+    const o = entriesById(orig);
+    const b = entriesById(base);
+    return edited.map((e) => {
+        const oe = o.get(e?.id);
+        if (oe === undefined)
+            return jsonClone(e);
+        const be = b.get(e?.id);
+        if (hasBaseline && be !== undefined && same(be, e))
+            return jsonClone(oe);
+        // Two-way: an entry that matches the original's apart from the binding's
+        // spelling and the fields compile does not write is the original's.
+        if (!hasBaseline && Object.keys(e ?? {}).every((k) => (k === 'binding'
+            ? bindingText(oe.binding) === bindingText(e.binding)
+            : same(oe[k], e[k]))))
+            return jsonClone(oe);
+        const merged = { ...jsonClone(oe), ...jsonClone(e) };
+        // The baseline and the edit spell bindings the same way (both compiled); the
+        // original may not (`=$vars.x` vs `=js:$vars.x`), so compare it by text.
+        const rebound = hasBaseline && be !== undefined
+            ? !same(be.binding, e.binding)
+            : bindingText(oe.binding) !== bindingText(e.binding);
+        if (rebound && !('description' in e))
+            delete merged.description;
+        return merged;
+    });
+}
+/** A binding's expression text, without the `=` / `=js:` prefix, so two spellings of one binding compare equal. */
+function bindingText(binding) {
+    return typeof binding === 'string' ? binding.replace(/^=(js:)?/, '') : binding;
+}
+/**
+ * The merged node for an embedded original whose edited node is a shell: the
+ * original, plus the author's change to the node.
+ *
+ * @param orig - The original node (embedded).
+ * @param edited - The edited compile's node (a shell).
+ * @param base - The baseline compile's node, when the merge has a baseline.
+ * @returns The original node with the edit's changed structural inputs and changed top-level keys applied.
+ */
+export function mergeEmbeddedAgentNode(orig, edited, base) {
+    if (base === undefined) {
+        // Two-way: the edited node, with the original's configuration put back.
+        const out = jsonClone(edited);
+        const inputs = { ...(out.inputs ?? {}) };
+        for (const k of VARIABLE_ARRAY_KEYS) {
+            if (k in inputs)
+                inputs[k] = mergeVariableArray(orig.inputs?.[k], inputs[k], undefined, false);
+        }
+        out.inputs = { ...inputs, ...jsonClone(configInputs(orig)) };
+        return out;
+    }
+    const out = jsonClone(orig);
+    // Top-level keys (outputs, display, typeVersion, parentId, …): the edit's
+    // value where the author changed it.
+    for (const k of new Set([...Object.keys(base), ...Object.keys(edited)])) {
+        if (NODE_KEYS_NOT_IN_DELTA.has(k) || same(base[k], edited[k]))
+            continue;
+        if (k in edited)
+            out[k] = jsonClone(edited[k]);
+        else
+            delete out[k];
+    }
+    // Inputs: the same, key by key. The configuration keys are on neither shell,
+    // so they never differ here and stay the original's.
+    const bi = base.inputs ?? {};
+    const ei = edited.inputs ?? {};
+    const inputs = { ...(out.inputs ?? {}) };
+    for (const k of new Set([...Object.keys(bi), ...Object.keys(ei)])) {
+        if (same(bi[k], ei[k]))
+            continue;
+        if (!(k in ei))
+            delete inputs[k];
+        else if (VARIABLE_ARRAY_KEYS.has(k))
+            inputs[k] = mergeVariableArray(orig.inputs?.[k], ei[k], bi[k], true);
+        else
+            inputs[k] = jsonClone(ei[k]);
+    }
+    out.inputs = inputs;
+    return out;
+}
+/** `{{input.<name>}}` placeholders in a prompt string. */
+function promptInputs(prompt) {
+    if (typeof prompt !== 'string')
+        return [];
+    return [...prompt.matchAll(/\{\{\s*input\.([A-Za-z_$][\w$]*)\s*\}\}/g)].map((m) => m[1]);
+}
+/**
+ * What a merged embedded agent needs said, per original embedded agent (root
+ * and subflows, matched by scope and node id):
+ *
+ * - `agent-storage` (refuses): the merged node no longer carries the original's
+ *   embedded configuration, so the runtime would read `<source>/agent.json`
+ *   instead — a model or prompt change the author never wrote.
+ * - `agent-prompt-input` (refuses): a kept prompt names `{{input.X}}` but the
+ *   merged node declares no input `X` (the edit removed or renamed it), so the
+ *   prompt would render the placeholder empty.
+ * - `agent-embedded-edit` (warns): the author edited the node; merge applied the
+ *   node change and kept the original's prompts, model and settings, so a
+ *   prompt or model edit in the source did not reach this agent.
+ *
+ * @param hasBaseline - Whether the merge had a baseline. Without one, merge
+ *   cannot tell the author's change from the round trip's, so the
+ *   `agent-embedded-edit` warning says the node may have been edited.
+ * @param scopes - Per scope (`''` = root, otherwise the subflow key): the original, merged and edited-node-ids.
+ */
+export function embeddedAgentFindings(hasBaseline, scopes) {
+    const out = [];
+    for (const { scope, original, merged, edited } of scopes) {
+        const where = scope === '' ? '' : ` in subflow "${scope}"`;
+        const mergedById = new Map(merged.map((n) => [n.id, n]));
+        for (const o of original) {
+            if (!isEmbeddedAgent(o))
+                continue;
+            const m = mergedById.get(o.id);
+            if (m === undefined || m.type !== o.type)
+                continue; // deleted or replaced by the author
+            const lost = Object.entries(configInputs(o))
+                .filter(([k, v]) => !same(m.inputs?.[k], v))
+                .map(([k]) => k);
+            if (!isEmbeddedAgent(m) || lost.length > 0) {
+                out.push({
+                    kind: 'agent-storage', refuses: true,
+                    message: `agent "${o.id}"${where} carries its configuration on the node (embedded), but the merged node `
+                        + `${isEmbeddedAgent(m) ? 'changes' : 'drops'} ${lost.map((k) => `inputs.${k}`).join(', ') || 'its prompts'}, `
+                        + 'so the agent would run a configuration the author did not write (flow-builder-sdk#1220).',
+                });
+                continue;
+            }
+            const declared = new Set((Array.isArray(m.inputs?.agentInputVariables) ? m.inputs.agentInputVariables : [])
+                .map((v) => v?.id)
+                .filter((id) => typeof id === 'string'));
+            const missing = [...new Set([...promptInputs(m.inputs?.systemPrompt), ...promptInputs(m.inputs?.userPrompt)])]
+                .filter((name) => !declared.has(name));
+            const origDeclared = new Set((Array.isArray(o.inputs?.agentInputVariables) ? o.inputs.agentInputVariables : []).map((v) => v?.id));
+            // A placeholder the original already left undeclared is not the merge's doing.
+            const newlyMissing = missing.filter((name) => origDeclared.has(name));
+            if (newlyMissing.length > 0) {
+                out.push({
+                    kind: 'agent-prompt-input', refuses: true,
+                    message: `agent "${o.id}"${where} keeps its original embedded prompt, which uses `
+                        + `${newlyMissing.map((n) => `{{input.${n}}}`).join(', ')}, but the edit removed or renamed that input. `
+                        + 'An embedded agent\'s prompts are not taken from the source; change the prompt on the canvas too.',
+                });
+            }
+            if (edited.has(o.id)) {
+                out.push({
+                    kind: 'agent-embedded-edit', refuses: false,
+                    message: `agent "${o.id}"${where} carries its prompts, model and settings on the node (embedded). Merge applied `
+                        + (hasBaseline
+                            ? 'your change to the node'
+                            : 'the edited node\'s inputs and outputs (with no baseline it cannot tell your change from the round trip\'s, '
+                                + 'so this node may not have been edited)')
+                        + ' and kept those as the original has them. A prompt, model or settings edit in the '
+                        + 'source is not carried for an embedded agent (it would land in <source>/agent.json, which the node '
+                        + 'shadows); make that change on the canvas.',
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/merge-roundtrip.d.ts

@@ -33,12 +33,13 @@ interface RtFlow {
 /** One difference, or one inconsistency in the merged file. */
 export interface MergeFinding {
     /** Which comparison found it. */
-    kind: 'node-removed' | 'node-added' | 'node-type' | 'implicit-end' | 'edge-handle-renamed' | 'edge-rewired' | 'edge-removed' | 'edge-added' | 'handle-ids' | 'binding-removed' | 'binding-added' | 'undeclared-handle' | 'duplicate-binding' | 'agent-sidecar';
+    kind: 'node-removed' | 'node-added' | 'node-type' | 'implicit-end' | 'edge-handle-renamed' | 'edge-rewired' | 'edge-removed' | 'edge-added' | 'handle-ids' | 'binding-removed' | 'binding-added' | 'undeclared-handle' | 'duplicate-binding' | 'agent-sidecar' | 'agent-storage' | 'agent-prompt-input' | 'agent-embedded-edit';
     /** The finding, phrased for the author, naming the node, edge or row. */
     message: string;
     /**
      * Whether `strict` refuses the merge over it. False for `implicit-end` and
-     * `binding-removed`, which leave the merged file doing what the original does.
+     * `binding-removed`, which leave the merged file doing what the original does,
+     * and for `agent-embedded-edit`, which reports what merge did not carry.
      */
     refuses: boolean;
 }

package/dist/merge-sidecars.js

@@ -65,6 +65,7 @@
  * Pure: the caller reads the files ({@link SidecarSet}) and writes the result.
  */
 import { jsonClone } from './core/json-clone.js';
+import { isEmbeddedAgent } from './merge-embedded-agent.js';
 /** The `{ path, json }` list `serializeWithSidecars` returns, as a {@link SidecarSet}. */
 export function sidecarSetFromList(list) {
     return (source) => {
@@ -258,11 +259,13 @@ function carryResources(source, files, flows) {
     }
     return { writes, removals, unmatched };
 }
-/** Whether a node carries its prompts itself, so its `agent.json` is not what runs (see decompile's `sidecarAgentInputs`). */
-function carriesOwnPrompts(node) {
-    const i = node?.inputs ?? {};
-    return typeof i.systemPrompt === 'string' || typeof i.userPrompt === 'string';
-}
+/**
+ * The `agent.json` keys an embedded node carries itself, in its descriptor
+ * arrays (`agentInputVariables` / `agentOutputVariables`). An input or output
+ * edit changes them in the compiled `agent.json` and on the node; merge applies
+ * the node change (#1220), so their delta is not an edit the node shadows.
+ */
+const SCHEMA_ON_THE_NODE = /^(inputSchema|outputSchema)(\.|$)/;
 const finding = (message) => ({ kind: 'agent-sidecar', message, refuses: true });
 /**
  * The sidecar files the merged flow needs written beside it, and what merge could
@@ -310,12 +313,20 @@ export function mergeAgentSidecars(merged, sources, flows) {
         const changed = [];
         const next = mergeJson3(orig[agentPath], base[agentPath], edited[agentPath], changed);
         if (changed.length > 0) {
-            // `node` is the merged node: the original's when merge kept it, the
-            // edited shell when the author changed the node too.
-            if (carriesOwnPrompts(node)) {
-                findings.push(finding(`agent "${node.id}": its ${agentPath} was edited (${changed.join(', ')}), but the original node carries its `
-                    + 'own prompts, which are read before agent.json, so the edit would not reach the agent. The change is NOT '
-                    + 'carried. Make the change on the canvas, or save the agent with its prompts in agent.json only.'));
+            // `node` is the merged node: the original's when merge kept it; when the
+            // author changed the node too, the edited shell, or, for an embedded
+            // original, the original plus that change (#1220), still embedded.
+            // An embedded node (prompts or voice settings on the node) is read before
+            // agent.json, so an agent.json edit does not reach it. Its input and
+            // output schemas are the exception: the node's descriptor arrays carry
+            // them, and merge applied that node change already.
+            if (isEmbeddedAgent(node)) {
+                const shadowed = changed.filter((p) => !SCHEMA_ON_THE_NODE.test(p));
+                if (shadowed.length > 0) {
+                    findings.push(finding(`agent "${node.id}": its ${agentPath} was edited (${shadowed.join(', ')}), but the original node carries its `
+                        + 'own configuration (embedded), which is read before agent.json, so the edit would not reach the agent. The '
+                        + 'change is NOT carried. Make the change on the canvas, or save the agent with its prompts in agent.json only.'));
+                }
             }
             else if (stable(next) !== stable(orig[agentPath])) {
                 writes.push({ path: agentPath, json: next, carried: changed });

package/dist/merge.d.ts

@@ -75,6 +75,12 @@
  * `warn`, and `strict` refuses the merge over it; the merged file is also
  * checked for an edge that leaves a handle its kept source node does not
  * declare. See merge-roundtrip.ts.
+ *
+ * ## An embedded agent stays embedded
+ *
+ * An agent node whose original carries its prompts and model on the node is
+ * never replaced by the edited compile's shell node: the merged node is the
+ * original plus the author's change to the node. See merge-embedded-agent.ts.
  */
 import { type MergeSidecarSources, type SidecarWrite } from './merge-sidecars.js';
 export { MergeRefusedError, type MergeFinding } from './merge-roundtrip.js';
@@ -142,7 +148,12 @@ export interface MergeOptions {
      * - an edited node whose `typeVersion` differs from the original node with
      *   the same id, because the edit took the SDK's version;
      * - a merged edge whose `sourcePort` is not a handle its source node declares,
-     *   and two merged binding rows for the same resource property.
+     *   and two merged binding rows for the same resource property;
+     * - an edited agent whose original carries its prompts and model on the node
+     *   (embedded): merge keeps them and applies only the node change, so a prompt
+     *   or model edit in the source is not carried. Under `strict` it refuses a
+     *   merged node that would drop or change that embedded configuration, or
+     *   whose kept prompt uses an input the edit removed (flow-builder-sdk#1220).
      */
     warn?: (message: string) => void;
     /**

package/dist/merge.js

@@ -75,6 +75,12 @@
  * `warn`, and `strict` refuses the merge over it; the merged file is also
  * checked for an edge that leaves a handle its kept source node does not
  * declare. See merge-roundtrip.ts.
+ *
+ * ## An embedded agent stays embedded
+ *
+ * An agent node whose original carries its prompts and model on the node is
+ * never replaced by the edited compile's shell node: the merged node is the
+ * original plus the author's change to the node. See merge-embedded-agent.ts.
  */
 import { bindingIdentity } from './core/binding-identity.js';
 import { jsonClone } from './core/json-clone.js';
@@ -82,6 +88,7 @@ import { DEFINITIONLESS_NODE_TYPES } from './core/definitionless-node-types.js';
 import { MergeRefusedError, mergedFileFindings, roundTripFindings } from './merge-roundtrip.js';
 import { placeAddedNodes } from './node-placement.js';
 import { mergeAgentSidecars } from './merge-sidecars.js';
+import { embeddedAgentFindings, isEmbeddedAgent, mergeEmbeddedAgentNode } from './merge-embedded-agent.js';
 export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
@@ -218,6 +225,8 @@ function mergeFlowFindings(original, edited, options) {
     // references are the original's now, not the recompile's
     // (see withoutRowsMintedForKeptNodes).
     const keptFromOriginal = new Set();
+    /** Root node ids taken from `edited` that the original also has (the author edited them). */
+    const editedIds = new Set();
     for (const e of edited.nodes ?? []) {
         const orig = origNodes.get(e.id);
         if (isKept(e, origNodes, baseNodes, options.baseline) && orig) {
@@ -228,9 +237,17 @@ function mergeFlowFindings(original, edited, options) {
         }
         else {
             // Added or edited → take the edited node, re-attaching original layout.
-            finalNodes.push(withOriginalSource(withOriginalLayout(jsonClone(e), orig, layoutNodesOf(original)), orig, baseNodes.get(e.id)));
-            if (orig && orig.type === e.type && orig.typeVersion !== e.typeVersion) {
-                options.warn?.(`node ${JSON.stringify(e.id)} moved ${e.type}@${String(orig.typeVersion)} -> ${String(e.typeVersion)} `
+            // An EMBEDDED agent stays embedded: the original plus the author's change
+            // to the node, never the edited shell whole (#1220, merge-embedded-agent.ts).
+            const node = keepsEmbeddedAgent(orig, e) ? mergeEmbeddedAgentNode(orig, e, baseNodes.get(e.id)) : jsonClone(e);
+            const placed = withOriginalSource(withOriginalLayout(node, orig, layoutNodesOf(original)), orig, baseNodes.get(e.id));
+            finalNodes.push(placed);
+            // Without a baseline every node lands here; count one as edited only
+            // when the merged node differs from the original.
+            if (orig && (options.baseline || !sameApartFromUi(placed, orig)))
+                editedIds.add(e.id);
+            if (orig && orig.type === node.type && orig.typeVersion !== node.typeVersion) {
+                options.warn?.(`node ${JSON.stringify(e.id)} moved ${e.type}@${String(orig.typeVersion)} -> ${String(node.typeVersion)} `
                     + `(the edited source does not pin ${String(orig.typeVersion)}; keep the { version } pin, `
                     + `with .definitions([...]) when the SDK does not bundle that version).`);
             }
@@ -242,6 +259,11 @@ function mergeFlowFindings(original, edited, options) {
     // ── Variables & subflows: the edited flow is authoritative (the user's graph). ──
     result.variables = jsonClone(edited.variables);
     result.subflows = jsonClone(edited.subflows ?? {});
+    // A subflow is taken from `edited` whole, so an embedded agent inside one
+    // would flip to the edited shell even with no edit. Keep it embedded too.
+    // This runs before the source fix-up below: it compares each node with the
+    // baseline to tell which ones the author edited.
+    const subflowEdited = keepEmbeddedAgentsInSubflows(original, result.subflows, options.baseline);
     if (options.baseline)
         keepOriginalSourcesInSubflows(original, result.subflows, options.baseline);
     const subflowScopes = Object.values(result.subflows);
@@ -296,9 +318,74 @@ function mergeFlowFindings(original, edited, options) {
     const findings = [
         ...(options.baseline ? roundTripFindings(original, options.baseline, result) : []),
         ...mergedFileFindings(result, original),
+        ...embeddedAgentFindings(!!options.baseline, [
+            { scope: '', original: original.nodes ?? [], merged: finalNodes, edited: editedIds },
+            ...Object.entries(original.subflows ?? {}).map(([key, sf]) => ({
+                scope: key,
+                original: sf?.nodes ?? [],
+                merged: result.subflows?.[key]?.nodes ?? [],
+                edited: subflowEdited.get(key) ?? new Set(),
+            })),
+        ]),
     ];
     return { result, findings };
 }
+/**
+ * Whether the merged node for `orig` must be built from the original rather than
+ * taken from `edited`: the original is an embedded agent and the edited node is
+ * not (compile emits only shells), so taking it would move the agent's
+ * configuration from the node to `<source>/agent.json`.
+ */
+function keepsEmbeddedAgent(orig, e) {
+    return orig !== undefined && orig.type === e.type && isEmbeddedAgent(orig) && !isEmbeddedAgent(e);
+}
+/**
+ * Whether two nodes are equal apart from their position (`ui`), which merge
+ * re-attaches separately, and apart from object key order (a two-way embedded
+ * merge puts the original's configuration keys after the edited shell's).
+ */
+function sameApartFromUi(a, b) {
+    if (!a || !b)
+        return false;
+    const { ui: _a, ...ra } = a;
+    const { ui: _b, ...rb } = b;
+    return sortedJson(ra) === sortedJson(rb);
+}
+/** JSON text with object keys sorted, so two objects that differ only in key order compare equal. */
+function sortedJson(v) {
+    return JSON.stringify(v, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x)
+        ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : x));
+}
+/**
+ * In each subflow taken from `edited`, replace an edited shell agent whose
+ * original (same subflow, same id) is embedded with
+ * {@link mergeEmbeddedAgentNode}'s result. Returns, per subflow, the ids of the
+ * original's nodes the author edited (differ from the baseline, or, without a
+ * baseline, merged differently from the original).
+ */
+function keepEmbeddedAgentsInSubflows(original, subflows, baseline) {
+    const edited = new Map();
+    for (const [key, sf] of Object.entries(subflows)) {
+        const nodes = sf?.nodes;
+        if (!Array.isArray(nodes))
+            continue;
+        const origNodes = byId(original.subflows?.[key]?.nodes);
+        const baseNodes = byId(baseline?.subflows?.[key]?.nodes);
+        const ids = new Set();
+        for (let i = 0; i < nodes.length; i++) {
+            const e = nodes[i];
+            const orig = origNodes.get(e.id);
+            if (keepsEmbeddedAgent(orig, e))
+                nodes[i] = mergeEmbeddedAgentNode(orig, e, baseline ? baseNodes.get(e.id) : undefined);
+            const changed = baseline ? !nodeUnchanged(e, baseNodes.get(e.id)) : !sameApartFromUi(nodes[i], orig);
+            if (orig && changed)
+                ids.add(e.id);
+        }
+        edited.set(key, ids);
+    }
+    return edited;
+}
 /**
  * The root edges with their edited ids, except that an edge with no id, or with
  * an id already used by a subflow edge or an earlier root edge, gets a fresh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.31.6",
+  "version": "6.31.7",
   "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": "77c2e7b1f09268cc94ee0f4b8f9d4ae80ba625ee"
+  "gitref": "99f1861467ac06fba1c816f365bf027e1e2c8e05"
 }