@uipath/maestro-builder-sdk 6.16.14 → 6.17.1

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[];
@@ -821,7 +824,7 @@ declare class StepList {
      * even a legal call: `out(step, path?)` takes two arguments.
      *
      * **Three ways the handler can end**: `.return(...)` answers the flow,
-     * `.terminate(...)` stops the run, and `h.rejoin('<step>')` compensates and
+     * `.terminate(...)` stops the run, and `h.stepToRef('<step>')` compensates and
      * hands control back to a step the success path also reaches — the shape most
      * deployed flows use. A handler that just runs out of steps still gets its own
      * End: rejoining is something the author SAYS, never something wiring infers.
@@ -835,8 +838,9 @@ declare class StepList {
      *
      * **A `.loop()` container takes one too.** `core.logic.loop` declares the
      * handle, and a body step's failure routes to it: the container's envelope
-     * carries the body's message in `detail` and the failing body step's id in
-     * `element`, and the instance completes rather than faulting. `.doWhile()` does
+     * carries the body's message in `detail` and the failing body step's label
+     * (`display.label`, which defaults to the step name) in `element`, and the
+     * instance completes rather than faulting. `.doWhile()` does
      * NOT — it declares an error variable and no error handle — so that one is
      * refused by name, and its failures belong to the body step that can fail.
      *
@@ -1235,7 +1239,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 +1286,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

@@ -402,7 +402,7 @@ class StepList {
      * even a legal call: `out(step, path?)` takes two arguments.
      *
      * **Three ways the handler can end**: `.return(...)` answers the flow,
-     * `.terminate(...)` stops the run, and `h.rejoin('<step>')` compensates and
+     * `.terminate(...)` stops the run, and `h.stepToRef('<step>')` compensates and
      * hands control back to a step the success path also reaches — the shape most
      * deployed flows use. A handler that just runs out of steps still gets its own
      * End: rejoining is something the author SAYS, never something wiring infers.
@@ -416,8 +416,9 @@ class StepList {
      *
      * **A `.loop()` container takes one too.** `core.logic.loop` declares the
      * handle, and a body step's failure routes to it: the container's envelope
-     * carries the body's message in `detail` and the failing body step's id in
-     * `element`, and the instance completes rather than faulting. `.doWhile()` does
+     * carries the body's message in `detail` and the failing body step's label
+     * (`display.label`, which defaults to the step name) in `element`, and the
+     * instance completes rather than faulting. `.doWhile()` does
      * NOT — it declares an error variable and no error handle — so that one is
      * refused by name, and its failures belong to the body step that can fail.
      *
@@ -464,7 +465,7 @@ class StepList {
         // `@2.4`, gated on `errorHandlingEnabled` like every other error handle), and
         // the platform routes it: a body step throwing inside a measured run left the
         // instance Completed with the container's envelope published — `detail` the
-        // body's own message, `element` the id of the body step that failed.
+        // body's own message, `element` the label of the body step that failed.
         //
         // `.doWhile()` is NOT: `core.logic.dowhile@1.0` declares an error VARIABLE
         // and no error HANDLE, so an edge would leave a handle the node does not
@@ -942,7 +943,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 +998,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 +1015,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.

package/dist/path-within.d.ts

@@ -0,0 +1,33 @@
+/**
+ * path-within — the one path-containment test for anything that writes files.
+ *
+ * "Is `child` inside `parent`?" looks like a string-prefix question and is not
+ * one. `child.startsWith(parent + '/')` is correct only where the separator is
+ * `/`: on Windows `path.resolve` returns `C:\proj\P\x`, the check refuses every
+ * path, and compile refused every inline agent's `<source>/agent.json`
+ * (flow-builder-sdk#946). A prefix test without a trailing separator has the
+ * opposite bug: it accepts the sibling `C:\proj\P2\x` as inside `C:\proj\P`.
+ *
+ * So the test is `relative(parent, child)` instead, which gets both right on
+ * every platform, and Windows' case-insensitive drive letters and
+ * cross-drive paths (`relative` returns the absolute `D:\x` there) with them.
+ *
+ * The path implementation is a parameter so the Windows rules can be tested on
+ * a Linux runner (`isWithin(a, b, path.win32)`). Callers leave it out.
+ */
+import * as nodePath from 'node:path';
+/** The slice of `node:path` the test needs; `path.win32` and `path.posix` both fit. */
+export type PathApi = Pick<typeof nodePath, 'relative' | 'isAbsolute' | 'sep'>;
+/**
+ * `child` is `parent` itself or somewhere beneath it.
+ *
+ * Both paths should be absolute (from `path.resolve`); relative ones are
+ * resolved against the working directory by `relative`.
+ *
+ * @example
+ *   isWithin('/proj/P', '/proj/P/abc/agent.json')         // true
+ *   isWithin('/proj/P', '/proj/P2/agent.json')            // false — sibling, not child
+ *   isWithin('C:\\proj\\P', 'C:\\proj\\P\\abc\\agent.json', path.win32) // true
+ *   isWithin('C:\\proj\\P', 'D:\\agent.json', path.win32)  // false — other drive
+ */
+export declare function isWithin(parent: string, child: string, path?: PathApi): boolean;

package/dist/path-within.js

@@ -0,0 +1,41 @@
+/**
+ * path-within — the one path-containment test for anything that writes files.
+ *
+ * "Is `child` inside `parent`?" looks like a string-prefix question and is not
+ * one. `child.startsWith(parent + '/')` is correct only where the separator is
+ * `/`: on Windows `path.resolve` returns `C:\proj\P\x`, the check refuses every
+ * path, and compile refused every inline agent's `<source>/agent.json`
+ * (flow-builder-sdk#946). A prefix test without a trailing separator has the
+ * opposite bug: it accepts the sibling `C:\proj\P2\x` as inside `C:\proj\P`.
+ *
+ * So the test is `relative(parent, child)` instead, which gets both right on
+ * every platform, and Windows' case-insensitive drive letters and
+ * cross-drive paths (`relative` returns the absolute `D:\x` there) with them.
+ *
+ * The path implementation is a parameter so the Windows rules can be tested on
+ * a Linux runner (`isWithin(a, b, path.win32)`). Callers leave it out.
+ */
+import * as nodePath from 'node:path';
+/**
+ * `child` is `parent` itself or somewhere beneath it.
+ *
+ * Both paths should be absolute (from `path.resolve`); relative ones are
+ * resolved against the working directory by `relative`.
+ *
+ * @example
+ *   isWithin('/proj/P', '/proj/P/abc/agent.json')         // true
+ *   isWithin('/proj/P', '/proj/P2/agent.json')            // false — sibling, not child
+ *   isWithin('C:\\proj\\P', 'C:\\proj\\P\\abc\\agent.json', path.win32) // true
+ *   isWithin('C:\\proj\\P', 'D:\\agent.json', path.win32)  // false — other drive
+ */
+export function isWithin(parent, child, path = nodePath) {
+    const rel = path.relative(parent, child);
+    if (rel === '')
+        return true;
+    // `..` alone or as the first segment leaves `parent`; a segment that merely
+    // starts with dots (`..cache`) does not.
+    if (rel === '..' || rel.startsWith(`..${path.sep}`))
+        return false;
+    // Windows: a child on another drive has no relative spelling.
+    return !path.isAbsolute(rel);
+}

package/dist/registry/archive/extract.js

@@ -17,7 +17,8 @@
  * Python printed to stderr; the caller prints it and exits 1.
  */
 import { readFileSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
+import { isWithin } from "../../path-within.js";
 import { isFile, writeBytes, ensureDir } from "../files.js";
 import { UnsafeArchive, isSymlinkEntry, safeRelativePath } from "./entry-policy.js";
 import { NotAZip, UnsupportedArchive, entryData, readZipEntries } from "./zip-reader.js";
@@ -40,10 +41,6 @@ export class ExtractLibraryError extends Error {
         this.name = "ExtractLibraryError";
     }
 }
-/** `child` is `parent` or lives beneath it — both already `path.resolve`d. */
-function isWithin(parent, child) {
-    return child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
-}
 export function extractArchive(options) {
     const { archivePath, destination } = options;
     const root = options.root ?? DEFAULT_ROOT;

package/dist/registry/curated-overlay.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
-import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile } from "node:fs/promises";
 import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { sortedStrings } from "./compat/compare.js";
+import { writeJsonFile } from "../core/json-file.js";
 import { consoleReporter } from "./reporter.js";
 /** The corrections and definitions that the raw registry dump does not carry. */
 export function bundledOverlayPath() {
@@ -129,7 +130,7 @@ reporter = consoleReporter) {
     }
     if (additions.length > 0) {
         destination.entries = [...entries, ...additions];
-        await writeFile(indexPath, `${JSON.stringify(destination, null, 2)}\n`);
+        writeJsonFile(indexPath, destination);
     }
     return { files: copied, entries: additions.length, skipped: sortedStrings([...skipped]) };
 }

package/dist/registry/generators/descriptors.js

@@ -19,6 +19,7 @@
  * node type and so would emit the same const twice.
  */
 import { prepareCommand } from "../../core/cli-spelling.js";
+import { commentText, docComment } from "../../core/comment-text.js";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
@@ -58,15 +59,16 @@ export function lookupFieldNote(declared) {
 export function emitNestedProperty(name, node, indent, namedTypes, allOptional, isInput = false) {
     const lines = [];
     const declared = node.declared ?? {};
-    let desc = pyStrip(strOrEmpty(declared.description)).replaceAll("\n", " ");
+    let desc = pyStrip(strOrEmpty(declared.description));
     if (isInput && pyTruthy(declared.__lookup)) {
         // The identity goes ON the field, not only in the LOOKUP block above the
         // descriptor: "The reporter of the issue" beside `ConnectorLookupValue<string>`
         // read as "any string", and an e-mail went into `fields.reporter.id`.
         desc = pyStrip(`${desc} ${lookupFieldNote(declared)}`);
     }
+    // A multi-line description keeps its breaks: `docComment` opens a block for it.
     if (desc)
-        lines.push(`${indent}/** ${desc} */`);
+        lines.push(...docComment(desc, indent));
     const optional = allOptional || !subtreeRequired(node) ? "?" : "";
     let rendered = namedTypes.typeFor(name, node);
     if (isInput) {
@@ -100,11 +102,11 @@ export function emitLookupComment(specs, symbol = "<Descriptor>") {
     const lines = [];
     for (const [field, spec] of specs) {
         const target = splitOnce(pyStr(pyTruthy(spec.objectName) ? spec.objectName : spec.path), "?")[0];
-        lines.push(` * LOOKUP: \`${field}\` -> ${target}.${spec.value}`);
+        lines.push(` * LOOKUP: \`${commentText(field)}\` -> ${commentText(target)}.${commentText(spec.value)}`);
         const aliases = spec.aliases;
         const offered = aliases.size > 0 ? [...aliases.values()].map((a) => `${a}()`) : [];
         const byList = spec.by.map((n) => `\`${n}\``).join(", ");
-        lines.push(` *   by: ${byList}`);
+        lines.push(` *   by: ${commentText(byList)}`);
         // THE WHOLE CALL, not just the method names: naming `.byEmail` without the
         // `lookup(Descriptor, 'field')` wrapper says helpers exist but not how to
         // reach one.
@@ -114,16 +116,16 @@ export function emitLookupComment(specs, symbol = "<Descriptor>") {
             : spec.by.length > 0
                 ? `lookup(${symbol}, '${field}').by('${spec.by[0]}', value)`
                 : `lookup(${symbol}, '${field}')`;
-        lines.push(` *   use: ${call}`);
+        lines.push(` *   use: ${commentText(call)}`);
         if (offered.length > 0) {
-            lines.push(` *   also: ${[...aliases.values()].map((a) => `.${a}`).join(", ")}  ·  .by(name, value)`);
+            lines.push(` *   also: ${commentText([...aliases.values()].map((a) => `.${a}`).join(", "))}  ·  .by(name, value)`);
         }
         else {
             lines.push(" *   also: .by(name, value) only — aliases collided");
         }
-        lines.push(` *   strategy: ${STRATEGY_PROSE[spec.strategy]}`);
+        lines.push(` *   strategy: ${commentText(STRATEGY_PROSE[spec.strategy])}`);
         if (spec.dependsOn && spec.dependsOn.length > 0) {
-            lines.push(` *   resolve first: ${spec.dependsOn.map((d) => `\`${d}\``).join(", ")}`);
+            lines.push(` *   resolve first: ${commentText(spec.dependsOn.map((d) => `\`${d}\``).join(", "))}`);
         }
     }
     return lines;
@@ -186,16 +188,16 @@ export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTyp
     // connector input's are, so the descriptor carries the same specs.
     const specs = specsFromFields(inFields, invariant);
     lines.push("/**");
-    lines.push(` * ${pyStr(label)} — ${nodeType}`);
+    lines.push(` * ${commentText(pyStr(label))} — ${commentText(nodeType)}`);
     lines.push(" *");
     if (generic) {
         lines.push(" * A GENERIC event: it fires for ONE object of the connection (an entity, a");
-        lines.push(` * table, a custom object), so name it — \`onEvent(${name}, { object: '<Object>' })\`.`);
-        lines.push(` * \`uip is triggers objects ${pyStr(connectorKey)} <EVENT> --connection-id <id>\` lists them.`);
+        lines.push(` * table, a custom object), so name it — \`onEvent(${commentText(name)}, { object: '<Object>' })\`.`);
+        lines.push(` * \`uip is triggers objects ${commentText(pyStr(connectorKey))} <EVENT> --connection-id <id>\` lists them.`);
     }
     else {
-        lines.push(` * Start a flow on it with \`onEvent(${name}, { where: { … } })\`, or pause for it`);
-        lines.push(` * with \`waitForEvent(${name}, { … })\`; \`where\` carries its event parameters.`);
+        lines.push(` * Start a flow on it with \`onEvent(${commentText(name)}, { where: { … } })\`, or pause for it`);
+        lines.push(` * with \`waitForEvent(${commentText(name)}, { … })\`; \`where\` carries its event parameters.`);
     }
     // The facts the library build stamped from the event's `triggers objects`
     // row. An author holding only the descriptor must learn the requirement here:
@@ -205,7 +207,7 @@ export function emitEvent(entry, inFields, inputTree, outputTree, name, inputTyp
         lines.push(" * Requires a BYOA (bring-your-own-app) connection — on a standard one the");
         lines.push(" * trigger deploys and never fires. Bind it with");
         // Spelled for whoever ran the generator, like every `check` remedy.
-        lines.push(` * \`${prepareCommand(pyStr(connectorKey), eventId, "--connection-id", "<id>")}\`,`);
+        lines.push(` * \`${commentText(prepareCommand(pyStr(connectorKey), eventId, "--connection-id", "<id>"))}\`,`);
         lines.push(" * which refuses a standard connection and records the check `compile` requires;");
         lines.push(" * `uip is connections list --byoa --all-folders` lists the BYOA connections.");
     }
@@ -253,7 +255,7 @@ export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, ou
     const schemaAction = operation.schemaAction ?? {};
     const specs = lookupSpecs(entry, v1def, invariant);
     const lookupComment = specs.size > 0 ? emitLookupComment(specs, name) : [];
-    const header = ` * ${pyStr(label)} — ${nodeType}`;
+    const header = ` * ${commentText(pyStr(label))} — ${commentText(nodeType)}`;
     if (pyTruthy(operation.objectFromDiscovery)) {
         lines.push("/**");
         lines.push(header);
@@ -272,8 +274,8 @@ export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, ou
         lines.push("/**");
         lines.push(header);
         lines.push(" *");
-        lines.push(` * \`Inputs\` carries only the fields that SELECT the schema (${parents}).`);
-        lines.push(` * The real set comes from the \`${pyStr(schemaAction.name)}\` design-time`);
+        lines.push(` * \`Inputs\` carries only the fields that SELECT the schema (${commentText(parents)}).`);
+        lines.push(` * The real set comes from the \`${commentText(pyStr(schemaAction.name))}\` design-time`);
         lines.push(" * action — describe with those values supplied to see it.");
         if (lookupComment.length > 0) {
             lines.push(" *");
@@ -289,7 +291,7 @@ export function emitOp(entry, v1def, inputTree, outputTree, name, inputTypes, ou
         lines.push(" */");
     }
     else {
-        lines.push(`/** ${pyStr(label)} — ${nodeType} */`);
+        lines.push(`/** ${commentText(pyStr(label))} — ${commentText(nodeType)} */`);
     }
     lines.push(`export const ${name} = descriptor<${name}Inputs, ${name}Outputs>()({`);
     lines.push(`  nodeType: ${pyJsonString(nodeType)},`);

package/dist/registry/generators/triggers.js

@@ -11,6 +11,7 @@
  * with it, and `tests/registry-triggers-gen.test.ts` now pins the text.
  */
 import { PACKAGE_NAME } from "../../package-name.js";
+import { docComment } from "../../core/comment-text.js";
 import { pyJsonString, pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedByCodePoint, sortedStrings } from "../compat/compare.js";
 import { afterLast, pyRstrip, pyStrip, upperFirst } from "../compat/pystr.js";
@@ -32,11 +33,10 @@ function emitTrigger(row, seen) {
     seen.add(name);
     const version = "Version" in row ? row.Version : "1.0.0";
     const label = row.DisplayName || eventId;
-    const description = pyStrip(String(row.Description || "")).replaceAll("\n", " ");
-    let doc = description ? `${label} — ${description}` : label;
-    doc = doc.replaceAll("*/", "* /"); // never let a description close the doc comment early
+    const description = pyStrip(String(row.Description || ""));
+    const doc = description ? `${label} — ${description}` : label;
     return [
-        `/** ${doc} */`,
+        ...docComment(doc),
         `export const ${name} = triggerDescriptor()({`,
         `  connector: ${pyJsonString(row.connectorKey)},`,
         `  event: ${pyJsonString(eventId)},`,

package/dist/registry/prepare/messages.js

@@ -21,6 +21,7 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal, messageOf } from "../errors.js";
+import { commentText } from "../../core/comment-text.js";
 import { plausibleMatches } from "./actions.js";
 import { pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 export const PREFIX = "prepare-connector: ";
@@ -637,7 +638,7 @@ export function descriptorUsageUnparsedLines(sourcePosix, descriptorName) {
 export function descriptorUsageLines(descriptorName, importPath, requiredFields, boundConnection, boundFolder) {
     let inputs = "{}";
     if (requiredFields.length > 0) {
-        const placeholders = requiredFields.map(([name, type]) => `${name}: /* ${type}, required */`).join(", ");
+        const placeholders = requiredFields.map(([name, type]) => `${name}: /* ${commentText(type)}, required */`).join(", ");
         inputs = `{ ${placeholders} }`;
     }
     return [

package/dist/registry/prepare/source-labels.js

@@ -22,6 +22,10 @@
  *   import), so a source that a first `prepare` already repointed is still read;
  * - `onEvent(...)` / `waitForEvent(...)` — a subscription object whose
  *   `connector` is `'<key>'`, or a descriptor imported as above with its options.
+ * - `inlineAgent({ tools })` — each `{ kind: 'connector', connector: '<key>',
+ *   connection, folder }` tool, a single tool or an array (flow-builder-sdk#903).
+ *   A tool that is not a same-file object may be a connector tool, so it is
+ *   unplaceable like any other call; a tool of another `kind` binds nothing.
  *
  * `opts` and the labels in it may be literals or same-file `const`s, through
  * `as const`, `satisfies`, parentheses, spreads of such consts, and property
@@ -47,7 +51,7 @@ import { relativePosix } from "../compat/paths.js";
 import { canonicalPath, flowSources, isRelativeSpecifier } from "./source-import.js";
 import { inWorkDir } from "../../workdir.js";
 const CALLEES = new Set([
-    "connector", "onEvent", "waitForEvent", "eventTrigger", "dataService",
+    "connector", "onEvent", "waitForEvent", "eventTrigger", "dataService", "inlineAgent",
 ]);
 /**
  * Data Fabric's connector key, spelled here rather than imported from
@@ -313,6 +317,58 @@ function readFile(file, shown, text, connectorKey, moduleDirs, result, family) {
         result.unreadable.connection.push(line);
         result.unreadable.folder.push(line);
     };
+    /**
+     * An inline agent's `tools`: one tool or an array of them. A connector tool
+     * carries its labels on the tool object itself, beside its `connector` key.
+     */
+    const readAgentTools = (spec, at) => {
+        const obj = constObject(spec);
+        if (!obj) {
+            unplaceable(at, `takes \`${snippet(unwrap(spec))}\`, which is not a same-file object, so its tools`);
+            return;
+        }
+        const tools = prop(obj, "tools");
+        if (tools.kind === "absent")
+            return;
+        if (tools.kind === "unknown") {
+            unplaceable(at, `takes its tools from ${tools.why}`);
+            return;
+        }
+        const list = constArray(tools.expr);
+        if (!list && !constObject(tools.expr)) {
+            unplaceable(at, `takes its tools as \`${snippet(unwrap(tools.expr))}\``);
+            return;
+        }
+        const elements = list ? expandArgs(list.elements) : [tools.expr];
+        if (!Array.isArray(elements)) {
+            unplaceable(at, `${elements.why} in its tools`);
+            return;
+        }
+        for (const el of elements) {
+            const toolAt = `${where(el, "inlineAgent")} tool`;
+            const tool = constObject(el);
+            if (!tool) {
+                unplaceable(toolAt, `is \`${snippet(unwrap(el))}\`, which is not a same-file object`);
+                continue;
+            }
+            const kindProp = prop(tool, "kind");
+            if (kindProp.kind === "absent")
+                continue;
+            const kind = kindProp.kind === "found" ? constString(kindProp.expr) : undefined;
+            if (kind === undefined) {
+                unplaceable(toolAt, "computes its `kind`");
+                continue;
+            }
+            if (kind !== "connector")
+                continue;
+            const keyProp = prop(tool, "connector");
+            const key = keyProp.kind === "found" ? constString(keyProp.expr) : undefined;
+            if (key)
+                record(key, el, toolAt);
+            else
+                unplaceable(toolAt, keyProp.kind === "absent" ? "has no `connector`" : "computes its `connector`");
+        }
+    };
     const visitCalls = (node) => {
         if (ts.isCallExpression(node)) {
             const callee = ts.isIdentifier(node.expression)
@@ -343,6 +399,9 @@ function readFile(file, shown, text, connectorKey, moduleDirs, result, family) {
                             record(key, args[callee === "connector" ? 4 : 3], at);
                     }
                 }
+                else if (callee === "inlineAgent") {
+                    readAgentTools(args[0], at);
+                }
                 else if (callee === "connector") {
                     const [first] = args;
                     const literalKey = constString(first);

package/dist/registry/prepare-cli.js

@@ -58,10 +58,20 @@ export function pipelineOptions(options) {
  * `uip` client and reporter injected so tests replay recordings.
  */
 export async function prepareConnector(options) {
-    return runPipeline(pipelineOptions(options), {
-        client: defaultUipClient(),
-        reporter: consoleReporter,
-    });
+    // One `uip mcp serve` for the ten-or-so calls a prepare makes, instead of a
+    // process start per call (flow-builder-sdk#965). Closed when the pipeline
+    // is done, whichever way it ends; a host that could not be used says so
+    // once, as a warning, and the calls spawn as they did before.
+    const client = defaultUipClient({ host: { onFallback: (reason) => consoleReporter.warn(`  WARN: ${reason}`) } });
+    try {
+        return await runPipeline(pipelineOptions(options), {
+            client,
+            reporter: consoleReporter,
+        });
+    }
+    finally {
+        client.close?.();
+    }
 }
 function value(args, name) {
     const index = args.indexOf(name);

package/dist/registry/pull-cli.js

@@ -2,6 +2,7 @@ import { reportResult } from '../cli-result.js';
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { writeJsonFile } from "../core/json-file.js";
 import { CURRENT_LINK, LIBRARY_JSON_DIR, LIBRARY_MARKDOWN_DIR, cacheEntry, libraryCacheRoot, referencedConnectorKeys, } from "../core/library-cache.js";
 import { extractLibrary } from "./extractor.js";
 import { materializeRegistry } from "./materializer.js";
@@ -210,14 +211,14 @@ async function isCurrentLibrary(libraryPath, sha256) {
     }
 }
 async function writeSource(libraryPath, archive, sha256, archiveSha256, overlaySha256) {
-    await writeFile(join(libraryPath, SOURCE_FILE), `${JSON.stringify({
+    writeJsonFile(join(libraryPath, SOURCE_FILE), {
         sha256,
         archiveSha256,
         overlaySha256,
         url: archive.url ?? null,
         archive: archive.checksum ? undefined : archive.path,
         pulledAt: new Date().toISOString(),
-    }, null, 2)}\n`);
+    });
 }
 /**
  * Point `current` at an entry, replacing whatever it named.