@uipath/maestro-builder-sdk 6.16.14 → 6.17.0

package/dist/core-definitions.json

@@ -8852,6 +8852,216 @@
       ]
     }
   },
+  "uipath.agent.autonomous@1.2": {
+    "nodeType": "uipath.agent.autonomous",
+    "version": "1.2",
+    "category": "agent",
+    "description": "AI agent that completes tasks autonomously",
+    "tags": [
+      "agentic",
+      "ai",
+      "autonomous",
+      "agent"
+    ],
+    "sortOrder": 5,
+    "supportsErrorHandling": true,
+    "display": {
+      "label": "Autonomous Agent",
+      "icon": "autonomous-agent",
+      "shape": "rectangle"
+    },
+    "handleConfiguration": [
+      {
+        "position": "top",
+        "handles": [
+          {
+            "id": "escalation",
+            "type": "source",
+            "handleType": "artifact",
+            "label": "Escalations",
+            "showButton": true,
+            "constraints": {
+              "allowedTargets": [
+                {
+                  "nodeType": "uipath.agent.resource.escalation"
+                },
+                {
+                  "nodeType": "uipath.agent.resource.escalation.*"
+                }
+              ],
+              "validationMessage": "Only Agent Escalation nodes can connect here"
+            }
+          }
+        ]
+      },
+      {
+        "position": "bottom",
+        "handles": [
+          {
+            "id": "context",
+            "type": "source",
+            "handleType": "artifact",
+            "label": "Context",
+            "showButton": true,
+            "constraints": {
+              "allowedTargets": [
+                {
+                  "nodeType": "uipath.agent.resource.context.*"
+                }
+              ],
+              "validationMessage": "Only Context resource nodes can connect here"
+            }
+          },
+          {
+            "id": "tool",
+            "type": "source",
+            "handleType": "artifact",
+            "label": "Tools",
+            "showButton": true,
+            "constraints": {
+              "allowedTargets": [
+                {
+                  "nodeType": "uipath.agent.resource.tool.*"
+                }
+              ],
+              "validationMessage": "Only Tool resource nodes can connect here"
+            }
+          }
+        ]
+      },
+      {
+        "position": "left",
+        "handles": [
+          {
+            "id": "input",
+            "type": "target",
+            "handleType": "input"
+          }
+        ]
+      },
+      {
+        "position": "right",
+        "handles": [
+          {
+            "id": "success",
+            "type": "source",
+            "handleType": "output",
+            "isDefaultForType": true
+          },
+          {
+            "id": "error",
+            "type": "source",
+            "handleType": "output",
+            "label": "Error",
+            "visible": "{inputs.errorHandlingEnabled}",
+            "constraints": {
+              "maxConnections": 1
+            }
+          }
+        ]
+      }
+    ],
+    "inputDefinition": {
+      "type": "object",
+      "properties": {
+        "systemPrompt": {
+          "type": "string",
+          "minLength": 1,
+          "errorMessage": {
+            "minLength": "System prompt is required"
+          }
+        },
+        "userPrompt": {
+          "type": "string",
+          "minLength": 1,
+          "errorMessage": {
+            "minLength": "User prompt is required"
+          }
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "errorMessage": {
+            "minLength": "Model is required"
+          }
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "maxTokenPerResponse": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 16384
+        },
+        "modelMaxTokens": {
+          "type": "number",
+          "minimum": 0
+        },
+        "maxIterations": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 100
+        },
+        "guardrails": {
+          "type": "array"
+        },
+        "agentInputVariables": {
+          "type": "array"
+        },
+        "agentOutputVariables": {
+          "type": "array"
+        }
+      },
+      "required": [
+        "systemPrompt",
+        "userPrompt",
+        "model"
+      ]
+    },
+    "inputDefaults": {},
+    "outputDefinition": {
+      "output": {
+        "type": "object",
+        "description": "Agent response",
+        "source": "=result.response",
+        "var": "output"
+      },
+      "error": {
+        "type": "object",
+        "description": "Error information if the node fails",
+        "source": "=Error",
+        "var": "error"
+      }
+    },
+    "model": {
+      "source": true,
+      "type": "bpmn:ServiceTask",
+      "serviceType": "Orchestrator.StartInlineAgentJob",
+      "version": "v2",
+      "context": [
+        {
+          "name": "_label",
+          "type": "string",
+          "value": ""
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "value": ""
+        },
+        {
+          "name": "entryPoint",
+          "type": "string",
+          "value": ""
+        }
+      ]
+    },
+    "debug": {
+      "runtime": "bpmnEngine"
+    }
+  },
   "uipath.agent.autonomous@1.3": {
     "nodeType": "uipath.agent.autonomous",
     "version": "1.3",

package/dist/decompile-cli.js

@@ -25,6 +25,7 @@ import { decompile } from './decompile.js';
 import { resolveFlowRefs } from './ref-resolve.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 import { PACKAGE_NAME } from './package-name.js';
+import { commentText } from './core/comment-text.js';
 /** Derive a PascalCase base name from the flow name/id for the default output file. */
 function baseName(flow) {
     const src = flow.name ?? flow.id ?? 'Flow';
@@ -101,7 +102,7 @@ function pipelineScript(originalPath, tsPath, pipelinePath) {
     const base = pipelinePath.replace(/\.pipeline\.mjs$/, '');
     return `#!/usr/bin/env node
 // Generated by flow-decompile — the brownfield read/modify/write pipeline for
-// ${basename(originalPath)}. Run it, edit ${basename(tsPath)}, run it again.
+// ${commentText(basename(originalPath))}. Run it, edit ${commentText(basename(tsPath))}, run it again.
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 

package/dist/decompile.js

@@ -35,6 +35,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inferScriptShape } from './core/script-return.js';
 import { DEFAULT_TRIGGER_ID } from './core/expr.js';
+import { commentText } from './core/comment-text.js';
 import { parseIxpProjectType } from './core/actions.js';
 import { readFlowGlobals } from './flow-variables.js';
 import { missingBindingLabels } from './core/binding-messages.js';
@@ -95,7 +96,19 @@ function warnOnce(message) {
  * emitted source; saying so here is the difference between a loop that fails
  * at step 2 with a hint and one that fails at step 2 with a puzzle.
  */
-const CORE_DEFINITION_KEYS = new Set(Object.keys(JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'core-definitions.json'), 'utf8'))));
+const CORE_DEFINITIONS = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'core-definitions.json'), 'utf8'));
+const CORE_DEFINITION_KEYS = new Set(Object.keys(CORE_DEFINITIONS));
+/**
+ * The label the canvas gives a freshly dropped `node`: its definition's
+ * `display.label`, from the file's own `definitions[]`, else the bundled core
+ * definition. `serialize` uses the same label when the author sets none.
+ */
+function definitionLabel(node) {
+    const key = `${node.type}@${node.typeVersion}`;
+    const def = runDefs.get(key) ?? CORE_DEFINITIONS[key] ?? runDefs.get(node.type);
+    const label = def?.display?.label;
+    return typeof label === 'string' ? label : undefined;
+}
 function verClause(node) {
     const tv = node.typeVersion;
     if (!tv) {
@@ -124,6 +137,25 @@ function verArg(node) {
     const clause = verClause(node);
     return clause ? `, { ${clause} }` : '';
 }
+/**
+ * A trigger node's option clauses: its exact `version`, and its canvas `label`
+ * when that differs from the definition's label (`definitionLabel`).
+ */
+function triggerOptParts(node) {
+    const parts = [];
+    const ver = verClause(node);
+    if (ver)
+        parts.push(ver);
+    const label = node.display?.label;
+    if (typeof label === 'string' && label !== definitionLabel(node))
+        parts.push(`label: ${str(label)}`);
+    return parts;
+}
+/** `triggerOptParts` as the `.trigger(spec, { ... })` options argument. */
+function triggerOptsArg(node) {
+    const parts = triggerOptParts(node);
+    return parts.length ? `, { ${parts.join(', ')} }` : '';
+}
 /**
  * The full node-options argument for steps that can carry both an exact
  * `version` and mid-flow `updates` (the format's `variableUpdates[nodeId]`,
@@ -1083,11 +1115,12 @@ function sidecarAgentInputs(node) {
         ? numberUnless(settings.maxIterations, STUDIO_WEB_DEFAULT_MAX_ITERATIONS)
         : typeof settings.maxIterations === 'number' ? settings.maxIterations : undefined;
     // `mode` is a harness choice on the inline agent only; the conversational and
-    // voice sidecars always carry their family's fixed value. Naming it is also
-    // what selects the 1.3 definition, so on a 1.3 node even `'standard'` was the
-    // author's.
+    // voice sidecars always carry their family's fixed value. `'standard'` is the
+    // sidecar's default, so only another value is the author's. (Naming it no
+    // longer selects a definition version — the node's `{ version }` carries that,
+    // flow-builder-sdk#956.)
     const mode = node.type === T.inlineAgent && typeof settings.mode === 'string'
-        && (settings.mode !== 'standard' || node.typeVersion === '1.3')
+        && settings.mode !== 'standard'
         ? settings.mode : undefined;
     return {
         ...(system === undefined ? {} : { systemPrompt: system }),
@@ -1616,7 +1649,7 @@ function unboundMarker(node, labels, key, action) {
         + `The source leaves ${missing.length > 1 ? 'them' : 'it'} out, and compile refuses the node (BINDING_MISSING) `
         + `until it names both labels: run \`${prepareCommand(key, action ?? '<action>')}\`, then pass `
         + `\`connection\` and \`folder\`.`);
-    return ` /* TODO: bind ${names}; compile refuses this node until it has both labels (BINDING_MISSING) */`;
+    return ` /* TODO: bind ${commentText(names)}; compile refuses this node until it has both labels (BINDING_MISSING) */`;
 }
 function emitEventSubscription(node, imp, inputNames) {
     const prefix = node.type.startsWith('uipath.connector.event.') ? 'uipath.connector.event.'
@@ -1705,6 +1738,13 @@ function emitPublishedResource(node, imp, inputNames) {
     // definition to read there is nothing to recover it from.
     const name = binding('name');
     const folderPath = binding('folderPath');
+    // A sibling project of the same solution (#951): the model names its project
+    // instead of a folder. `isInSolution` is flow-core's marker; an in-solution
+    // agent emitted before #951 carries only `projectId`. Read back as
+    // `location: 'in-solution'` so the recompile takes the in-solution path
+    // instead of a published one with an empty folder.
+    const projectId = typeof def?.model?.projectId === 'string' ? def.model.projectId : undefined;
+    const inSolution = def?.model?.isInSolution === true || projectId !== undefined;
     const inputs = { ...(node.inputs ?? {}) };
     // The design-time fire-and-forget switch is an OPTION on the factory, not a
     // process argument — serialize adds it to `inputs` after rendering the
@@ -1720,7 +1760,9 @@ function emitPublishedResource(node, imp, inputNames) {
     return `${imp.use(family.factory)}(${opts([
         ['key', str(key)],
         ['name', name !== undefined ? str(name) : undefined],
-        ['folderPath', folderPath !== undefined ? str(folderPath) : undefined],
+        ['location', inSolution ? str('in-solution') : undefined],
+        ['folderPath', !inSolution && folderPath !== undefined ? str(folderPath) : undefined],
+        ['projectId', inSolution && projectId !== undefined ? str(projectId) : undefined],
         ['inputs', inputRows.length ? objLit(inputRows) : undefined],
         ['returns', returns],
         ['form', family.form !== undefined ? str(family.form) : undefined],
@@ -1792,7 +1834,7 @@ function unsupportedSpec(node, imp, o) {
     }
     // No definition to carry: a mock publishes nothing and takes no inputs, so it
     // is a safe structural stand-in, and the marker records what it replaced.
-    return `${imp.use('mock')}() /* TODO: unsupported node type ${node.type} */`;
+    return `${imp.use('mock')}() /* TODO: unsupported node type ${commentText(node.type)} */`;
 }
 /** `some-node.id` → `someNodeId`, for a hoisted const name. */
 function camel(id) {
@@ -1902,39 +1944,39 @@ function emitTrigger(e, depth, trigger, imp, o, inputNames = new Set()) {
         // The default trigger, spelled out: decompiled source is deliberately more
         // explicit than hand-authored source so the node's exact definition version
         // survives recompilation (design §5.3).
-        e.line(depth, `.trigger(${imp.use('manual')}()${verArg(trigger)})`);
+        e.line(depth, `.trigger(${imp.use('manual')}()${triggerOptsArg(trigger)})`);
         return;
     }
     if (trigger.type === T.triggerScheduled) {
-        e.line(depth, `.trigger(${imp.use('scheduled')}(${opts([['every', str(scheduleEvery(trigger))]])})${verArg(trigger)})`);
+        e.line(depth, `.trigger(${imp.use('scheduled')}(${opts([['every', str(scheduleEvery(trigger))]])})${triggerOptsArg(trigger)})`);
         return;
     }
     if (trigger.type === T.triggerForm) {
         // The schema is DERIVED from the flow's inputs at compile time, so nothing
         // of it needs recovering — the factory takes no arguments.
-        e.line(depth, `.trigger(${imp.use('formTrigger')}()${verArg(trigger)})`);
+        e.line(depth, `.trigger(${imp.use('formTrigger')}()${triggerOptsArg(trigger)})`);
         return;
     }
     if (trigger.type === T.triggerConversation) {
-        e.line(depth, `.trigger(${imp.use('conversationTrigger')}()${verArg(trigger)})`);
+        e.line(depth, `.trigger(${imp.use('conversationTrigger')}()${triggerOptsArg(trigger)})`);
         return;
     }
     if (trigger.type === T.triggerVoice) {
-        e.line(depth, `.trigger(${imp.use('voiceTrigger')}()${verArg(trigger)})`);
+        e.line(depth, `.trigger(${imp.use('voiceTrigger')}()${triggerOptsArg(trigger)})`);
         return;
     }
     // A connector EVENT trigger — the same subscription body as a mid-flow wait.
     {
         const sub = emitEventSubscription(trigger, imp, inputNames);
         if (sub !== undefined) {
-            e.line(depth, `.trigger(${imp.use('onEvent')}(${sub})${verArg(trigger)})`);
+            e.line(depth, `.trigger(${imp.use('onEvent')}(${sub})${triggerOptsArg(trigger)})`);
             return;
         }
     }
     if (o.bestEffort === false) {
         throw new Error(`decompile: unsupported trigger type "${trigger.type}".`);
     }
-    e.line(depth, `/* TODO: unsupported trigger type ${trigger.type} */`);
+    e.line(depth, `/* TODO: unsupported trigger type ${commentText(trigger.type)} */`);
 }
 // ─── Control-flow reconstruction (Phase 3) ────────────────────────────────────
 //
@@ -2350,7 +2392,7 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         // Unstructured fan-out we can't fold — best-effort marker.
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: unstructured fan-out at "${node.id}".`);
-        segs.push(`/* TODO: unstructured fan-out at ${node.id} (${succ.length} successors) */`);
+        segs.push(`/* TODO: unstructured fan-out at ${commentText(node.id)} (${commentText(succ.length)} successors) */`);
         return segs;
     }
     return segs;
@@ -2637,7 +2679,7 @@ function emitSubflow(node, ctx) {
     if (!child) {
         if (ctx.o.bestEffort === false)
             throw new Error(`decompile: subflow "${node.id}" has no body in subflows[].`);
-        return `${ctx.imp.use('mock')}() /* TODO: subflow ${node.id} body missing */`;
+        return `${ctx.imp.use('mock')}() /* TODO: subflow ${commentText(node.id)} body missing */`;
     }
     const childName = `${node.id}Child`;
     const childSrc = emitChildFlow(childName, child, ctx);
@@ -2736,7 +2778,7 @@ export function decompile(flow, options = {}) {
         if (runStrict)
             throw new Error(`decompile: ${schema.problem}`);
         warnOnce(schema.problem);
-        e.line(d, `// TODO: ${schema.problem}`);
+        e.line(d, `// TODO: ${commentText(schema.problem)}`);
     }
     if (flow.name !== undefined && flow.name !== flow.id)
         e.line(d, `.name(${str(flow.name)})`);
@@ -2772,7 +2814,7 @@ export function decompile(flow, options = {}) {
             throw new Error(`decompile: ${message}`);
         warnOnce(message);
         for (const n of detached) {
-            e.line(d, `// TODO: node ${str(n.id)} (${n.type}) is not reachable from any trigger and is NOT in this source; recompiling drops it. Connect it in the .flow or edit its JSON directly.`);
+            e.line(d, `// TODO: node ${commentText(str(n.id))} (${commentText(n.type)}) is not reachable from any trigger and is NOT in this source; recompiling drops it. Connect it in the .flow or edit its JSON directly.`);
         }
     }
     // `{ shared }` input copies on the roots (#924). Any other trigger-level
@@ -2786,7 +2828,7 @@ export function decompile(flow, options = {}) {
         if (runStrict)
             throw new Error(`decompile: ${message}`);
         warnOnce(message);
-        e.line(d, `// TODO: ${message}`);
+        e.line(d, `// TODO: ${commentText(message)}`);
     }
     emitVariables(e, d, flow, imp, new Set(triggerNodes.filter((t) => t !== trigger).map((t) => t.id)), shared);
     // Reconstruct the body: structured control flow recovered from the graph.
@@ -2876,7 +2918,7 @@ function entryPointSeg(t, scope, ipdom, ctx) {
                         : (() => {
                             if (ctx.o.bestEffort === false)
                                 throw new Error(`decompile: unsupported entry-point trigger type "${t.type}".`);
-                            return `${ctx.imp.use('manual')}() /* TODO: unsupported trigger type ${t.type} */`;
+                            return `${ctx.imp.use('manual')}() /* TODO: unsupported trigger type ${commentText(t.type)} */`;
                         })();
     const scoped = readFlowGlobals(ctx.flow.variables, runStrict)
         .filter((g) => g.direction === 'in' && g.triggerNodeId === t.id);
@@ -2885,9 +2927,7 @@ function entryPointSeg(t, scope, ipdom, ctx) {
         const sharedOf = (g) => ctx.shared?.byInput.get(`${t.id}\0${g.id}`);
         optParts.push(`inputs: { ${scoped.map((g) => `${key(g.name ?? g.id)}: ${declExpr(g, true, ctx.imp, sharedOf(g))}`).join(', ')} }`);
     }
-    const ver = verClause(t);
-    if (ver)
-        optParts.push(ver);
+    optParts.push(...triggerOptParts(t));
     const first = scopeSucc(ctx.graph, t.id, scope)[0];
     const prefixSegs = first !== undefined ? region(first, EXIT, scope, ipdom, ctx) : [];
     const optArgText = optParts.length ? `, { ${optParts.join(', ')} }` : (prefixSegs.length ? ', undefined' : '');

package/dist/emit.js

@@ -25,13 +25,14 @@
  * are the ones `.build()` and `serialize()` raise themselves. Callers who want
  * the static pass should call `check()` — or use `compile-cli`.
  */
-import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { serialize } from './serialize.js';
 import { Library } from './library.js';
 import { Bindings } from './bindings.js';
 import { resolveLibraryDir } from './core/library-cache.js';
 import { defaultBindingsFile } from './workdir.js';
+import { writeJsonFile } from './core/json-file.js';
 /**
  * Resolve the connector library the same way `compile-cli` does: only load it
  * when it is actually there, so a flow with no connectors emits fine without a
@@ -51,11 +52,11 @@ export function emitFlow(built, path, opts = {}) {
         library: opts.library ?? defaultLibrary(opts.libraryDir),
         bindings: opts.bindings ?? new Bindings(bindFile),
         // Same channel `compile` uses; a host that wants them elsewhere passes `warn`.
-        warn: opts.warn ?? ((w) => console.error(`  ⚠ [${w.code}] ${w.message}`)),
+        warn: opts.warn ?? ((w) => process.stderr.write(`  ⚠ [${w.code}] ${w.message}\n`)),
     });
     const dir = dirname(path);
     if (dir && dir !== '.' && !existsSync(dir))
         mkdirSync(dir, { recursive: true });
-    writeFileSync(path, JSON.stringify(flowJson, null, 2) + '\n');
+    writeJsonFile(path, flowJson);
     return flowJson;
 }

package/dist/flow-sdk.d.ts

@@ -373,7 +373,8 @@ export interface NodeOptions {
     updates?: Record<string, Expr | unknown>;
     /**
      * What the canvas shows on this node (`display.label`). Defaults to the step
-     * name.
+     * name; on a trigger (`.trigger()`, `.entryPoint()`) to the trigger
+     * definition's label, e.g. `Manual trigger`.
      *
      * @remarks
      * Purely cosmetic, and deliberately separate from the step name: the NAME is
@@ -386,8 +387,10 @@ export interface NodeOptions {
      * .step('fetchInv', http({ url, managed: true }), { label: 'Fetch invoice' })
      * ```
      *
-     * `.branch()`, `.switch()`, `.loop()`, `.doWhile()`, `.parallel()` and
-     * `.terminate()` take their label as a positional argument instead.
+     * `.branch()`, `.switch()`, `.loop()`, `.doWhile()`, `.parallel()`,
+     * `.trigger()` and `.entryPoint()` take it here too, in their options
+     * argument. Only `.terminate()` also has a positional label
+     * (`.terminate('stop', 'Stop here')`); when both are given, this option wins.
      */
     label?: string;
 }
@@ -663,7 +666,7 @@ export interface BuiltEntryPoint {
     id: string;
     /** What fires this root: any built-in trigger factory, or a custom trigger. */
     trigger: TriggerSpec;
-    /** Node options for the trigger node — exact `version` selection. */
+    /** Node options for the trigger node — exact `version` selection and canvas `label`. */
     options?: NodeOptions;
     /** Inputs scoped to this root (globals bound to it via `triggerNodeId`). */
     inputs: VarDecl[];
@@ -1235,7 +1238,8 @@ declare class FlowBuilder extends StepList {
      *
      * @param spec - What starts the flow, from `scheduled(...)` or `onEvent(...)`.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version and `label` sets what the canvas shows on the trigger node
+     * (default: the trigger definition's label, e.g. `Scheduled trigger`). See {@link NodeOptions}.
      * @returns This builder, so calls chain.
      * @defaultValue the manual trigger
      */
@@ -1281,13 +1285,14 @@ declare class FlowBuilder extends StepList {
      * @param trigger - What fires this root: `manual()`, `scheduled(...)`,
      * `onEvent(...)`, `formTrigger()` (one field per scoped input),
      * `conversationTrigger()`, or `voiceTrigger()`.
-     * @param options - `version` (exact trigger definition version) and `inputs`
-     * — this root's scoped inputs, declared like `.input()`.
+     * @param options - `version` (exact trigger definition version), `label`
+     * (what the canvas shows on the trigger node; default: the trigger
+     * definition's label, e.g. `Manual trigger`), and `inputs` — this root's scoped inputs, declared like
+     * `.input()`.
      * @param prefixFn - Optional sub-builder for the root's prefix steps.
      * @returns This builder, so calls chain.
      */
-    entryPoint(id: string, trigger: TriggerSpec | FlowTrigger, options?: {
-        version?: string;
+    entryPoint(id: string, trigger: TriggerSpec | FlowTrigger, options?: Pick<NodeOptions, 'version' | 'label'> & {
         inputs?: Record<string, TypeDesc | VarSpec>;
     }, prefixFn?: (b: StepList) => void): this;
     /**

package/dist/flow-sdk.js

@@ -942,7 +942,8 @@ class FlowBuilder extends StepList {
      *
      * @param spec - What starts the flow, from `scheduled(...)` or `onEvent(...)`.
      * @param options - Node options; `version` selects the exact definition
-     * version (see {@link NodeOptions}).
+     * version and `label` sets what the canvas shows on the trigger node
+     * (default: the trigger definition's label, e.g. `Scheduled trigger`). See {@link NodeOptions}.
      * @returns This builder, so calls chain.
      * @defaultValue the manual trigger
      */
@@ -996,8 +997,10 @@ class FlowBuilder extends StepList {
      * @param trigger - What fires this root: `manual()`, `scheduled(...)`,
      * `onEvent(...)`, `formTrigger()` (one field per scoped input),
      * `conversationTrigger()`, or `voiceTrigger()`.
-     * @param options - `version` (exact trigger definition version) and `inputs`
-     * — this root's scoped inputs, declared like `.input()`.
+     * @param options - `version` (exact trigger definition version), `label`
+     * (what the canvas shows on the trigger node; default: the trigger
+     * definition's label, e.g. `Manual trigger`), and `inputs` — this root's scoped inputs, declared like
+     * `.input()`.
      * @param prefixFn - Optional sub-builder for the root's prefix steps.
      * @returns This builder, so calls chain.
      */
@@ -1011,7 +1014,14 @@ class FlowBuilder extends StepList {
         this._entryPoints.push({
             id,
             trigger: trigger,
-            ...(options?.version !== undefined ? { options: { version: options.version } } : {}),
+            ...(options?.version !== undefined || options?.label !== undefined
+                ? {
+                    options: {
+                        ...(options.version !== undefined ? { version: options.version } : {}),
+                        ...(options.label !== undefined ? { label: options.label } : {}),
+                    },
+                }
+                : {}),
             inputs,
             steps: b.steps,
         });

package/dist/flow-step-tree.d.ts

@@ -15,9 +15,8 @@ export declare function stopsAtEnd(steps: readonly Step[]): boolean;
  * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
  * flow's own tree must descend into. Exhaustive over `Step['kind']`, so a new
  * container kind fails to compile here instead of being silently skipped by
- * every walker. That is how `check`'s return scan came to miss `.stepSwitch`
- * arms and `.stepToList` / `.onError` bodies, and warned NO_RETURN on flows
- * whose every path ends in `.return()` (UV-16855).
+ * every walker. That is how an earlier `check` return scan came to miss
+ * `.stepSwitch` arms and `.stepToList` / `.onError` bodies (UV-16855).
  *
  * A subflow's child flow is deliberately NOT a child here: it is another
  * flow's tree, and its returns say nothing about whether THIS flow ends.

package/dist/flow-step-tree.js

@@ -15,9 +15,8 @@ export function stopsAtEnd(steps) {
  * The step lists nested DIRECTLY inside `step` — the bodies a walk over this
  * flow's own tree must descend into. Exhaustive over `Step['kind']`, so a new
  * container kind fails to compile here instead of being silently skipped by
- * every walker. That is how `check`'s return scan came to miss `.stepSwitch`
- * arms and `.stepToList` / `.onError` bodies, and warned NO_RETURN on flows
- * whose every path ends in `.return()` (UV-16855).
+ * every walker. That is how an earlier `check` return scan came to miss
+ * `.stepSwitch` arms and `.stepToList` / `.onError` bodies (UV-16855).
  *
  * A subflow's child flow is deliberately NOT a child here: it is another
  * flow's tree, and its returns say nothing about whether THIS flow ends.

package/dist/load.js

@@ -13,7 +13,7 @@ export function resolveFlowFile(arg) {
         if (!statSync(resolvedCandidate, { throwIfNoEntry: false })?.isFile())
             continue;
         if (candidate !== arg && argStat?.isDirectory()) {
-            console.error(`flow source: "${resolvedArg}" is a directory; using "${resolvedCandidate}"`);
+            process.stderr.write(`flow source: "${resolvedArg}" is a directory; using "${resolvedCandidate}"\n`);
         }
         return resolvedCandidate;
     }

package/dist/merge-cli.js

@@ -12,7 +12,8 @@
  * See merge.ts.
  */
 import { reportResult } from './cli-result.js';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { writeJsonFile } from './core/json-file.js';
+import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { mergeFlow } from './merge.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
@@ -37,7 +38,7 @@ export function run(argv) {
         warn: (m) => console.error(`flow-merge: warning: ${m}`),
     });
     const out = flagValue(argv, '-o') ?? 'merged.flow';
-    writeFileSync(out, JSON.stringify(merged, null, 2) + '\n');
+    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 });
     return 0;

package/dist/merge.d.ts

@@ -25,7 +25,8 @@
  *     as decompile was faithful for every node (the common case).
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
- * preserved from the original; `definitions` and `bindings` are unioned
+ * preserved from the original; `subflows` and edges (with their ids) come from
+ * `edited`; `definitions` and `bindings` are unioned
  * (original wins on conflict, since the original's are the tenant-resolved
  * authority). Node ids are stable by construction (decompile names every step by
  * its node id), which is what lets every re-attach key on id.