@uipath/maestro-builder-sdk 6.29.2 → 6.30.1

package/dist/api-index.md

@@ -150,7 +150,7 @@ could hand you spans for a version you do not have.
 | `HitlAssigneeType` | type | `dist/nodes/hitl/flow/spec.d.ts:16-23` | Supporting types | How the task is assigned, the platform's own vocabulary (canvas `HITL_ASSIGNEE_TYPE`): `'user'` a single user, `'group'`… |
 | `HitlChannel` | type | `dist/nodes/hitl/flow/spec.d.ts:10-15` | Supporting types | Where the task is delivered. |
 | `HitlConnection` | interface | `dist/nodes/hitl/flow/spec.d.ts:24-32` | Supporting types | A per-channel Integration Service connection (Slack / Teams delivery). |
-| `HitlInputs` | interface | `dist/nodes/hitl/flow/spec.d.ts:186-257` | Option shapes | 11 field(s) |
+| `HitlInputs` | interface | `dist/nodes/hitl/flow/spec.d.ts:186-290` | Option shapes | 12 field(s) |
 | `HitlRecipient` | interface | `dist/nodes/hitl/flow/spec.d.ts:33-69` | Supporting types | Who gets the task and over which channels. |
 | `HitlVariant` | type | `dist/nodes/hitl/flow/spec.d.ts:114-139` | Supporting types | WHICH human-task node type to emit. |
 | `http` | function | `dist/nodes/http/flow/factories.d.ts:7-14` | Actions | Declare an HTTP request action, explicitly choosing standalone or managed. |

package/dist/api-members.md

@@ -5,12 +5,12 @@
 
 # Maestro Builder SDK — member index
 
-**A lookup table of 1118 rows — match one name in it, do not read it.**
+**A lookup table of 1119 rows — match one name in it, do not read it.**
 Grep or search for the member you have; the row it lands on is the whole
 answer. Reading top to bottom costs ~20x what the one row does and tells you
 nothing you asked for.
 
-Every field and method of every exported shape — 1118 across
+Every field and method of every exported shape — 1119 across
 200 interfaces and classes — keyed by the MEMBER's own name.
 
 **Use this when the name you have is a field or a method**, which is usually
@@ -28,7 +28,7 @@ truncated summary would, for less. Read the span.
 Member names repeat across shapes (`name` is declared on 69 of them), so the
 `Declared on` column is what makes a match actionable. For the whole shape
 rather than the one field, look that name up in [`api-index.md`](api-index.md) —
-which is why its span is not repeated on all 1118 rows here.
+which is why its span is not repeated on all 1119 rows here.
 
 **A name that misses both indexes is probably not part of the API.** The one
 that comes up is a RUNTIME output key — a human task's `Action`, a step's
@@ -264,7 +264,7 @@ not find it either.
 | `displayName` | property | `RegistryInputField` | `dist/bpmn/typed-node.d.ts:58` |
 | `displayName` | property | `SlaOpts` | `dist/case/case-sdk.d.ts:170-175` |
 | `displayName` | property | `TriggerMeta` | `dist/core/connectors.d.ts:127-128` |
-| `document` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:252-256` |
+| `document` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:285-289` |
 | `documentClassify` | property | `FlowActionSpecs` | `dist/nodes/document/flow/spec.d.ts:56-59` |
 | `documentId` | property | `DocValidationInputs` | `dist/nodes/hitl/flow/spec.d.ts:84-85` |
 | `doWhile` | method | `StepList` | `dist/flow-sdk.d.ts:1089-1113` |
@@ -420,7 +420,7 @@ not find it either.
 | `height` | property | `StickyNote` | `dist/flow-sdk.d.ts:702-703` |
 | `hidden` | property | `RegistryContextField` | `dist/bpmn/typed-node.d.ts:27` |
 | `hidden` | property | `RegistryInputField` | `dist/bpmn/typed-node.d.ts:61` |
-| `hitl` | property | `FlowActionSpecs` | `dist/nodes/hitl/flow/spec.d.ts:260-263` |
+| `hitl` | property | `FlowActionSpecs` | `dist/nodes/hitl/flow/spec.d.ts:293-296` |
 | `http` | property | `FlowActionSpecs` | `dist/nodes/http/flow/spec.d.ts:145-148` |
 | `http` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2366-2400` |
 | `humanTask` | method | `ScopeBuilder` | `dist/bpmn/bpmn-sdk.d.ts:2595-2646` |
@@ -549,6 +549,7 @@ not find it either.
 | `layout` | property | `BuiltFlow` | `dist/flow-sdk.d.ts:754-755` |
 | `layout` | method | `CaseBuilder` | `dist/case/case-sdk.d.ts:1139-1159` |
 | `layout` | method | `FlowBuilder` | `dist/flow-sdk.d.ts:1288-1298` |
+| `legacyCompleted` | property | `HitlInputs` | `dist/nodes/hitl/flow/spec.d.ts:252-284` |
 | `limit` | property | `DataFabricReadInputs` | `dist/nodes/data-fabric/flow/spec.d.ts:95-100` |
 | `limit` | property | `DoWhileOptions` | `dist/flow-sdk.d.ts:503-504` |
 | `literal` | property | `Expr` | `dist/core/expr.d.ts:18` |

package/dist/check.js

@@ -342,9 +342,12 @@ function checkFlow(built, ancestors, opts = {}) {
                             level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
                             message: `Port "${s.port}" routes a per-outcome exit, but human task "${prevAction?.name}" `
                                 + `has none — ${ids.length === 0 ? 'it declares no outcomes'
-                                    : `the '${prevSpec.inputs?.variant}' variant reads its outcomes from its app`}, so its single `
+                                    : model.legacyCompleted ? 'it sets legacyCompleted: true'
+                                        : `the '${prevSpec.inputs?.variant}' variant reads its outcomes from its app`}, so its single `
                                 + `exit is 'completed'.`,
-                            suggestion: `route on out('${prevAction?.name}', 'Action') downstream`,
+                            suggestion: model.legacyCompleted
+                                ? 'drop `legacyCompleted` (and set outcomePorts: true to route each outcome)'
+                                : `route on out('${prevAction?.name}', 'Action') downstream`,
                         });
                     }
                     else if (!ids.includes(want)) {
@@ -425,7 +428,11 @@ function checkFlow(built, ancestors, opts = {}) {
                     const allEnd = outcomes.length > 0
                         && outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
                     // `.stepSwitch` routes every outcome as an arm, so it never belongs here.
+                    // Nor does a `legacyCompleted` task: only its primary outcome continues,
+                    // so no downstream switch can reach the others, and HITL_LEGACY_COMPLETED
+                    // already says so.
                     if (outcomes.length > 1 && !allEnd && s0.kind !== 'stepSwitch'
+                        && s.spec.inputs?.legacyCompleted !== true
                         && !hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                         hitlChoiceNoPorts.set(s.name, {
                             names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),

package/dist/core/hitl-routing.d.ts

@@ -68,6 +68,15 @@
  * `exposeError: true` or `outcomePorts: true` select `per-outcome` on every node
  * type, including the two app-backed variants, so that `serialize` and `check`
  * refuse them there with their own message rather than silently ignoring them.
+ *
+ * **`legacyCompleted: true`** is the one way to keep a task with outcomes on the
+ * `completed` handle: the `placeholder` shape, marked `legacyCompleted`. It
+ * exists so a file saved before flow-workbench #3512, whose task leaves on one
+ * `completed` edge, round-trips through decompile and compile unchanged
+ * (flow-builder-sdk#1197). It is the file's shape, not one to author: the
+ * product runs that edge as the PRIMARY outcome only, and `check` says so
+ * (HITL_LEGACY_COMPLETED). `serialize`'s edge guard below exempts exactly the
+ * nodes that asked for it.
  */
 /**
  * The fields of a human task's inputs the routing model reads — structural, so
@@ -83,6 +92,7 @@ export interface HitlRoutingInputs {
     }>;
     readonly outcomePorts?: boolean;
     readonly exposeError?: boolean;
+    readonly legacyCompleted?: boolean;
 }
 /**
  * An outcome's stable id — the slug that names its `outcome-<id>` port.
@@ -114,6 +124,7 @@ export interface HitlOutcomeExit {
 export type HitlFanOutReason = 'outcomePorts: false' | 'quick-form' | 'pinned' | 'one outcome' | 'every outcome ends';
 export type HitlExitModel = {
     shape: 'placeholder';
+    legacyCompleted?: true;
 } | {
     shape: 'every-outcome';
     exits: HitlOutcomeExit[];
@@ -151,14 +162,17 @@ type EdgeLike = {
  * the product does not draw, and an `outcome-<id>` naming no declared outcome is
  * one `flow validate` refuses ("Edge references undeclared source handle"). A
  * real outcome named "Completed" is `outcome-completed`, which is fine — the
- * bare `completed` never is.
+ * bare `completed` never is, unless the task asked for it with
+ * `legacyCompleted: true` (`legacyCompleted` here).
  */
-export declare function hitlExitViolation(node: NodeLike, port: string): string | undefined;
+export declare function hitlExitViolation(node: NodeLike, port: string, legacyCompleted?: boolean): string | undefined;
 /**
  * The post-emit half of the guard: every edge of an emitted scope, whatever
  * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
  * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
  * these would ship a flow that validates and then drops outcomes at run time.
+ * `legacyCompleted` holds the ids of the tasks that set `legacyCompleted: true`,
+ * whose `completed` edge is the author's explicit choice.
  */
-export declare function assertHitlExitInvariant(nodes: readonly NodeLike[], edges: readonly EdgeLike[]): void;
+export declare function assertHitlExitInvariant(nodes: readonly NodeLike[], edges: readonly EdgeLike[], legacyCompleted?: ReadonlySet<string>): void;
 export {};

package/dist/core/hitl-routing.js

@@ -57,6 +57,8 @@ export function hitlExitModel(inputs, pinnedVersion) {
         return { shape: 'per-outcome', exits };
     if (!hitlDerivesOutcomeHandles(inputs?.variant) || exits.length === 0)
         return { shape: 'placeholder' };
+    if (inputs?.legacyCompleted === true)
+        return { shape: 'placeholder', legacyCompleted: true };
     const every = (why) => ({ shape: 'every-outcome', exits, why });
     if (inputs?.outcomePorts === false)
         return every('outcomePorts: false');
@@ -95,9 +97,10 @@ function outcomeIdsOf(node) {
  * the product does not draw, and an `outcome-<id>` naming no declared outcome is
  * one `flow validate` refuses ("Edge references undeclared source handle"). A
  * real outcome named "Completed" is `outcome-completed`, which is fine — the
- * bare `completed` never is.
+ * bare `completed` never is, unless the task asked for it with
+ * `legacyCompleted: true` (`legacyCompleted` here).
  */
-export function hitlExitViolation(node, port) {
+export function hitlExitViolation(node, port, legacyCompleted = false) {
     if (!OUTCOME_HANDLE_NODE_TYPES.has(String(node.type)))
         return undefined;
     const ids = outcomeIdsOf(node);
@@ -105,6 +108,8 @@ export function hitlExitViolation(node, port) {
         return undefined;
     const declared = ids.map((i) => `outcome-${i}`).join(', ');
     if (port === 'completed') {
+        if (legacyCompleted)
+            return undefined;
         return `human task "${String(node.id)}" has outcomes (${declared}), so the product draws no `
             + `'completed' handle on it — an edge there is remapped to the primary outcome and every other `
             + `outcome loses its path.`;
@@ -119,14 +124,16 @@ export function hitlExitViolation(node, port) {
  * path produced it (a tail, a `.stepToList` seed, a parked `.stepToRef`), is held
  * to {@link hitlExitViolation}. Fails closed — a serializer that emitted one of
  * these would ship a flow that validates and then drops outcomes at run time.
+ * `legacyCompleted` holds the ids of the tasks that set `legacyCompleted: true`,
+ * whose `completed` edge is the author's explicit choice.
  */
-export function assertHitlExitInvariant(nodes, edges) {
+export function assertHitlExitInvariant(nodes, edges, legacyCompleted = new Set()) {
     const byId = new Map(nodes.map((n) => [String(n.id), n]));
     for (const e of edges) {
         const node = byId.get(String(e.sourceNodeId));
         if (!node)
             continue;
-        const why = hitlExitViolation(node, String(e.sourcePort));
+        const why = hitlExitViolation(node, String(e.sourcePort), legacyCompleted.has(String(e.sourceNodeId)));
         if (why)
             throw new Error(`serialize: ${why}`);
     }

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/flow-node-type.d.ts

@@ -52,6 +52,12 @@ export interface FlowNodeContribution extends Omit<NodeContribution, 'definition
         readonly port: string;
         readonly endsRun?: boolean;
     }>;
+    /**
+     * The node is a human task with outcomes that leaves on its legacy `completed`
+     * handle, because its author set `legacyCompleted: true`. Exempts it from the
+     * guard that refuses a `completed` edge on such a task (`hitlExitViolation`).
+     */
+    legacyCompleted?: boolean;
     /**
      * `outputs` REPLACES the definition's `outputDefinition` on the node instead of
      * being merged over it — for an instance whose output slots are its own (a

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/dist/nodes/hitl/flow/check.js

@@ -6,6 +6,8 @@ import { hitlDerivesOutcomeHandles, outcomeIdOf } from '../../../core/hitl-routi
 export const HITL_DIAGNOSTICS = {
     HITL_VARIANT_UNKNOWN: { severity: 'error', summary: 'a variant that names no human-task node type' },
     HITL_OUTCOME_PORTS_VARIANT: { severity: 'error', summary: 'exposeError or outcomePorts on a variant that cannot honour it' },
+    HITL_LEGACY_COMPLETED: { severity: 'warning', summary: "a task with outcomes that leaves on the legacy 'completed' handle" },
+    HITL_LEGACY_COMPLETED_CONFLICT: { severity: 'error', summary: 'legacyCompleted with outcomePorts or exposeError, or where it changes nothing' },
     HITL_DOCUMENT_WITHOUT_VARIANT: { severity: 'error', summary: 'a document on a task that is not a validation station' },
     HITL_DOCVAL_WITH_FIELDS: { severity: 'error', summary: 'form fields on a validation station' },
     HITL_DOCVAL_NO_DOCUMENT: { severity: 'error', summary: 'a validation station with no document' },
@@ -86,6 +88,28 @@ export function checkHitl(inputs, ctx) {
             : `Route on out('${step}', 'Action') downstream.`);
         return;
     }
+    // `legacyCompleted: true` keeps a pre-#3512 file's `completed` edge (#1197).
+    // It is the file's shape, so it compiles, but what it does at run time is
+    // rarely what the author wants, and `flow validate` says nothing about it.
+    if (inputs?.legacyCompleted === true) {
+        const outcomes = Array.isArray(inputs?.outcomes) ? inputs.outcomes : [];
+        if (inputs?.outcomePorts !== undefined || inputs?.exposeError === true) {
+            at('HITL_LEGACY_COMPLETED_CONFLICT', `Human task "${step}" sets legacyCompleted: true, which leaves it on its single 'completed' handle, and also `
+                + `${inputs?.exposeError === true ? 'exposeError' : 'outcomePorts'}, which asks for per-outcome exits.`, 'Drop `legacyCompleted`.');
+            return;
+        }
+        if (!hitlDerivesOutcomeHandles(variant) || outcomes.length === 0) {
+            at('HITL_LEGACY_COMPLETED_CONFLICT', `Human task "${step}" sets legacyCompleted: true, but ${outcomes.length === 0 ? 'it has no outcomes'
+                : `its variant is "${variant}", which reads its outcomes from its app`}, so 'completed' is already its only exit.`, 'Drop `legacyCompleted`.');
+            return;
+        }
+        const first = typeof outcomes[0] === 'string' ? outcomes[0] : outcomes[0]?.name;
+        at('HITL_LEGACY_COMPLETED', `Human task "${step}" leaves on the legacy 'completed' handle (legacyCompleted: true). Studio Web and the `
+            + `runtime read that edge as the primary outcome, ${JSON.stringify(String(first ?? ''))}, only`
+            + (outcomes.length > 1 ? ': when the reviewer picks any other outcome, the run stops at the task.' : '.'), outcomes.length > 1
+            ? 'outcomePorts: false (every outcome continues to the next step), or outcomePorts: true / .stepSwitch (route each one)'
+            : 'Drop `legacyCompleted`: one outcome continues to the next step on its own handle.');
+    }
     if (inputs?.document !== undefined && !isDocval) {
         at('HITL_DOCUMENT_WITHOUT_VARIANT', `Human task "${step}" names a document to validate, but its variant is `
             + `${variant === undefined ? 'the default node type' : `"${variant}"`} — only the validation `

package/dist/nodes/hitl/flow/node-type.js

@@ -252,6 +252,12 @@ function hitlExits({ inputs }, pinnedVersion) {
     if (model.shape === 'placeholder') {
         // WHY it has no outcome exits decides what the author can do about it, so
         // the caller gets the specific one rather than "ports are off".
+        if (model.legacyCompleted) {
+            return {
+                reason: "legacyCompleted: true leaves it on its single 'completed' exit",
+                suggestion: 'Drop `legacyCompleted` to route its outcomes.',
+            };
+        }
         if ((inputs?.outcomes ?? []).length === 0) {
             return { reason: 'it declares no outcomes', suggestion: `outcomes: ['Approve', 'Reject']` };
         }
@@ -413,24 +419,24 @@ function liftHitl(node, typeName, ctx) {
     const outcomePorts = (typeName === BASE && version === '1.1')
         || (derivesHandles && !versionRoutes && !ctx.convergedFanOut()
             && outPorts.some((p) => p.startsWith('outcome-')));
-    // A lone `completed` edge on a task with several outcomes is the shape the
-    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
-    // unconditioned, so every outcome continued down it; since then Studio Web and
-    // the converter remap it to the primary outcome only. Recompiling writes one
-    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
-    // this is the one place decompile→compile is deliberately not exact. Say so.
-    const legacyCompleted = derivesHandles && outcomeIdsOfNode(n).length > 1 && outPorts.includes('completed');
-    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
-    // continues to the next step". Say so in the source with `outcomePorts: false`
-    // rather than leaving it to the `{ version }` pin, so the intent survives an
-    // author dropping the pin.
-    const fanOut = !outcomePorts && derivesHandles && !versionRoutes && outcomeIdsOfNode(n).length > 1
-        && (legacyCompleted || ctx.convergedFanOut());
+    // A `completed` edge on a task with outcomes is the shape the designer
+    // stopped drawing: before flow-workbench #3512 (09-08) it was unconditioned,
+    // so every outcome continued down it; since then Studio Web and the converter
+    // remap it to the primary outcome only. The source keeps it as it is,
+    // `legacyCompleted: true`, so a round trip with no edits writes the same edge
+    // back (#1197) and the author decides what it should mean.
+    const legacyCompleted = derivesHandles && !versionRoutes && outcomeIdsOfNode(n).length > 0
+        && outPorts.includes('completed');
+    // A converged fan-out means "every outcome continues to the next step". Say so
+    // in the source with `outcomePorts: false` rather than leaving it to the
+    // `{ version }` pin, so the intent survives an author dropping the pin.
+    const fanOut = !outcomePorts && !legacyCompleted && derivesHandles && !versionRoutes
+        && outcomeIdsOfNode(n).length > 1 && ctx.convergedFanOut();
     if (legacyCompleted) {
         ctx.warn(`human task ${JSON.stringify(n.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
-            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
-            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
-            + `before flow-workbench #3512.`);
+            + `once a task has outcomes: it runs that edge as the primary outcome only, so any other outcome stops the run. `
+            + `The source keeps it (legacyCompleted: true), so recompiling writes the same edge. To continue every outcome, `
+            + `replace it with outcomePorts: false; to route each one, outcomePorts: true or .stepSwitch.`);
     }
     const title = plain(i.title);
     const priority = plain(i.priority);
@@ -447,7 +453,8 @@ function liftHitl(node, typeName, ctx) {
         // there is serialize's own, not the author's.
         ...(fields.length || (variant !== 'action-app' && variant !== 'document-validation') ? { fields } : {}),
         outcomes,
-        ...(outcomePorts ? { outcomePorts: true } : fanOut ? { outcomePorts: false } : {}),
+        ...(legacyCompleted ? { legacyCompleted: true }
+            : outcomePorts ? { outcomePorts: true } : fanOut ? { outcomePorts: false } : {}),
         ...(version === '1.2' ? { exposeError: true } : {}),
     };
     return { kind: 'hitl', inputs: lifted };
@@ -511,6 +518,7 @@ function printHitl({ inputs }, ctx) {
             ['outcomes', `[${outcomes.join(', ')}]`],
             ['outcomePorts', h.outcomePorts === true ? 'true' : h.outcomePorts === false ? 'false' : undefined],
             ['exposeError', h.exposeError ? 'true' : undefined],
+            ['legacyCompleted', h.legacyCompleted ? 'true' : undefined],
         ],
     };
 }
@@ -535,6 +543,14 @@ function hitlAt(typeName, version, factory) {
                 throw new Error(`"${ctx.step}": outcomePorts: true, but the '${inputs?.variant}' variant reads its outcomes `
                     + `from its app and leaves on its single 'completed' exit. Route on out('${ctx.step}', 'Action') downstream.`);
             }
+            if (inputs?.legacyCompleted === true && (inputs?.outcomePorts !== undefined || inputs?.exposeError === true)) {
+                throw new Error(`"${ctx.step}": legacyCompleted: true leaves the task on its single 'completed' handle, so it cannot also `
+                    + `${inputs?.exposeError === true ? 'expose the error output (exposeError)' : 'set outcomePorts'}. Drop one.`);
+            }
+            if (inputs?.legacyCompleted === true && typeName === BASE && (pinned === '1.1' || pinned === '1.2')) {
+                throw new Error(`"${ctx.step}": legacyCompleted: true, but { version: '${pinned}' } pins the task's per-outcome definition, `
+                    + `which has no 'completed' handle (flow validate refuses the edge). Drop the pin or legacyCompleted.`);
+            }
             if (inputs?.exposeError === true && pinned !== undefined && pinned !== '1.2') {
                 throw new Error(`"${ctx.step}": exposeError needs the task's 1.2 definition, but { version: '${pinned}' } pins it. `
                     + `Drop the pin or match it.`);
@@ -554,8 +570,9 @@ function hitlAt(typeName, version, factory) {
                 return { ...contribution, fanOut: exitModel.exits.map((e) => ({ port: e.port, ...(e.endsProcess ? { endsRun: true } : {}) })) };
             }
             // Every human-task definition declares one static source handle,
-            // `completed`: the real exit on an app-backed task and on one with no outcomes.
-            return { ...contribution, port: 'completed' };
+            // `completed`: the real exit on an app-backed task and on one with no
+            // outcomes, and the author's explicit choice with `legacyCompleted: true`.
+            return { ...contribution, port: 'completed', ...(exitModel.legacyCompleted ? { legacyCompleted: true } : {}) };
         },
         deserialize: (node, ctx) => liftHitl(node, typeName, ctx),
         print: printHitl,

package/dist/nodes/hitl/flow/spec.d.ts

@@ -249,6 +249,39 @@ export interface HitlInputs {
      * {@link HitlInputs.outcomePorts | outcomePorts}. Default node only.
      */
     exposeError?: boolean;
+    /**
+     * Leave on the task's legacy `completed` handle, as a file saved before
+     * Studio Web drew one handle per outcome does. `decompile` writes this for
+     * such a file, so a round trip with no edits gives its `completed` edge back
+     * unchanged instead of rewriting it into one `outcome-<id>` edge per outcome.
+     *
+     * Not for new flows. Studio Web and the runtime read a `completed` edge on a
+     * task with outcomes as the PRIMARY (first) outcome only: when the reviewer
+     * picks any other outcome, that path has no edge and the run stops there.
+     * `check` warns (`HITL_LEGACY_COMPLETED`). To continue every outcome to the
+     * next step, drop this and set
+     * {@link HitlInputs.outcomePorts | outcomePorts}`: false`; to route each
+     * outcome, use `outcomePorts: true` or `.stepSwitch`.
+     *
+     * Only on the default node and `'quick-form'` with at least one outcome (the
+     * other variants always leave on `completed`), and not with `outcomePorts` or
+     * `exposeError`.
+     *
+     * @example
+     * ```ts
+     * // Decompiled from a task whose one edge leaves on `completed`.
+     * export default flow('review')
+     *   .step('review1', hitl({
+     *     variant: 'quick-form',
+     *     fields: [{ id: 'comments', type: 'text', direction: 'output' }],
+     *     outcomes: ['Submit', 'Reject'],
+     *     legacyCompleted: true,
+     *   }))
+     *   .step('approved1', script({ code: 'return 1;' }))
+     *   .build();
+     * ```
+     */
+    legacyCompleted?: boolean;
     /**
      * The document to validate. Required by — and only legal with —
      * `variant: 'document-validation'`.

package/dist/serialize.js

@@ -4423,6 +4423,13 @@ export function serialize(built, opts = {}) {
      * `.stepToRef` rejoins now do come through here, #938).
      */
     const hitlNodes = new Map();
+    /**
+     * Human tasks with outcomes that set `legacyCompleted: true`: they leave on
+     * `completed` by the author's choice, so the guard exempts that one port
+     * (flow-builder-sdk#1197). They are not tracked in `hitlNodes`, whose tails are
+     * outcome edges; theirs is the one `completed` edge.
+     */
+    const legacyCompletedNodes = new Set();
     /** Step name → node id of a step whose every forward exit is templated (see `contributionPort`). */
     const routerNodes = new Map();
     /**
@@ -4436,7 +4443,7 @@ export function serialize(built, opts = {}) {
     const hitlEndExits = [];
     function addEdge(scope, from, toNode, toPort = 'input') {
         const hitlNode = hitlNodes.get(from.node);
-        const refused = hitlNode ? hitlExitViolation(hitlNode, from.port) : undefined;
+        const refused = hitlNode ? hitlExitViolation(hitlNode, from.port, legacyCompletedNodes.has(from.node)) : undefined;
         if (refused)
             throw new Error(`serialize: ${refused}`);
         scope.edges.push({ id: `edge_${edgeSeq++}`, sourceNodeId: from.node, sourcePort: from.port, targetNodeId: toNode, targetPort: toPort });
@@ -4612,7 +4619,7 @@ export function serialize(built, opts = {}) {
         for (const vd of childGlobals.vars)
             globals.push({ id: vd.name, name: vd.name, direction: 'inout', type: vd.type, ...varMeta(vd) });
         resolveRejoins(scope, addEdge);
-        assertHitlExitInvariant(scope.nodes, scope.edges);
+        assertHitlExitInvariant(scope.nodes, scope.edges, legacyCompletedNodes);
         typeAgentInputSchemas(scope, globals);
         emitStickyNotes(child, scope, claimNoteId);
         const layoutEdges = applyAuthorLayout(child.layout, scope, `subflow "${nodeId}"`);
@@ -4815,7 +4822,9 @@ export function serialize(built, opts = {}) {
         // edge out of it is held to that rule (`hitlExitViolation`, in addEdge), and
         // the step list treats its tails as outcome edges. A rawNode of the type is
         // not one: it routes by the port lists its author wrote.
-        if (o.trackOutcomes && OUTCOME_HANDLE_NODE_TYPES.has(o.typeName))
+        if (o.trackOutcomes && contribution.legacyCompleted)
+            legacyCompletedNodes.add(id);
+        else if (o.trackOutcomes && OUTCOME_HANDLE_NODE_TYPES.has(o.typeName))
             hitlNodes.set(id, node);
         for (const t of o.tails)
             addEdge(scope, t, id);
@@ -5979,10 +5988,13 @@ export function serialize(built, opts = {}) {
      * Refuse a side exit on a human task's port that the step's tails already
      * continue from: that would put two edges on one port (flow-builder-sdk#741).
      * After a fan-out task that is EVERY outcome port. `check` reports the same
-     * as HITL_OUTCOME_PORTS_OFF; this is the compile-side half.
+     * as HITL_OUTCOME_PORTS_OFF; this is the compile-side half. A
+     * `legacyCompleted` task counts too: its main path leaves on `completed`, so a
+     * side route there is the same second edge.
      */
     function refuseRewire(method, port, source, tails) {
-        if (!hitlNodes.has(tails[0]?.node ?? '') || !tails.some((t) => t.port === port))
+        const node = tails[0]?.node ?? '';
+        if (!(hitlNodes.has(node) || legacyCompletedNodes.has(node)) || !tails.some((t) => t.port === port))
             return;
         throw new Error(tails.length > 1
             ? `${method}('${port}', …) after human task "${source}": every outcome already continues to the next `
@@ -6641,7 +6653,7 @@ export function serialize(built, opts = {}) {
         }
     }
     resolveRejoins(root, addEdge);
-    assertHitlExitInvariant(root.nodes, root.edges);
+    assertHitlExitInvariant(root.nodes, root.edges, legacyCompletedNodes);
     typeAgentInputSchemas(root, globals);
     emitStickyNotes(built, root, claimNoteId);
     const rootLayoutEdges = applyAuthorLayout(built.layout, root, `flow "${built.id}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.29.2",
+  "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": "b0d822e147a21ef1051b36c474b303839e980b13"
+  "gitref": "07dd8e31058cf19c3db3a504b6e2bbb56cf980d2"
 }