@uipath/maestro-builder-sdk 6.16.2 → 6.16.4

package/dist/check.js

@@ -50,9 +50,9 @@ function checkFlow(built, ancestors, opts = {}) {
         checkTrigger(built.trigger, diags, opts);
     if (built.trigger?.kind === 'form' && built.inputs.length === 0) {
         diags.push({
-            level: 'warning', code: 'FORM_TRIGGER_NO_INPUTS', step: 'trigger',
-            message: `formTrigger() renders one field per flow input, and this flow declares none — the person `
-                + `gets an empty form with only a submit button.`,
+            level: 'error', code: 'FORM_TRIGGER_NO_INPUTS', step: 'trigger',
+            message: `formTrigger() renders one field per flow input, and this flow declares none. `
+                + `Publish skips a form with no fields, so the flow would ship with no form.`,
             suggestion: `.input({ amount: types.number })`,
         });
     }
@@ -857,7 +857,22 @@ function checkFlow(built, ancestors, opts = {}) {
             }
         }
         else {
-            checkTrigger(ep.trigger, diags, opts, `onEvent() entry point "${ep.id}"`);
+            checkTrigger(ep.trigger, diags, opts, ep.id);
+        }
+        if (ep.trigger.kind === 'form' && ep.inputs.length === 0) {
+            diags.push({
+                level: 'error', code: 'FORM_TRIGGER_NO_INPUTS', step: ep.id,
+                message: `.entryPoint("${ep.id}", formTrigger()) renders one field per entry-point input, and it declares none. `
+                    + `Publish skips a form with no fields, so this root would ship with no form.`,
+                suggestion: `.entryPoint("${ep.id}", formTrigger(), { inputs: { amount: types.number } })`,
+            });
+        }
+        if ((ep.trigger.kind === 'conversation' || ep.trigger.kind === 'voice') && ep.inputs.length) {
+            diags.push({
+                level: 'warning', code: 'TRIGGER_INPUTS_IGNORED', step: ep.id,
+                message: `.entryPoint("${ep.id}") declares inputs, but a ${ep.trigger.kind} trigger starts with only what the platform `
+                    + `supplies (${ep.trigger.kind === 'voice' ? 'callContext' : 'conversationId'}). Its inputs are never passed.`,
+            });
         }
         for (const inp of ep.inputs) {
             const collides = built.inputs.some((g) => g.name === inp.name)
@@ -879,6 +894,17 @@ function checkFlow(built, ancestors, opts = {}) {
             message: 'Entry points join the shared body, but this flow has no shared step. Add one, or end each prefix terminally.',
         });
     }
+    const conversationRoots = [
+        ...(built.trigger?.kind === 'conversation' ? [triggerId] : []),
+        ...(built.entryPoints ?? []).filter((ep) => ep.trigger.kind === 'conversation').map((ep) => ep.id),
+    ];
+    if (conversationRoots.length > 1) {
+        diags.push({
+            level: 'error', code: 'SINGLE_CONVERSATION_TRIGGER', step: conversationRoots[1],
+            message: `Only one conversationTrigger() is allowed per flow, and ${conversationRoots.length} roots use one: `
+                + `${conversationRoots.map((id) => `"${id}"`).join(', ')}. Keep one and give the others another trigger.`,
+        });
+    }
     checkStepRefs(built, diags);
     checkArmScopedReads(built, diags);
     // A fire-and-forget dispatch publishes no output: any read of it would wait
@@ -1731,9 +1757,11 @@ function checkNodeUpdates(built, diags) {
     };
     visit(built.steps);
 }
-function checkTrigger(spec, diags, opts = {}, where) {
+function checkTrigger(spec, diags, opts = {}, entryPointId) {
+    const where = entryPointId === undefined ? undefined : `onEvent() entry point "${entryPointId}"`;
+    const call = entryPointId === undefined ? '.trigger()' : `.entryPoint("${entryPointId}")`;
     const push = (level) => (code, message, suggestion) => {
-        diags.push({ level, code, message, step: 'trigger', ...(suggestion ? { suggestion } : {}) });
+        diags.push({ level, code, message, step: entryPointId ?? 'trigger', ...(suggestion ? { suggestion } : {}) });
     };
     const at = push('error');
     // Types are stripped at run time, so `.trigger({ every: 'R/PT1H' })` (the spec
@@ -1758,7 +1786,7 @@ function checkTrigger(spec, diags, opts = {}, where) {
     if (spec?.kind === 'conversation' || spec?.kind === 'voice')
         return;
     if (spec?.kind !== 'scheduled') {
-        at('TRIGGER_UNKNOWN_KIND', `.trigger() was given ${JSON.stringify(spec?.kind)}, which is not a trigger. `
+        at('TRIGGER_UNKNOWN_KIND', `${call} was given ${JSON.stringify(spec?.kind)}, which is not a trigger. `
             + `Wrap it in a factory: scheduled({ every: 'R/PT1H' }) for a schedule, `
             + `onEvent({ connector, event, where, connection, folder }) to start on a connector event, formTrigger() to start from a `
             + `submitted form, or conversationTrigger() to start on a new conversation. Omit .trigger() entirely `

package/dist/core/actions.d.ts

@@ -1407,20 +1407,19 @@ export interface InlineAgentInputs {
      * ```
      *
      * Why a placeholder rather than an interpolated expression: an inline agent is two
-     * artifacts, and its prompt exists in THREE dialects. You write one; the compiler
-     * emits the other two.
+     * artifacts, and its prompt exists in TWO dialects. You write one; the compiler
+     * emits the other into the `agent.json` sidecar. The `.flow` node carries no copy
+     * of the prompt: it is a shell, so Studio Web reads the sidecar.
      *
      *   1. yours          `{{input.claim}}`
-     *   2. the NODE's     `=js:$vars.prepare.output.claimRef`   ← what the platform SCANS
-     *   3. the AGENT.JSON `{{input.prepare__output__claimRef}}` ← what the runtime SENDS
-     *
-     * The third exists because the platform does not send an agent the names you
-     * declared: it scans the node's prompts for `$vars.*` references and names each
-     * argument after the reference PATH, `__`-joined. For a flow input the two
-     * coincide (`$vars.notes` → `notes`); for a step output they do not, and a sidecar
-     * still saying `{{input.claim}}` templates against a key that is not there — the
-     * literal text reaches the model. See the inline-agent node reference (`website/reference/inline-agent.md`)
-     * §"The three prompt DIALECTS".
+     *   2. the AGENT.JSON `{{input.prepare__output__claimRef}}` ← what the runtime SENDS
+     *
+     * The second exists because the platform does not send an agent the names you
+     * declared: it names each argument after the bound reference PATH, `__`-joined.
+     * For a flow input the two coincide (`$vars.notes` → `notes`); for a step output
+     * they do not, and a sidecar still saying `{{input.claim}}` templates against a key
+     * that is not there — the literal text reaches the model. See the inline-agent
+     * node reference (`website/reference/inline-agent.md`) §"The prompt dialects".
      *
      * **The answer's shape is `returns`, not the prompt.** `returns` becomes the node's
      * `agentOutputVariables` and the `agent.json` `outputSchema` — what Studio Web's

package/dist/decompile-cli.js

@@ -19,7 +19,7 @@
  */
 import { reportResult } from './cli-result.js';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { defaultSourceOut, workDirBeside, writeSource } from './workdir.js';
 import { decompile } from './decompile.js';
 import { resolveFlowRefs } from './ref-resolve.js';
@@ -65,6 +65,15 @@ export function run(argv) {
         // writable band) go to stderr, where the agent running the brownfield loop
         // reads them before compile refuses.
         warn: (message) => console.error(`flow-decompile: warning: ${message}`),
+        // A shell agent node's prompts live in `<source>/agent.json` beside the .flow.
+        readSidecar: (relativePath) => {
+            try {
+                return readFileSync(join(dirname(resolve(pos)), relativePath), 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        },
     });
     const out = opt(argv, '-o') ?? defaultSourceOut(`${baseName(flow)}.flow.ts`);
     writeSource(out, ts);

package/dist/decompile.d.ts

@@ -133,6 +133,17 @@ export interface DecompileOptions {
      * `compile` will refuse it). The CLI prints these on stderr.
      */
     warn?: (message: string) => void;
+    /**
+     * Reads a file of the flow's project, by path relative to the `.flow`'s
+     * directory; returns `undefined` when it is absent. Used for an agent node
+     * that is a SHELL (no prompts on the node, the shape compile writes since
+     * #927): its prompts, model and voice settings are read back from
+     * `<source>/agent.json`. The sidecar speaks flat input names
+     * (`{{input.start__output__notes}}`), so the recovered source declares its
+     * inputs under those names — the same flow, not the same spelling. Without a
+     * reader, a shell agent decompiles with empty prompts and a warning.
+     */
+    readSidecar?: (relativePath: string) => string | undefined;
 }
 export declare function decompile(flow: FlowFile, options?: DecompileOptions): string;
 export {};

package/dist/decompile.js

@@ -79,6 +79,8 @@ let runStrict = false;
 /** `DecompileOptions.warn` for the current run, and the messages already sent to it (one line per finding). */
 let runWarn;
 let runWarned = new Set();
+/** `DecompileOptions.readSidecar` for the current run. */
+let runReadSidecar;
 function warnOnce(message) {
     if (runWarned.has(message))
         return;
@@ -1037,8 +1039,53 @@ function connectorObjectName(configuration) {
  * arguments reach the model, spelled the platform's way. (Node ids are
  * preserved exactly; only these logical names change.)
  */
+/**
+ * The agent configuration a SHELL agent node keeps in its sidecar: the prompts,
+ * the model and (voice) the `voice` settings, read from `<source>/agent.json`
+ * in the node's own input names. Empty when the node carries prompts itself (an
+ * embedded node, e.g. a `.flow` saved by Studio Web with the self-contained
+ * flag on), or when no sidecar can be read.
+ */
+function sidecarAgentInputs(node) {
+    const inputs = (node.inputs ?? {});
+    if (typeof inputs.systemPrompt === 'string' || typeof inputs.userPrompt === 'string')
+        return {};
+    const source = unwrapSource(inputs.source);
+    if (!source)
+        return {};
+    const path = `${source}/agent.json`;
+    const raw = runReadSidecar?.(path);
+    if (raw === undefined) {
+        warnOnce(`agent step "${node.id}" carries no prompts and ${path} was not found beside the .flow, `
+            + 'so its prompts and model decompile empty. Decompile the .flow from inside its project directory.');
+        return {};
+    }
+    let agent;
+    try {
+        agent = JSON.parse(raw);
+    }
+    catch {
+        warnOnce(`agent step "${node.id}": ${path} is not valid JSON, so its prompts and model decompile empty.`);
+        return {};
+    }
+    const messages = (Array.isArray(agent?.messages) ? agent.messages : []);
+    const content = (role) => {
+        const c = messages.find((m) => m.role === role)?.content;
+        return typeof c === 'string' ? c : undefined;
+    };
+    const settings = (agent?.settings ?? {});
+    const system = content('system');
+    const user = content('user');
+    return {
+        ...(system === undefined ? {} : { systemPrompt: system }),
+        ...(user === undefined ? {} : { userPrompt: user }),
+        ...(typeof settings.model === 'string' ? { model: settings.model } : {}),
+        ...(node.type === T.voiceAgent && settings.voice && typeof settings.voice === 'object' ? { voice: settings.voice } : {}),
+    };
+}
 function emitAgentCluster(node, imp, inputNames, graph) {
-    const i = (node.inputs ?? {});
+    // A key on the node wins over the sidecar's copy of it.
+    const i = { ...sidecarAgentInputs(node), ...(node.inputs ?? {}) };
     const plain = (v) => {
         const raw = unwrapSource(v);
         return raw === undefined || raw === '' ? undefined : raw;
@@ -2616,6 +2663,7 @@ export function decompile(flow, options = {}) {
     const importSpecifier = options.importSpecifier ?? './flow-sdk.js';
     runStrict = options.bestEffort === false;
     runWarn = options.warn;
+    runReadSidecar = options.readSidecar;
     runWarned = new Set();
     runDefPairs = new Set((flow.definitions ?? [])
         .filter((d) => typeof d?.nodeType === 'string' && typeof d?.version === 'string')

package/dist/flow-sdk.d.ts

@@ -661,7 +661,7 @@ export interface FlowLayout {
 export interface BuiltEntryPoint {
     /** The trigger node's id — also the root expressions read (`$vars.<id>.output.x`). */
     id: string;
-    /** What fires this root: `manual()`, `scheduled(...)`, or `onEvent(...)`. */
+    /** What fires this root: any built-in trigger factory, or a custom trigger. */
     trigger: TriggerSpec;
     /** Node options for the trigger node — exact `version` selection. */
     options?: NodeOptions;
@@ -1278,8 +1278,9 @@ declare class FlowBuilder extends StepList {
      *
      * @param id - The root's trigger-node id — unique among entry points, steps,
      * and the default trigger id. Expressions read it as `$vars.<id>.output.*`.
-     * @param trigger - What fires this root: `manual()`, `scheduled(...)`, or
-     * `onEvent(...)`.
+     * @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 prefixFn - Optional sub-builder for the root's prefix steps.

package/dist/flow-sdk.js

@@ -993,8 +993,9 @@ class FlowBuilder extends StepList {
      *
      * @param id - The root's trigger-node id — unique among entry points, steps,
      * and the default trigger id. Expressions read it as `$vars.<id>.output.*`.
-     * @param trigger - What fires this root: `manual()`, `scheduled(...)`, or
-     * `onEvent(...)`.
+     * @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 prefixFn - Optional sub-builder for the root's prefix steps.

package/dist/serialize.js

@@ -2204,10 +2204,9 @@ function inlineAgentDef(spec) {
 /**
  * Classify a RENDERED input value (the output of {@link renderValue}).
  *
- * The `=js:` test is the same one `renderInlineAgentPrompt` uses, deliberately:
- * both halves of the emission must agree about what is an expression, and a
- * literal string that happens to begin with `=js:` is already treated as one
- * there.
+ * A rendered value is an expression exactly when it starts with `=js:` — the
+ * same test the rest of the serializer applies, so a literal string that
+ * happens to begin with `=js:` is treated as one everywhere.
  */
 function classifyAgentInput(rendered) {
     if (typeof rendered !== 'string' || !rendered.startsWith('=js:')) {
@@ -2471,40 +2470,6 @@ function promptTokens(content) {
         tokens.push({ type: 'simpleText', rawString: content.slice(last) });
     return tokens.length ? tokens : [{ type: 'simpleText', rawString: content }];
 }
-/**
- * Render an inline agent's prompt for the NODE, which speaks a different dialect
- * from the `agent.json`.
- *
- * The author writes `{{input.<name>}}`, which is what the agent's own template
- * language uses and what goes into `agent.json` verbatim. The node's copy has to
- * carry the FLOW expression instead: flow-v1's `preDeriveAgentInputDefinitions`
- * builds the deployed input list by scanning the node's prompts for `$vars.*`
- * references, and — when its caller prunes — drops any `agentInputVariables` entry no
- * such reference points at. A prompt with no references can therefore deploy an agent
- * that receives nothing, with the authored list sitting in the file unused.
- *
- * So each placeholder becomes the rendered binding of that input, `=js:`-prefixed the
- * way an embedded expression is read. One caveat that comes with that encoding:
- * an embedded run has no terminator, so it is read to
- * end-of-line and then backed off token by token until a prefix evaluates. That
- * resolves `"Notes: =js:$vars.notes and then some"` correctly, but a placeholder
- * followed by more text on the same line is doing more work than one at end of line.
- *
- * A placeholder naming something `inputs` does not declare is left ALONE rather than
- * silently deleted: it reaches the model as literal `{{input.x}}`, which is visible,
- * and `check` names it.
- */
-function renderInlineAgentPrompt(template, inputs, rename) {
-    return template.replace(INPUT_PLACEHOLDER, (whole, name) => {
-        if (!Object.prototype.hasOwnProperty.call(inputs, name))
-            return whole;
-        const rendered = renderValue(inputs[name], rename);
-        // A literal binding needs no expression at all — inline the value.
-        if (typeof rendered === 'string' && rendered.startsWith('=js:'))
-            return rendered;
-        return String(rendered);
-    });
-}
 /**
  * The parts every `uipath.ixp.*` definition shares, bundled verbatim from
  * `uip maestro flow registry get` (2026-07-31, after `registry pull --force`).
@@ -4838,9 +4803,9 @@ export function serialize(built, opts = {}) {
                 ? scheduleInputs(built.trigger.inputs, triggerId)
                 : built.trigger?.kind === 'form'
                     ? {
-                        // The definition marks the family an entry point (`model.entryPointId:
-                        // true`); the id is the node's own, the scheduled trigger's convention.
-                        entryPointId: triggerId,
+                        // A GUID: publish keys the form's FormTrigger binding on it and skips
+                        // the form when it is not one.
+                        entryPointId: stableId(`${built.id}:${triggerId}:entryPoint`),
                         schema: { fields: formTriggerFields(built.inputs), outcomes: [] },
                     }
                     : built.trigger?.kind === 'conversation' || built.trigger?.kind === 'voice'
@@ -5136,14 +5101,18 @@ export function serialize(built, opts = {}) {
             // What the PLATFORM will call each of these — computed once and shared by
             // the descriptor array below and the sidecar. See `agentInputPlan`.
             const plan = agentInputPlan(nodeInputs, scope.rename);
+            // A SHELL node (#927): the prompts and the model live only in the
+            // `<source>/agent.json` sidecar written below, never on the node. Studio
+            // Web decides which copy wins by `hasEmbeddedAgentContent`
+            // (@uipath/flow-schema): any `systemPrompt`/`userPrompt` string on the node
+            // makes the `.flow` authoritative and the sidecar is skipped, so a node copy
+            // shadowed the sidecar and lost the input tokens and the tool configuration
+            // on the first save. With no prompt strings the converter also keeps the
+            // `agentInputVariables` below as written (`canPruneAgentInputs` is false),
+            // and `uip maestro flow debug` reconciles them against the sidecar's
+            // `inputSchema` — the shape the v1 skill and `uip agent refresh` write.
             node.inputs = {
                 source,
-                // The NODE's dialect: `{{input.x}}` → the flow expression, so flow-v1's
-                // input-derivation pre-pass can see the reference. See
-                // `renderInlineAgentPrompt`.
-                systemPrompt: renderInlineAgentPrompt(s.systemPrompt, nodeInputs, scope.rename),
-                userPrompt: renderInlineAgentPrompt(s.userPrompt, nodeInputs, scope.rename),
-                model: s.model,
                 ...(s.mode === undefined ? {} : { mode: s.mode }),
                 ...(s.temperature === undefined ? {} : { temperature: s.temperature }),
                 ...(s.maxTokenPerResponse === undefined ? {} : { maxTokenPerResponse: s.maxTokenPerResponse }),
@@ -5154,11 +5123,10 @@ export function serialize(built, opts = {}) {
                 // binding expression; `agentOutputVariables` entries are name + type only,
                 // and the runtime's structured final call fills exactly these keys.
                 //
-                // `id` is the FLAT NAME, not the author's — the platform re-derives this
-                // array from the node's prompts and keeps a pre-existing entry only when
-                // its id already IS a flatName (`deriveAgentInputVariables:506-509`). One
-                // entry per flatName, so two logical names bound to the same reference
-                // claim one argument rather than two.
+                // `id` is the FLAT NAME, not the author's — the name the runtime's
+                // JobArguments are keyed by, and the key the CLI reconciles against the
+                // sidecar's `inputSchema`. One entry per flatName, so two logical names
+                // bound to the same reference claim one argument rather than two.
                 agentInputVariables: plan.refs.map((r) => ({
                     id: r.flatName,
                     type: 'string',
@@ -5727,10 +5695,11 @@ export function serialize(built, opts = {}) {
                 if (v !== undefined)
                     settings[key] = v;
             }
+            // A SHELL node, like the inline agent's (#927): the system prompt and the
+            // model live only in the sidecar, so Studio Web reads the sidecar instead
+            // of letting a node copy shadow it.
             node.inputs = {
                 source,
-                systemPrompt: s.systemPrompt,
-                model: s.model,
                 // The family's own flag — every instance of this node IS conversational.
                 isConversational: true,
                 conversationalAgentSettings: settings,
@@ -5797,15 +5766,18 @@ export function serialize(built, opts = {}) {
             delete node.model;
             const nodeInputs = s.inputs ?? {};
             const plan = agentInputPlan(nodeInputs, scope.rename);
+            // A SHELL node (#927): the system prompt and the `voice` settings live only
+            // in the sidecar's `messages` and `settings.voice`. On a voice node either
+            // one makes Studio Web treat the `.flow` as authoritative and skip the
+            // sidecar (`hasEmbeddedAgentContent`). `uip maestro flow debug` builds the
+            // voice agent from the sidecar (`packageInlineAgents`).
             node.inputs = {
                 source,
-                systemPrompt: renderInlineAgentPrompt(s.systemPrompt, nodeInputs, scope.rename),
                 callContext: renderValue(toExpr(s.callContext), scope.rename),
                 // The platform's own flag for this family — every voice agent IS
                 // conversational, and the definition declares the field.
                 isConversational: true,
                 ...(s.maxIterations === undefined ? {} : { maxIterations: s.maxIterations }),
-                ...(s.voice === undefined ? {} : { voice: { ...s.voice } }),
                 ...(plan.refs.length === 0 ? {} : {
                     agentInputVariables: plan.refs.map((r) => ({
                         id: r.flatName,
@@ -6842,10 +6814,28 @@ export function serialize(built, opts = {}) {
                     ...scheduleInputs(epSpec.inputs, ep.id),
                 };
             }
-            else {
+            else if (epSpec.kind === 'form') {
+                node = makeNode(NODE_TYPE.formTrigger, ep.id, 'Form trigger', { requestedVersion });
+                node.inputs = {
+                    entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`),
+                    schema: { fields: formTriggerFields(ep.inputs), outcomes: [] },
+                };
+            }
+            else if (epSpec.kind === 'conversation') {
+                node = makeNode(NODE_TYPE.conversationTrigger, ep.id, 'Conversation trigger', { requestedVersion });
+                node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
+            }
+            else if (epSpec.kind === 'voice') {
+                node = makeNode(NODE_TYPE.voiceTrigger, ep.id, 'Incoming call trigger', { requestedVersion });
+                node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
+            }
+            else if (epSpec.kind === 'manual') {
                 node = makeNode(NODE_TYPE.trigger, ep.id, 'Manual trigger', { requestedVersion });
                 node.inputs = { entryPointId: stableId(`${built.id}:${ep.id}:entryPoint`) };
             }
+            else {
+                throw new Error(`.entryPoint("${ep.id}"): unsupported trigger kind ${JSON.stringify(epSpec.kind)}.`);
+            }
             root.nodes.push(node);
             const prefixTails = emit(ep.steps, [{ node: ep.id, port: 'output' }], root);
             for (const t of prefixTails) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.16.2",
+  "version": "6.16.4",
   "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": "f8da41b16f3176129d44eeb3dbd1f6c8be1ecfef"
+  "gitref": "eac0393e29eed1fe0992c8923b88964e50483eaf"
 }