@uipath/maestro-builder-sdk 6.30.0 → 6.30.1

package/dist/decompile-cli.js

@@ -105,11 +105,16 @@ function pipelineScript(originalPath, tsPath, pipelinePath) {
 // Generated by flow-decompile — the brownfield read/modify/write pipeline for
 // ${commentText(basename(originalPath))}. Run it, edit ${commentText(basename(tsPath))}, run it again.
 ${pipelineFrontDoor('flow')}
+import { mkdirSync } from 'node:fs';
 
 const ORIGINAL = ${JSON.stringify(originalPath)};
 const TS       = ${JSON.stringify(tsPath)};
-const BASELINE = ${JSON.stringify(base + '.baseline.flow')};
-const EDITED   = ${JSON.stringify(base + '.edited.flow')};
+// The baseline and the edited compile each get a directory of their own: a
+// compile writes an inline agent's \`<source>/agent.json\` beside its output, and
+// merge reads both copies to carry a prompt or settings edit (#1207). In one
+// directory the edited compile would overwrite the baseline's.
+const BASELINE = ${JSON.stringify(join(base + '.baseline', basename(base) + '.flow'))};
+const EDITED   = ${JSON.stringify(join(base + '.edited', basename(base) + '.flow'))};
 const MERGED   = ${JSON.stringify(base + '.merged.flow')};
 
 // Ensure the decompiled source exists (a fresh clone may have only the .flow).
@@ -118,10 +123,12 @@ if (!existsSync(TS)) run('decompile', [ORIGINAL, '-o', TS, '--no-pipeline']);
 if (!existsSync(BASELINE)) {
   // ── Step 1: capture the baseline = compile of the PRISTINE decompiled code,
   //    BEFORE any edit. Run this once right after decompiling, then edit. ──
+  mkdirSync(dirname(BASELINE), { recursive: true });
   run('compile', [TS, '-o', BASELINE, '--no-check']);
   console.log('\\n>>> Baseline captured. Now EDIT ' + ${JSON.stringify(basename(tsPath))} + ', then re-run this script to compile + merge.');
 } else {
   // ── Step 2: compile your edits, then merge them back into the original. ──
+  mkdirSync(dirname(EDITED), { recursive: true });
   run('compile', [TS, '-o', EDITED, '--no-check']);
 
   // ── DIFF GATE (seam) ──────────────────────────────────────────────────────
@@ -142,7 +149,8 @@ if (!existsSync(BASELINE)) {
   const args = namedOriginal ? [EDITED, '--original', ORIGINAL, '-o', MERGED] : [ORIGINAL, EDITED, '-o', MERGED];
   if (existsSync(BASELINE)) args.push('--baseline', BASELINE);
   run('merge', args);
-  console.log('\\n>>> Wrote ' + ${JSON.stringify(base + '.merged.flow')});
+  console.log('\\n>>> Wrote ' + ${JSON.stringify(base + '.merged.flow')}
+    + '. Replace the original with it, together with every <source>/ file merge reports writing beside it.');
 }
 `;
 }

package/dist/merge-cli.d.ts

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
+import { type SidecarSet } from './merge-sidecars.js';
 import { type CliExitCode } from './cli-run.js';
+/**
+ * The agent sidecars beside the flow at `flowPath`: `<source>/agent.json` and each
+ * `<source>/resources/<id>/resource.json`, parsed. An unreadable or invalid file
+ * reads as absent.
+ */
+export declare function sidecarsBeside(flowPath: string): SidecarSet;
 export declare function run(argv: string[]): Promise<CliExitCode>;

package/dist/merge-cli.js

@@ -18,12 +18,26 @@
  * With `--baseline`, every wire-identity difference between the baseline and
  * the original (what the no-edit round trip changed) is printed as a warning;
  * `--strict` refuses instead (exit 1, nothing written). See merge.ts.
+ *
+ * Agent sidecars (#1207): an inline agent's prompts and settings live in
+ * `<source>/agent.json` beside each flow, not in the node. Merge reads that file
+ * beside the original, the baseline and the edited flow, applies the author's
+ * change (baseline -> edited) onto the original's copy, and writes the result
+ * beside the merged output, one `flow-merge: wrote <source>/agent.json` line per
+ * file. Copy those files along with the merged `.flow`. The baseline's sidecars
+ * are only known when the baseline and the edited flow are in different
+ * directories (each compile writes `<source>/` beside its output), or when merge
+ * compiled the side itself (`--baseline-from`, an edited `.flow.ts`), which keeps
+ * the sidecars in memory; what merge cannot carry is warned, and refused under
+ * `--strict`. See merge-sidecars.ts.
  */
 import { reportResult } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
-import { readFileSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
-import { MergeRefusedError, mergeFlow } from './merge.js';
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { MergeRefusedError, mergeFlowWithSidecars } from './merge.js';
+import { sidecarSetFromList } from './merge-sidecars.js';
+import { isWithin } from './path-within.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
 import { flowCheckOpts, openCliLibrary } from './cli-library.js';
@@ -32,6 +46,38 @@ import { defaultBindingsFile } from './workdir.js';
 import { baselineFromOriginal, checkEdited, classifyDrafts, compileSourceDraftTolerant } from './merge-compile.js';
 const USAGE = 'usage: flow-merge <original.flow> <edited.flow | Edited.flow.ts> [-o merged.flow] '
     + '[--baseline <baseline.flow> | --baseline-from <original.flow>] [--library <dir>] [--bindings <file>] [--strict]';
+/**
+ * The agent sidecars beside the flow at `flowPath`: `<source>/agent.json` and each
+ * `<source>/resources/<id>/resource.json`, parsed. An unreadable or invalid file
+ * reads as absent.
+ */
+export function sidecarsBeside(flowPath) {
+    const dir = dirname(resolve(flowPath));
+    const read = (rel) => {
+        try {
+            return JSON.parse(readFileSync(join(dir, rel), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return (source) => {
+        const agent = read(`${source}/agent.json`);
+        if (agent === undefined)
+            return undefined;
+        const files = { [`${source}/agent.json`]: agent };
+        const resourcesDir = join(dir, source, 'resources');
+        if (existsSync(resourcesDir)) {
+            for (const entry of readdirSync(resourcesDir)) {
+                const rel = `${source}/resources/${entry}/resource.json`;
+                const json = read(rel);
+                if (json !== undefined)
+                    files[rel] = json;
+            }
+        }
+        return files;
+    };
+}
 export async function run(argv) {
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         console.error(USAGE);
@@ -62,6 +108,7 @@ export async function run(argv) {
     let drafts = [];
     let diagnostics = [];
     let edited;
+    let editedSidecars;
     if (editedIsSource) {
         // The edited source gets what `compile` gives it: check() with the same
         // options, and the serializer's warnings (CONNECTION_STUB, ...) printed.
@@ -70,14 +117,18 @@ export async function run(argv) {
             warn: (w) => console.error(`  ⚠ [${w.code}] ${w.message}`),
         });
         edited = compiled.flow;
+        editedSidecars = compiled.sidecars;
         drafts = compiled.drafts;
         diagnostics = checkEdited(compiled.built, edited, flowCheckOpts(library, bindings));
     }
     else {
         edited = JSON.parse(readFileSync(editedPath, 'utf8'));
     }
-    const baseline = baselineFrom
-        ? (await baselineFromOriginal(baselineFrom, compileOpts, (m) => console.error(`flow-merge: decompile warning: ${m}`))).flow
+    const baselineCompile = baselineFrom
+        ? await baselineFromOriginal(baselineFrom, compileOpts, (m) => console.error(`flow-merge: decompile warning: ${m}`))
+        : undefined;
+    const baselineSidecars = baselineCompile?.sidecars;
+    const baseline = baselineCompile ? baselineCompile.flow
         : baselinePath ? JSON.parse(readFileSync(baselinePath, 'utf8')) : undefined;
     const strict = argv.includes('--strict');
     if (strict && !baseline) {
@@ -107,9 +158,25 @@ export async function run(argv) {
         console.error(`flow-merge: ${errors.length} error(s) in nodes merge takes from the edited flow; finish them or revert the edit. Nothing written.`);
         return 1;
     }
+    // Each compile writes `<source>/` beside its own output, so a baseline in the
+    // edited flow's directory had its sidecars overwritten by the edited compile.
+    // A side merge compiled itself (--baseline-from, an edited .flow.ts) carries
+    // its sidecars in memory instead.
+    const dirOf = (p) => dirname(resolve(p));
+    const baselineShared = baselinePath !== undefined && !editedIsSource && dirOf(baselinePath) === dirOf(editedPath);
+    const sources = {
+        original: sidecarsBeside(originalPath),
+        edited: editedSidecars ? sidecarSetFromList(editedSidecars) : sidecarsBeside(editedPath),
+        baseline: baselineSidecars ? sidecarSetFromList(baselineSidecars)
+            : baselinePath !== undefined && !baselineShared ? sidecarsBeside(baselinePath) : undefined,
+        baselineMissing: baselinePath === undefined
+            ? 'no --baseline or --baseline-from was given'
+            : `the baseline and the edited flow are in one directory (${dirOf(editedPath)}), so the edited compile `
+                + 'overwrote the baseline\'s agent sidecars',
+    };
     let merged;
     try {
-        merged = mergeFlow(original, edited, {
+        merged = mergeFlowWithSidecars(original, edited, sources, {
             baseline,
             strict,
             warn: (m) => console.error(`flow-merge: warning: ${m}`),
@@ -122,9 +189,28 @@ export async function run(argv) {
         return 1;
     }
     const out = flagValue(argv, '-o') ?? 'merged.flow';
-    writeJsonFile(out, merged);
-    console.log(`flow-merge: wrote ${basename(out)} (${(merged.nodes ?? []).length} nodes, ${(merged.edges ?? []).length} edges)`);
-    reportResult({ path: resolve(out), nodes: (merged.nodes ?? []).length, edges: (merged.edges ?? []).length });
+    const outDir = dirOf(out);
+    const targets = merged.sidecars.map((s) => ({ sidecar: s, target: resolve(outDir, s.path) }));
+    const escaping = targets.find(({ target }) => !isWithin(outDir, target));
+    if (escaping) {
+        console.error(`flow-merge: refusing to write a sidecar outside the merged flow's directory: ${escaping.sidecar.path}`);
+        return 1;
+    }
+    const flow = merged.flow;
+    mkdirSync(outDir, { recursive: true });
+    writeJsonFile(out, flow);
+    console.log(`flow-merge: wrote ${basename(out)} (${(flow.nodes ?? []).length} nodes, ${(flow.edges ?? []).length} edges)`);
+    for (const { sidecar, target } of targets) {
+        mkdirSync(dirname(target), { recursive: true });
+        writeJsonFile(target, sidecar.json);
+        console.log(`flow-merge: wrote ${sidecar.path} (carries ${sidecar.carried.join(', ')})`);
+    }
+    reportResult({
+        path: resolve(out),
+        nodes: (flow.nodes ?? []).length,
+        edges: (flow.edges ?? []).length,
+        ...(targets.length > 0 ? { sidecars: targets.map((t) => t.target) } : {}),
+    });
     return 0;
 }
 runWhenInvokedDirectly(import.meta.url, 'flow-merge', run);

package/dist/merge-compile.d.ts

@@ -1,10 +1,17 @@
 import { type DraftFinding, type SerializeOpts } from './serialize.js';
 import { type CheckOpts, type Diagnostic } from './check.js';
 import type { BuiltFlow } from './flow-sdk.js';
-/** A compile's flow and the draft refusals it reported instead of throwing. */
+/**
+ * A compile's flow, the draft refusals it reported instead of throwing, and the
+ * agent sidecars (`<source>/agent.json`, resource files) it produced, none written.
+ */
 export interface DraftTolerantCompile {
     flow: any;
     drafts: DraftFinding[];
+    sidecars: Array<{
+        path: string;
+        json: unknown;
+    }>;
 }
 /** Compile `built` with draft tolerance. Every other refusal still throws. */
 export declare function compileDraftTolerant(built: BuiltFlow, opts?: Omit<SerializeOpts, 'draft'>): DraftTolerantCompile;

package/dist/merge-compile.js

@@ -18,8 +18,9 @@ import { PACKAGE_NAME } from './package-name.js';
 /** Compile `built` with draft tolerance. Every other refusal still throws. */
 export function compileDraftTolerant(built, opts = {}) {
     const drafts = [];
-    const flow = serialize(built, { ...opts, draft: (f) => drafts.push(f) });
-    return { flow, drafts };
+    const sidecars = [];
+    const flow = serialize(built, { ...opts, draft: (f) => drafts.push(f), sidecars });
+    return { flow, drafts, sidecars };
 }
 /**
  * Load a `.flow.ts` source and compile it with draft tolerance.

package/dist/merge-roundtrip.d.ts

@@ -33,7 +33,7 @@ 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';
+    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';
     /** The finding, phrased for the author, naming the node, edge or row. */
     message: string;
     /**

package/dist/merge-roundtrip.js

@@ -373,7 +373,8 @@ export class MergeRefusedError extends Error {
     /** Every refusing finding, in report order. */
     findings;
     constructor(findings) {
-        super(`refused (--strict): the merged file would differ from the original where the author made no edit:\n`
+        super(`refused (--strict): the merged file would differ from the original where the author made no edit, `
+            + `or would leave out an edit the author made:\n`
             + findings.map((f) => `  - ${f.message}`).join('\n'));
         this.name = 'MergeRefusedError';
         this.findings = findings;

package/dist/merge-sidecars.d.ts

@@ -0,0 +1,71 @@
+import type { MergeFinding } from './merge-roundtrip.js';
+/**
+ * The sidecar files of one side of the merge, per agent `source`: every file
+ * under `<source>/` that merge understands, keyed by its path relative to the
+ * flow (`<source>/agent.json`, `<source>/resources/<id>/resource.json`), parsed.
+ * `undefined` when that side has no `<source>/agent.json`.
+ */
+export type SidecarSet = (source: string) => Record<string, unknown> | undefined;
+/** The three sides' sidecars, as {@link mergeAgentSidecars} reads them. */
+export interface MergeSidecarSources {
+    original: SidecarSet;
+    edited: SidecarSet;
+    /**
+     * The baseline compile's sidecars. Leave it out when they are not known, and
+     * say why in {@link baselineMissing}: merge then cannot tell an edit from the
+     * round trip's own changes, and reports instead of carrying.
+     */
+    baseline?: SidecarSet;
+    /** Why {@link baseline} is absent, phrased to finish "merge cannot tell an edit from the round trip: …". */
+    baselineMissing?: string;
+}
+/** One file the merged flow needs written beside it, relative to it. */
+export interface SidecarWrite {
+    path: string;
+    json: unknown;
+    /** What it carries, for the report: the changed `agent.json` paths, or `new agent`. */
+    carried: string[];
+}
+/** The `{ path, json }` list `serializeWithSidecars` returns, as a {@link SidecarSet}. */
+export declare function sidecarSetFromList(list: ReadonlyArray<{
+    path: string;
+    json: unknown;
+}>): SidecarSet;
+interface AnyNode {
+    id: string;
+    inputs?: Record<string, unknown>;
+}
+/**
+ * The agent `source` directories a flow's nodes point at, root and subflows,
+ * each with the first node that does. A `source` is a single directory name
+ * (the agent's uuid); anything else (an expression, a path) is not a sidecar
+ * directory and is skipped.
+ */
+export declare function agentSources(flow: {
+    nodes?: AnyNode[];
+    subflows?: Record<string, unknown>;
+} | undefined): Map<string, AnyNode>;
+/**
+ * Three-way merge of one JSON value: `original` with the change from `baseline`
+ * to `edited` applied. Objects merge key by key; arrays merge index by index
+ * when all three have the same length (a prompt edit changes `messages[0]` and
+ * leaves `messages[1]` as the original has it), and are replaced whole otherwise.
+ * Every replaced path is pushed to `changed`.
+ *
+ * For example original `{a: 1, b: 2}`, baseline `{a: 1}`, edited `{a: 3}` gives
+ * `{a: 3, b: 2}` and `changed = ["a"]`.
+ */
+export declare function mergeJson3(original: unknown, baseline: unknown, edited: unknown, changed: string[], path?: string): unknown;
+/**
+ * The sidecar files the merged flow needs written beside it, and what merge could
+ * not carry. `merged` is `mergeFlow`'s result. An agent is new when the
+ * original side has no `<source>/agent.json` for it.
+ */
+export declare function mergeAgentSidecars(merged: {
+    nodes?: AnyNode[];
+    subflows?: Record<string, unknown>;
+}, sources: MergeSidecarSources): {
+    writes: SidecarWrite[];
+    findings: MergeFinding[];
+};
+export {};

package/dist/merge-sidecars.js

@@ -0,0 +1,214 @@
+/**
+ * merge-sidecars — carry an agent's sidecar edits through a brownfield merge (#1207).
+ *
+ * An inline agent is TWO artifacts: the node in the `.flow`, and the agent's own
+ * configuration in `<source>/agent.json` beside it (plus a
+ * `<source>/resources/<id>/resource.json` per attached resource). Since #927 the
+ * node is a shell: the prompts, the model and the run settings live ONLY in the
+ * sidecar. So an edit to a prompt leaves the agent node byte-equal in the baseline
+ * and the edited compile, `mergeFlow` keeps the original node (correctly: the node
+ * did not change), and the only artifact that changed is a file merge used not to
+ * read. The edit was lost without a word.
+ *
+ * This module is merge's view of those files. For every agent the merged flow
+ * keeps, it computes what the author changed in `agent.json` (baseline -> edited)
+ * and applies exactly that onto the ORIGINAL's `agent.json`:
+ *
+ *     original  { model: "gpt-5.4", maxIterations: 25, system: "Summarize..." }
+ *     baseline  { model: "gpt-5.4",                    system: "Summarize..." }   <- round trip drops maxIterations
+ *     edited    { model: "gpt-5.4",                    system: "EDITED..." }
+ *     merged    { model: "gpt-5.4", maxIterations: 25, system: "EDITED..." }
+ *
+ * Taking `edited`'s file whole would carry the round trip's own changes too
+ * (`maxIterations` dropped above; on a canvas flow, a dropped `description`, a
+ * default model filled in). A delta carries the edit and nothing else, the same
+ * rule `mergeFlow` applies to nodes.
+ *
+ * What it cannot carry, it reports as a {@link MergeFinding} that `strict`
+ * refuses, so no sidecar edit can disappear silently:
+ *
+ * - no baseline sidecar to compare with (no `--baseline`, or the baseline and the
+ *   edited compile were written to one directory, so the second overwrote the
+ *   first's `<source>/`), and the edited `agent.json` differs from the original's;
+ * - a change to the agent's resource files (a context or tool added or removed);
+ * - an `agent.json` edit on a node that carries its own prompts (an embedded
+ *   node: decompile, like Studio Web, reads the node's prompts first, so the
+ *   edited file would not be what runs).
+ *
+ * An agent the merged flow adds (no sidecar in the original) gets the edited
+ * compile's files whole.
+ *
+ * Pure: the caller reads the files ({@link SidecarSet}) and writes the result.
+ */
+import { jsonClone } from './core/json-file.js';
+/** The `{ path, json }` list `serializeWithSidecars` returns, as a {@link SidecarSet}. */
+export function sidecarSetFromList(list) {
+    return (source) => {
+        const files = {};
+        for (const s of list)
+            if (s.path.startsWith(`${source}/`))
+                files[s.path] = s.json;
+        return files[`${source}/agent.json`] === undefined ? undefined : files;
+    };
+}
+/**
+ * The agent `source` directories a flow's nodes point at, root and subflows,
+ * each with the first node that does. A `source` is a single directory name
+ * (the agent's uuid); anything else (an expression, a path) is not a sidecar
+ * directory and is skipped.
+ */
+export function agentSources(flow) {
+    const out = new Map();
+    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' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(src) && !out.has(src))
+                out.set(src, n);
+        }
+        if (s?.subflows && typeof s.subflows === 'object')
+            Object.values(s.subflows).forEach(walk);
+    };
+    walk(flow);
+    return out;
+}
+/** JSON with object keys sorted, so key order is not a difference. */
+function stable(v) {
+    return JSON.stringify(v, (_k, val) => (val && typeof val === 'object' && !Array.isArray(val)
+        ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
+        : val));
+}
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Three-way merge of one JSON value: `original` with the change from `baseline`
+ * to `edited` applied. Objects merge key by key; arrays merge index by index
+ * when all three have the same length (a prompt edit changes `messages[0]` and
+ * leaves `messages[1]` as the original has it), and are replaced whole otherwise.
+ * Every replaced path is pushed to `changed`.
+ *
+ * For example original `{a: 1, b: 2}`, baseline `{a: 1}`, edited `{a: 3}` gives
+ * `{a: 3, b: 2}` and `changed = ["a"]`.
+ */
+export function mergeJson3(original, baseline, edited, changed, path = '') {
+    if (stable(baseline) === stable(edited))
+        return jsonClone(original);
+    if (isObject(original) && isObject(baseline) && isObject(edited)) {
+        const out = { ...jsonClone(original) };
+        for (const k of new Set([...Object.keys(baseline), ...Object.keys(edited)])) {
+            if (stable(baseline[k]) === stable(edited[k]))
+                continue;
+            const at = path ? `${path}.${k}` : k;
+            if (edited[k] === undefined) {
+                delete out[k];
+                changed.push(at);
+            }
+            else {
+                out[k] = mergeJson3(original[k], baseline[k], edited[k], changed, at);
+            }
+        }
+        return out;
+    }
+    if (Array.isArray(original) && Array.isArray(baseline) && Array.isArray(edited)
+        && original.length === baseline.length && baseline.length === edited.length) {
+        return original.map((o, i) => mergeJson3(o, baseline[i], edited[i], changed, `${path}[${i}]`));
+    }
+    changed.push(path || '(whole file)');
+    return jsonClone(edited);
+}
+/** A resource file's identity: its content without the `id` (and directory) the writer derives. */
+function resourceIdentities(files) {
+    const out = new Map();
+    for (const [path, json] of Object.entries(files)) {
+        if (!/\/resources\/[^/]+\/resource\.json$/.test(path))
+            continue;
+        const { id: _id, ...rest } = (isObject(json) ? json : {});
+        out.set(stable(rest), path);
+    }
+    return out;
+}
+/**
+ * The resource files `to` adds or removes relative to `from`, by identity
+ * (content without `id`), as `added <path>; removed <path>`; `undefined` when
+ * the sets are equal.
+ */
+function resourceChanges(from, to) {
+    const a = resourceIdentities(from);
+    const b = resourceIdentities(to);
+    const out = [
+        ...[...b.keys()].filter((k) => !a.has(k)).map((k) => `added ${b.get(k)}`),
+        ...[...a.keys()].filter((k) => !b.has(k)).map((k) => `removed ${a.get(k)}`),
+    ];
+    return out.length > 0 ? out.join('; ') : undefined;
+}
+/** 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';
+}
+const finding = (message) => ({ kind: 'agent-sidecar', message, refuses: true });
+/**
+ * The sidecar files the merged flow needs written beside it, and what merge could
+ * not carry. `merged` is `mergeFlow`'s result. An agent is new when the
+ * original side has no `<source>/agent.json` for it.
+ */
+export function mergeAgentSidecars(merged, sources) {
+    const writes = [];
+    const findings = [];
+    for (const [source, node] of agentSources(merged)) {
+        const edited = sources.edited(source);
+        if (edited === undefined)
+            continue; // the edited compile wrote no sidecar here: nothing to carry
+        const orig = sources.original(source);
+        const agentPath = `${source}/agent.json`;
+        if (orig === undefined) {
+            // An agent the edit added (or one whose original sidecar is missing):
+            // the edited compile's files are the only ones there are.
+            for (const [path, json] of Object.entries(edited))
+                writes.push({ path, json: jsonClone(json), carried: ['new agent'] });
+            continue;
+        }
+        const base = sources.baseline?.(source);
+        if (base === undefined) {
+            if (stable(orig[agentPath]) !== stable(edited[agentPath])) {
+                const why = sources.baselineMissing
+                    ?? `the baseline compile wrote no ${agentPath}`;
+                findings.push(finding(`agent "${node.id}": the edited ${agentPath} differs from the original's, and merge cannot tell an edit `
+                    + `from the round trip's own changes: ${why}. The change is NOT carried; the original's ${agentPath} stays. `
+                    + 'Compile the baseline and the edited source into two different directories and pass --baseline.'));
+            }
+            // A context or tool added or removed changes no agent.json, so compare the
+            // resource files too, against the original's this time.
+            const res = resourceChanges(orig, edited);
+            if (res) {
+                const why = sources.baselineMissing ?? 'the baseline compile wrote no sidecars';
+                findings.push(finding(`agent "${node.id}": the edited resource files differ from the original's (${res}), and merge cannot tell `
+                    + `an edit from the round trip's own changes: ${why}. Merge does not carry resource files; the original's `
+                    + 'stay as they are.'));
+            }
+            continue;
+        }
+        // agent.json: the author's delta, applied onto the original.
+        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.'));
+            }
+            else if (stable(next) !== stable(orig[agentPath])) {
+                writes.push({ path: agentPath, json: next, carried: changed });
+            }
+        }
+        // Resources: report a changed set; the canvas names them by its own ids, so
+        // the edited files cannot be mapped onto the original's directories.
+        const res = resourceChanges(base, edited);
+        if (res) {
+            findings.push(finding(`agent "${node.id}": the edit changes its resource files (${res}). Merge does not carry resource files; `
+                + 'the original\'s stay as they are. Make that change on the canvas.'));
+        }
+    }
+    return { writes, findings };
+}

package/dist/merge.d.ts

@@ -74,7 +74,9 @@
  * checked for an edge that leaves a handle its kept source node does not
  * declare. See merge-roundtrip.ts.
  */
+import { type MergeSidecarSources, type SidecarWrite } from './merge-sidecars.js';
 export { MergeRefusedError, type MergeFinding } from './merge-roundtrip.js';
+export type { MergeSidecarSources, SidecarSet, SidecarWrite } from './merge-sidecars.js';
 interface AnyNode {
     id: string;
     type: string;
@@ -143,8 +145,9 @@ export interface MergeOptions {
     warn?: (message: string) => void;
     /**
      * Refuse instead of warn: when the merged file differs from the original
-     * where the author made no edit, throw {@link MergeRefusedError} listing every
-     * such finding, and return nothing. The other findings still go to `warn`.
+     * where the author made no edit, or (with sidecars, `mergeFlowWithSidecars`)
+     * would leave out an agent sidecar edit, throw {@link MergeRefusedError}
+     * listing every such finding, and return nothing. The other findings still go to `warn`.
      * Two findings never refuse, because the merged file does what the original
      * does: an End the compile appends to a tail the original leaves open, and a
      * binding row the round trip drops (merge keeps the original's). Meant to be
@@ -162,3 +165,15 @@ export interface MergeOptions {
  */
 export declare function nodesTakenFromEdited(original: AnyFlow, edited: AnyFlow, baseline?: AnyFlow): string[];
 export declare function mergeFlow(original: AnyFlow, edited: AnyFlow, options?: MergeOptions): AnyFlow;
+/**
+ * `mergeFlow`, plus the agent sidecar files the merged flow needs written beside
+ * it (#1207). An inline agent's prompts and settings live only in
+ * `<source>/agent.json`, so an edit to them changes no node; this carries the
+ * author's change to that file onto the original's copy. What it cannot carry
+ * becomes a finding: warned, and refused under `strict`, with the flow's own
+ * findings. See merge-sidecars.ts.
+ */
+export declare function mergeFlowWithSidecars(original: AnyFlow, edited: AnyFlow, sidecars: MergeSidecarSources, options?: MergeOptions): {
+    flow: AnyFlow;
+    sidecars: SidecarWrite[];
+};

package/dist/merge.js

@@ -79,6 +79,7 @@ import { jsonClone } from './core/json-file.js';
 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';
 export { MergeRefusedError } from './merge-roundtrip.js';
 function byId(nodes) {
     return new Map((nodes ?? []).map((n) => [n.id, n]));
@@ -145,6 +146,34 @@ function layoutNodesOf(f) {
     return nodes && typeof nodes === 'object' && !Array.isArray(nodes) ? nodes : undefined;
 }
 export function mergeFlow(original, edited, options = {}) {
+    const { result, findings } = mergeFlowFindings(original, edited, options);
+    reportOrRefuse(findings, options);
+    return result;
+}
+/**
+ * `mergeFlow`, plus the agent sidecar files the merged flow needs written beside
+ * it (#1207). An inline agent's prompts and settings live only in
+ * `<source>/agent.json`, so an edit to them changes no node; this carries the
+ * author's change to that file onto the original's copy. What it cannot carry
+ * becomes a finding: warned, and refused under `strict`, with the flow's own
+ * findings. See merge-sidecars.ts.
+ */
+export function mergeFlowWithSidecars(original, edited, sidecars, options = {}) {
+    const { result, findings } = mergeFlowFindings(original, edited, options);
+    const carried = mergeAgentSidecars(result, sidecars);
+    reportOrRefuse([...findings, ...carried.findings], options);
+    return { flow: result, sidecars: carried.writes };
+}
+/** Warn every finding; under `strict`, throw over the refusing ones (and still warn the rest). */
+function reportOrRefuse(findings, options) {
+    const refusing = options.strict ? findings.filter((f) => f.refuses) : [];
+    for (const f of findings)
+        if (!refusing.includes(f))
+            options.warn?.(f.message);
+    if (refusing.length > 0)
+        throw new MergeRefusedError(refusing);
+}
+function mergeFlowFindings(original, edited, options) {
     const result = jsonClone(original);
     const origNodes = byId(original.nodes);
     const baseNodes = byId(options.baseline?.nodes);
@@ -219,19 +248,12 @@ export function mergeFlow(original, edited, options = {}) {
         result.version = edited.version;
     }
     // ── What the no-edit round trip changed, and what mixing sources broke. ──
-    // Under strict, the findings that do not refuse are still warned, so a
-    // refused run shows them too.
+    // The caller warns them, or refuses under strict (`reportOrRefuse`).
     const findings = [
         ...(options.baseline ? roundTripFindings(original, options.baseline, result) : []),
         ...mergedFileFindings(result, original),
     ];
-    const refusing = options.strict ? findings.filter((f) => f.refuses) : [];
-    for (const f of findings)
-        if (!refusing.includes(f))
-            options.warn?.(f.message);
-    if (refusing.length > 0)
-        throw new MergeRefusedError(refusing);
-    return result;
+    return { result, findings };
 }
 /**
  * The root edges with their edited ids, except that an edge with no id, or with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.30.0",
+  "version": "6.30.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "5b38f3fae80cbcb874c6d92afb49690b77656caf"
+  "gitref": "07dd8e31058cf19c3db3a504b6e2bbb56cf980d2"
 }