@uipath/maestro-builder-sdk 6.31.5 → 6.31.7

package/dist/compile-cli.js

@@ -19,7 +19,7 @@
  */
 import { reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, compileOwnsResource } from './serialize.js';
@@ -32,9 +32,12 @@ import { readBindingsV2, readInlineAgentFiles } from './bindings-v2-files.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { defaultBindingsFile } from './workdir.js';
 import { isWithin } from './path-within.js';
-import { resourceSourcesOfOtherFlows } from './project-resource-users.js';
+import { flowSources, resourceSourcesOfOtherFlows } from './project-resource-users.js';
+import { fnv1aX4Uuid } from './core/stable-id.js';
 import { BindingRefusal } from './core/binding-messages.js';
 import { ByoaRefusal } from './core/byoa.js';
+/** An agent folder name: a uuid, any case. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error('usage: compile <flow.ts | BaseName> [-o out.flow] [--library <dir>] [--bindings <file>]');
@@ -93,10 +96,57 @@ export async function run(argv) {
     // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
     // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
     // (`--no-check`, or an emit-only project). Nothing is written.
+    const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
+    const outDir = dirname(resolve(out));
+    // ONE FOLDER, ONE FLOW (#1184). An agent's `source` is the name of the folder
+    // beside the `.flow` that holds its `agent.json` and `resources/`. Decompile
+    // keeps a canvas agent's `source` (the sidecar must still resolve), so
+    // compiling that source to a SECOND `.flow` in the same project would write
+    // into the first flow's folder: its `agent.json` is overwritten with the new
+    // flow's agent, and `uip agent refresh` for the new flow declares every
+    // resource the first flow keeps there. The product never shares a folder
+    // either: Studio Web mints a fresh uuid for an imported flow whose agent the
+    // project already owns, copies the folder and restamps `projectId`
+    // (flow-workbench MST-14919). So does compile: an agent whose `source`
+    // another `.flow` in this Flow project claims is written to its own folder,
+    // derived from that `source` and this file's name, so a recompile lands in
+    // the same one. Outside a Flow project (`project.uiproj`) nothing is a
+    // deliverable: the brownfield loop writes its baseline/edited candidates
+    // beside the original on purpose, and they are left as they were.
+    //
+    // Two rules keep the choice stable across later edits to the project:
+    //   - The OWNER keeps its folder. A source the existing `out` file already
+    //     names stays put, even if another `.flow` names it too (one compiled
+    //     into it before this rule existed): the flow being recompiled is the one
+    //     that already lives there, so it is never the one moved.
+    //   - A re-home is STICKY. Once the re-homed folder exists, the step keeps
+    //     writing there even after the flow that claimed the old folder is
+    //     deleted or renamed; otherwise the next compile would move back into the
+    //     old folder (and its leftover resources) and orphan the new one.
+    const inProject = existsSync(join(outDir, 'project.uiproj'));
+    const claimed = inProject ? sourcesOfOtherFlows(outDir, resolve(out)) : new Map();
+    const ownSources = inProject ? new Set(flowSources(readJsonOrUndefined(resolve(out))).map((s) => s.toLowerCase())) : new Set();
+    const rehomed = new Map();
+    const agentSource = (source, step) => {
+        // Only a uuid names a folder (as in Studio Web); anything else is left to
+        // the sidecar-path check below rather than read from here.
+        if (!inProject || !UUID.test(source))
+            return source;
+        const key = source.toLowerCase();
+        if (ownSources.has(key))
+            return source;
+        const to = fnv1aX4Uuid(`${key}/${basename(out)}`);
+        const owner = claimed.get(key);
+        if (owner === undefined)
+            return existsSync(join(outDir, to, 'agent.json')) ? to : source;
+        if (!rehomed.has(source))
+            rehomed.set(source, { from: source, to, step, owner });
+        return to;
+    };
     const warnings = [];
     let emitted;
     try {
-        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
+        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w), agentSource });
     }
     catch (error) {
         for (const w of warnings)
@@ -119,7 +169,6 @@ export async function run(argv) {
     for (const w of warnings)
         console.error(`  ⚠ [${w.code}] ${w.message}`);
     diagnostics.push(...warnings.map(serializeWarningDiagnostic));
-    const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
     // runtime (`entryPoint: "<source>/agent.json"`, resolved relative to the
@@ -131,7 +180,6 @@ export async function run(argv) {
     //
     // Every sidecar is checked before anything is written; success is reported
     // only once every file is on disk.
-    const outDir = dirname(resolve(out));
     const targets = sidecars.map((s) => ({ sidecar: s, target: resolve(outDir, s.path) }));
     const escaping = targets.find(({ target }) => target === outDir || !isWithin(outDir, target));
     if (escaping) {
@@ -152,6 +200,20 @@ export async function run(argv) {
         console.log(`compile: wrote ${sidecar.path}`);
         written.push(target);
     }
+    // A re-homed agent's folder starts as a copy of the folder it came from, minus
+    // what this compile just wrote (its `agent.json`, the resources it derives)
+    // and minus every `resources/<id>/` this flow's nodes do not name — copying
+    // those would hand the new flow's agent the old flow's index again, which is
+    // the bug. A file already in the new folder is the new flow's own and is kept.
+    if (rehomed.size > 0) {
+        const referenced = new Set(flowSources(flowJson).map((s) => s.toLowerCase()));
+        for (const { from, to, step, owner } of rehomed.values()) {
+            const copied = seedFolder(join(outDir, from), join(outDir, to), referenced);
+            console.log(`compile: agent "${step}" uses its own folder ${to}: ${from} belongs to ${owner}`
+                + (copied > 0 ? ` (copied ${copied} file(s) from it)` : '')
+                + `. To make this explicit, set source: "${to}" on "${step}" in the .flow.ts.`);
+        }
+    }
     reportResult({ path: resolve(out), nodes: flowJson.nodes.length, edges: flowJson.edges.length, sidecars: written });
     // PRUNE the agent resources this compile owns but did not write this time.
     // Compile otherwise only ever ADDS files, and an agent resource is keyed by a
@@ -176,7 +238,11 @@ export async function run(argv) {
     // canvas resources there are still that flow's. A resource another
     // `.flow` beside this one references by `inputs.source` is never pruned.
     const removedResources = [];
-    const referencedElsewhere = resourceSourcesOfOtherFlows(outDir, resolve(out));
+    const referencedElsewhere = sourcesOfOtherFlows(outDir, resolve(out));
+    // ... and neither is one THIS flow still names: a re-homed agent's folder is
+    // seeded with the resources its nodes reference (see `seedFolder`), and a
+    // designer resource a node here points at is in use, whatever its type.
+    const referencedHere = new Set(flowSources(flowJson).map((s) => s.toLowerCase()));
     const owned = new Set(sidecars
         .filter((s) => /\/resources\/[^/]+\/resource\.json$/.test(s.path))
         .map((s) => resolve(outDir, s.path)));
@@ -189,9 +255,9 @@ export async function run(argv) {
             continue;
         for (const entry of readdirSync(resourcesDir)) {
             const file = join(resourcesDir, entry, 'resource.json');
-            if (!existsSync(file) || owned.has(file))
+            if (!existsSync(file) || owned.has(file) || referencedHere.has(entry.toLowerCase()))
                 continue;
-            const user = referencedElsewhere.get(entry);
+            const user = referencedElsewhere.get(entry.toLowerCase());
             if (user !== undefined) {
                 console.log(`compile: kept ${join('resources', entry, 'resource.json')}: ${user} still references it`);
                 continue;
@@ -251,3 +317,60 @@ function serializeWarningDiagnostic(w) {
     return { level: 'warning', code: w.code, message: w.message };
 }
 runWhenInvokedDirectly(import.meta.url, 'compile', run);
+/** A JSON file's contents, or `undefined` when it is missing or unreadable. */
+function readJsonOrUndefined(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `resourceSourcesOfOtherFlows`, keyed lower-case: folder names keep their
+ * case, claims must not. The first file to claim a source wins, as there.
+ */
+function sourcesOfOtherFlows(dir, self) {
+    const users = new Map();
+    for (const [src, f] of resourceSourcesOfOtherFlows(dir, self)) {
+        if (!users.has(src.toLowerCase()))
+            users.set(src.toLowerCase(), f);
+    }
+    return users;
+}
+/**
+ * Copy agent folder `from` into `to`, for an agent re-homed off a folder another
+ * flow owns. Skipped: the top-level `agent.json` (compile writes its own, with
+ * the new identity), any `resources/<id>/` whose id is not in `referenced`, any
+ * file already present in `to`, and anything that is not a plain file or
+ * folder. Returns how many files were copied; a missing `from` copies nothing.
+ */
+function seedFolder(from, to, referenced) {
+    let copied = 0;
+    const walk = (rel) => {
+        let entries;
+        try {
+            entries = readdirSync(join(from, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const r = rel === '' ? e.name : join(rel, e.name);
+            if (rel === '' && e.name === 'agent.json')
+                continue;
+            if (rel === 'resources' && !referenced.has(e.name.toLowerCase()))
+                continue;
+            if (e.isDirectory()) {
+                walk(r);
+            }
+            else if (e.isFile() && !existsSync(join(to, r))) {
+                mkdirSync(dirname(join(to, r)), { recursive: true });
+                copyFileSync(join(from, r), join(to, r));
+                copied++;
+            }
+        }
+    };
+    walk('');
+    return copied;
+}

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/dist/project-resource-users.d.ts

@@ -7,3 +7,11 @@
  * nothing.
  */
 export declare function resourceSourcesOfOtherFlows(dir: string, self: string): Map<string, string>;
+/**
+ * Every `inputs.source` string a flow's nodes name — agent folders and agent
+ * resource ids alike — root scope and subflow bodies, in the case the file
+ * spells them. A malformed flow yields nothing. The one walk both
+ * {@link resourceSourcesOfOtherFlows} and compile's own-flow checks use, so the
+ * two cannot disagree on where a node keeps its source.
+ */
+export declare function flowSources(flow: unknown): string[];

package/dist/project-resource-users.js

@@ -31,17 +31,31 @@ export function resourceSourcesOfOtherFlows(dir, self) {
         catch {
             continue;
         }
-        const walk = (scope) => {
-            const s = scope;
-            for (const n of Array.isArray(s?.nodes) ? s.nodes : []) {
-                const src = n?.inputs?.source;
-                if (typeof src === 'string' && !users.has(src))
-                    users.set(src, f);
-            }
-            if (s?.subflows && typeof s.subflows === 'object')
-                Object.values(s.subflows).forEach(walk);
-        };
-        walk(flow);
+        for (const src of flowSources(flow))
+            if (!users.has(src))
+                users.set(src, f);
     }
     return users;
 }
+/**
+ * Every `inputs.source` string a flow's nodes name — agent folders and agent
+ * resource ids alike — root scope and subflow bodies, in the case the file
+ * spells them. A malformed flow yields nothing. The one walk both
+ * {@link resourceSourcesOfOtherFlows} and compile's own-flow checks use, so the
+ * two cannot disagree on where a node keeps its source.
+ */
+export function flowSources(flow) {
+    const ids = [];
+    const walk = (scope) => {
+        const s = scope;
+        for (const n of Array.isArray(s?.nodes) ? s.nodes : []) {
+            const src = n?.inputs?.source;
+            if (typeof src === 'string')
+                ids.push(src);
+        }
+        if (s?.subflows && typeof s.subflows === 'object')
+            Object.values(s.subflows).forEach(walk);
+    };
+    walk(flow);
+    return ids;
+}

package/dist/serialize.d.ts

@@ -99,6 +99,18 @@ export interface SerializeOpts {
         path: string;
         json: unknown;
     }>;
+    /**
+     * Maps an agent's folder uuid (its `source`) to the one this compile writes,
+     * given the step's name. `compile-cli` passes it when the `source` a step
+     * carries already belongs to ANOTHER `.flow` in the same Flow project (#1184):
+     * decompile keeps a canvas agent's `source`, so compiling that source to a
+     * second `.flow` would otherwise write into the first flow's folder. The uuid
+     * returned is spent everywhere the `source` is: the node's `inputs.source`,
+     * the `agent.json` identity, and every sidecar path.
+     *
+     * @internal
+     */
+    agentSource?: (source: string, step: string) => string;
 }
 /**
  * `serialize`, plus the extra files the flow needs on disk beside it.

package/dist/serialize.js

@@ -4335,6 +4335,17 @@ export function serialize(built, opts = {}) {
      * gets them and one that does not is unaffected.
      */
     const sidecars = opts.sidecars ?? [];
+    /**
+     * 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
+     * byte-identical — a v4-shaped uuid over a stable hash, because the platform
+     * treats it as an opaque id and the designer shows it as a folder. Then
+     * `opts.agentSource` may move it to a folder this flow owns (#1184).
+     */
+    const agentFolder = (carried, stepName) => {
+        const source = carried ?? fnv1aX4Uuid(`${built.id}/${stepName}`);
+        return opts.agentSource ? opts.agentSource(source, stepName) : source;
+    };
     const subflows = {};
     const rootGlobals = emittableGlobals(built, `flow "${built.id}"`);
     const root = newScope(rootGlobals.outputs, rootGlobals.vars, rootGlobals.backing, rootGlobals.backingReads);
@@ -5146,11 +5157,8 @@ export function serialize(built, opts = {}) {
                         : `Drop { version: '${version}' } to use ${INLINE_AGENT_DEFAULT_VERSION}, or drop \`memory\`.`));
             }
             const id = stepUid(scope, step.name);
-            // `source` is the agent's directory name. Derived from the flow id + step
-            // name rather than random so a recompile is byte-identical — a v4-shaped uuid
-            // over a stable hash, because the platform treats it as an opaque id and the
-            // designer shows it as a folder.
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            // `source` is the agent's directory name; see `agentFolder`.
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(def.nodeType, id, step.name, { parentId, requestedVersion: step.options?.version, def });
             // Unlike the published families the inline agent KEEPS no node-level model:
             // 29 of 29 deployed instances carry none (the def's `model.source: true` is
@@ -5706,7 +5714,7 @@ export function serialize(built, opts = {}) {
             // lets the platform do that translation.
             const s = spec.inputs;
             const id = stepUid(scope, step.name);
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(NODE_TYPE.conversationalAgent, id, step.name, { parentId, requestedVersion: step.options?.version });
             delete node.model;
             const st = s.settings ?? {};
@@ -5799,7 +5807,7 @@ export function serialize(built, opts = {}) {
             // definition declares what comes back.
             const s = spec.inputs;
             const id = stepUid(scope, step.name);
-            const source = s.source ?? fnv1aX4Uuid(`${built.id}/${step.name}`);
+            const source = agentFolder(s.source, step.name);
             const node = makeNode(NODE_TYPE.voiceAgent, id, step.name, { parentId, requestedVersion: step.options?.version });
             // Same rule as the inline agent's: the resource model lives on the
             // definition (its `model.source: true` is what makes `source` an input).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.31.5",
+  "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": "19700f105da9eae840ec05cd3796c28a96f1a4ed"
+  "gitref": "99f1861467ac06fba1c816f365bf027e1e2c8e05"
 }