@uipath/maestro-builder-sdk 6.16.4 → 6.16.5

package/dist/check.js

@@ -3206,14 +3206,14 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
             : `inputs: { ${undeclared[0]}: input('${undeclared[0]}') }`);
     }
     // Direction 3: an input bound to a COMPUTED EXPRESSION rather than to one
-    // reference. The platform names an agent's arguments by flat-mangling the
-    // references it finds in the node's prompts, so an expression spanning zero or
-    // several references has no single argument — and therefore no name a
-    // `{{input.<x>}}` token could address. Its data still reaches the agent (the
-    // platform derives one argument per reference inside the expression), but not
-    // under a name the prompt can use, so the placeholder would reach the model as
-    // literal text. An error rather than a warning, and for the same reason
-    // `INLINE_AGENT_UNDECLARED_PLACEHOLDER` is one: the value never arrives.
+    // reference. The platform names each of an agent's arguments after the
+    // reference path it is bound to (the shell node's `agentInputVariables`), so
+    // an expression spanning zero or several references has no single argument —
+    // and therefore no name a `{{input.<x>}}` token could address. The compiler
+    // declares no argument for it, so its value does not reach the agent, and the
+    // placeholder reaches the model as literal text. An error rather than a
+    // warning, and for the same reason `INLINE_AGENT_UNDECLARED_PLACEHOLDER` is
+    // one: the value never arrives.
     for (const [name, val] of Object.entries(inputs?.inputs ?? {})) {
         if (!(val instanceof Expr) || val.literal)
             continue;
@@ -3223,11 +3223,10 @@ function checkInlineAgent(step, inputs, diags, opts = {}) {
             continue;
         at('INLINE_AGENT_COMPOSITE_INPUT', `Inline agent step "${step}"'s input \`${name}\` is bound to a computed expression `
             + `(\`${val.js.length > 60 ? `${val.js.slice(0, 60)}…` : val.js}\`), and a prompt references it as `
-            + `\`{{input.${name}}}\`. The platform does not send the agent the names you declared: it scans the `
-            + `node's prompts for variable references and names each argument after the REFERENCE PATH `
-            + `(\`$vars.a.output.b\` → \`a__output__b\`). A computed expression is not one reference, so it has no `
-            + `single argument to name and the placeholder cannot be substituted — it would reach the model as `
-            + `that literal text.`, `compute it in a script step first, then bind the step's output: `
+            + `\`{{input.${name}}}\`. The platform does not send the agent the names you declared: it names each `
+            + `argument after the REFERENCE PATH the input is bound to (\`$vars.a.output.b\` → \`a__output__b\`). `
+            + `A computed expression is not one reference, so it gets no argument: its value does not reach the `
+            + `agent, and the placeholder reaches the model as that literal text.`, `compute it in a script step first, then bind the step's output: `
             + `.step('${name}Value', script({ code: 'return …;' })) … inputs: { ${name}: out('${name}Value') }`);
     }
     // A step id containing `__` makes the flat name AMBIGUOUS on the platform: the

package/dist/core/actions.d.ts

@@ -699,15 +699,24 @@ export interface ConversationalAgentInputs {
      */
     settings: ConversationalAgentSettings;
     /**
-     * Whether the agent's reply CLOSES the exchange. The platform's legacy
-     * default is to end it; pass `false` to keep it open for another turn.
+     * Whether the agent's reply CLOSES the exchange.
+     *
+     * @deprecated Has no effect and is not emitted. The platform retired the input:
+     * the conversational agent's v1.7 node migration removes it, and the converter
+     * always sends `conversationalService.endExchange = ''`. Wait-for-message and
+     * the end of the conversation close open exchanges.
      */
     endExchange?: boolean;
     /** Sampling temperature, 0–1. */
     temperature?: number;
     /** Max tokens in one response. */
     maxTokenPerResponse?: number;
-    /** The model's own context ceiling — informational. */
+    /**
+     * The model's own context ceiling.
+     *
+     * @deprecated Has no effect and is not emitted. Studio Web derives it from the
+     * selected model.
+     */
     modelMaxTokens?: number;
     /** How many tool-calling rounds one turn may take, 1–100. */
     maxIterations?: number;
@@ -1505,7 +1514,13 @@ export interface InlineAgentInputs {
     temperature?: number;
     /** Max tokens in one response, 0–16384. */
     maxTokenPerResponse?: number;
-    /** The model's own context ceiling — informational, e.g. `128000`. */
+    /**
+     * The model's own context ceiling, e.g. `128000`.
+     *
+     * @deprecated Has no effect and is not emitted. Studio Web derives it from the
+     * selected model each time the agent is opened, and the sidecar has no field
+     * for it.
+     */
     modelMaxTokens?: number;
     /** How many tool-calling rounds the agent may take, 1–100. */
     maxIterations?: number;

package/dist/decompile.js

@@ -1023,28 +1023,24 @@ function connectorObjectName(configuration) {
  * Returns `undefined` when the node is not one of them, so the caller can fall
  * through to the next arm.
  */
+/** The `maxIterations` Studio Web writes into every inline agent's `agent.json` (flow-workbench `getDefaultAgentContent()`). */
+const STUDIO_WEB_DEFAULT_MAX_ITERATIONS = 25;
 /**
- * An AGENT and its attached resources — the inline autonomous agent, the
- * conversational agent, and the voice agent.
- *
- * The cluster is a node plus artifact nodes on its `tool` / `context` /
- * `escalation` / `memory` handles, so this walks those edges and recovers each
- * resource as an argument rather than as a step (see {@link ARTIFACT_PORTS}).
+ * The agent configuration a SHELL agent node keeps in its sidecar, read from
+ * `<source>/agent.json` in the node's own input names: the prompts, the model,
+ * the run settings (`temperature`, `maxTokenPerResponse`, `maxIterations`,
+ * `mode`), the `guardrails` and (voice) the `voice` settings. 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.
  *
- * **The author's input NAMES are not recoverable, and that is by design.** The
- * platform does not send an agent the names you declared: it keys each argument
- * by the reference PATH, `__`-joined (`$vars.prep.output` → `prep__output`), and
- * only those flat names survive in the emitted file. Recovery therefore uses
- * them for both the `inputs` keys and the `{{input.…}}` placeholders — the same
- * 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.
+ * A run setting equal to the default a sidecar writer fills in (`temperature`
+ * 0, `maxTokens` 16384, `mode` `'standard'`) is not recovered: recompiling
+ * without it writes the same sidecar, and recovering it would add an argument
+ * the author never wrote to every agent. `mode: 'standard'` is the exception on
+ * a 1.3 node, where naming it is what selected that definition. The same goes
+ * for the inline agent's `maxIterations` 25: the SDK omits it when unset, but
+ * Studio Web always writes it (its `getDefaultAgentContent()` default), so
+ * every Studio Web-saved agent would otherwise decompile with `maxIterations: 25`.
  */
 function sidecarAgentInputs(node) {
     const inputs = (node.inputs ?? {});
@@ -1057,7 +1053,8 @@ function sidecarAgentInputs(node) {
     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.');
+            + 'so its prompts, model and run settings decompile empty. Keep <source>/agent.json beside the .flow '
+            + '(download the whole project, not just the .flow).');
         return {};
     }
     let agent;
@@ -1065,7 +1062,7 @@ function sidecarAgentInputs(node) {
         agent = JSON.parse(raw);
     }
     catch {
-        warnOnce(`agent step "${node.id}": ${path} is not valid JSON, so its prompts and model decompile empty.`);
+        warnOnce(`agent step "${node.id}": ${path} is not valid JSON, so its prompts, model and run settings decompile empty.`);
         return {};
     }
     const messages = (Array.isArray(agent?.messages) ? agent.messages : []);
@@ -1076,13 +1073,50 @@ function sidecarAgentInputs(node) {
     const settings = (agent?.settings ?? {});
     const system = content('system');
     const user = content('user');
+    const isVoice = node.type === T.voiceAgent;
+    const numberUnless = (v, dflt) => typeof v === 'number' && v !== dflt ? v : undefined;
+    // The voice agent's temperature and token cap live in `settings.voice`, not here.
+    const temperature = isVoice ? undefined : numberUnless(settings.temperature, 0);
+    const maxTokenPerResponse = isVoice ? undefined : numberUnless(settings.maxTokens, 16384);
+    // Studio Web's default for the inline agent; the other families keep any value.
+    const maxIterations = node.type === T.inlineAgent
+        ? 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.
+    const mode = node.type === T.inlineAgent && typeof settings.mode === 'string'
+        && (settings.mode !== 'standard' || node.typeVersion === '1.3')
+        ? settings.mode : undefined;
     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 } : {}),
+        ...(temperature === undefined ? {} : { temperature }),
+        ...(maxTokenPerResponse === undefined ? {} : { maxTokenPerResponse }),
+        ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(Array.isArray(agent?.guardrails) && agent.guardrails.length > 0 ? { guardrails: agent.guardrails } : {}),
+        ...(isVoice && settings.voice && typeof settings.voice === 'object' ? { voice: settings.voice } : {}),
     };
 }
+/**
+ * An AGENT and its attached resources — the inline autonomous agent, the
+ * conversational agent, and the voice agent.
+ *
+ * The cluster is a node plus artifact nodes on its `tool` / `context` /
+ * `escalation` / `memory` handles, so this walks those edges and recovers each
+ * resource as an argument rather than as a step (see {@link ARTIFACT_PORTS}).
+ *
+ * **The author's input NAMES are not recoverable, and that is by design.** The
+ * platform does not send an agent the names you declared: it keys each argument
+ * by the reference PATH, `__`-joined (`$vars.prep.output` → `prep__output`), and
+ * only those flat names survive in the emitted file. Recovery therefore uses
+ * them for both the `inputs` keys and the `{{input.…}}` placeholders — the same
+ * arguments reach the model, spelled the platform's way. (Node ids are
+ * preserved exactly; only these logical names change.)
+ */
 function emitAgentCluster(node, imp, inputNames, graph) {
     // A key on the node wins over the sidecar's copy of it.
     const i = { ...sidecarAgentInputs(node), ...(node.inputs ?? {}) };
@@ -1094,10 +1128,12 @@ function emitAgentCluster(node, imp, inputNames, graph) {
         const raw = unwrapPlain(v);
         return typeof raw === 'number' ? String(raw) : undefined;
     };
-    // Prompts: invert `renderInlineAgentPrompt`. It replaced each
-    // `{{input.<name>}}` with that input's rendered binding, so the bindings in
-    // `agentInputVariables` are exactly what to put back — longest first, so a
-    // shorter binding cannot eat a longer one's prefix.
+    // Prompts. A sidecar prompt already speaks `{{input.<flatName>}}`, so this
+    // leaves it alone. An EMBEDDED node's prompt (Studio Web with the
+    // self-contained flag on, or an SDK before #927) carries each input as its
+    // rendered binding instead; the bindings in `agentInputVariables` are exactly
+    // what to put back — longest first, so a shorter binding cannot eat a longer
+    // one's prefix.
     const vars = (Array.isArray(i.agentInputVariables) ? i.agentInputVariables : []);
     const refs = vars
         .filter((v) => typeof v.id === 'string' && typeof v.binding === 'string')
@@ -1359,10 +1395,8 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             // `settings` is required on ConversationalAgentInputs, so an empty one
             // stays as `{}`, which check then reports as CONV_AGENT_NO_TURN.
             ['settings', settingsSrc || '{}'],
-            ['endExchange', unwrapPlain(i.endExchange) === false ? 'false' : undefined],
             ['temperature', num(i.temperature)],
             ['maxTokenPerResponse', num(i.maxTokenPerResponse)],
-            ['modelMaxTokens', num(i.modelMaxTokens)],
             ['maxIterations', num(i.maxIterations)],
             ['guardrails', guardrails],
             ['source', str(plain(i.source) ?? '')],
@@ -1376,7 +1410,6 @@ function emitAgentCluster(node, imp, inputNames, graph) {
         ['returns', returns],
         ['temperature', num(i.temperature)],
         ['maxTokenPerResponse', num(i.maxTokenPerResponse)],
-        ['modelMaxTokens', num(i.modelMaxTokens)],
         ['maxIterations', num(i.maxIterations)],
         ['mode', plain(i.mode) !== undefined ? str(plain(i.mode)) : undefined],
         ['guardrails', guardrails],

package/dist/serialize.js

@@ -5110,15 +5110,18 @@ export function serialize(built, opts = {}) {
             // 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.
+            // `inputSchema`.
+            //
+            // The run settings (`mode`, `temperature`, `maxTokenPerResponse`,
+            // `maxIterations`, `guardrails`) live in the sidecar too. The node keeps
+            // exactly the keys Studio Web's own strip keeps (`toAgentShellInputs`,
+            // @uipath/flow-schema): anything else is discarded on hydrate, and while
+            // present it makes Studio Web "trust the .flow" when the sidecar folder is
+            // missing (`flowNodeHasRealInputs`), flushing a prompt-less agent.json.
+            // `modelMaxTokens` is written nowhere: the designer derives it from the
+            // selected model.
             node.inputs = {
                 source,
-                ...(s.mode === undefined ? {} : { mode: s.mode }),
-                ...(s.temperature === undefined ? {} : { temperature: s.temperature }),
-                ...(s.maxTokenPerResponse === undefined ? {} : { maxTokenPerResponse: s.maxTokenPerResponse }),
-                ...(s.modelMaxTokens === undefined ? {} : { modelMaxTokens: s.modelMaxTokens }),
-                ...(s.maxIterations === undefined ? {} : { maxIterations: s.maxIterations }),
-                ...(s.guardrails === undefined ? {} : { guardrails: s.guardrails }),
                 // The two DESCRIPTOR ARRAYS. `agentInputVariables` entries carry the
                 // binding expression; `agentOutputVariables` entries are name + type only,
                 // and the runtime's structured final call fills exactly these keys.
@@ -5695,20 +5698,15 @@ 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.
+            // A SHELL node, like the inline agent's (#927): exactly the keys
+            // `toAgentShellInputs` keeps. The system prompt, the model and the run
+            // settings live only in the sidecar (`metadata.isConversational` there is
+            // the family flag). `endExchange` is written nowhere: the platform retired
+            // it (the node's v1.7 migration drops it, and the converter always sends
+            // `conversationalService.endExchange = ''`).
             node.inputs = {
                 source,
-                // The family's own flag — every instance of this node IS conversational.
-                isConversational: true,
                 conversationalAgentSettings: settings,
-                ...(s.endExchange === undefined ? {} : { endExchange: s.endExchange }),
-                ...(s.temperature === undefined ? {} : { temperature: s.temperature }),
-                ...(s.maxTokenPerResponse === undefined ? {} : { maxTokenPerResponse: s.maxTokenPerResponse }),
-                ...(s.modelMaxTokens === undefined ? {} : { modelMaxTokens: s.modelMaxTokens }),
-                ...(s.maxIterations === undefined ? {} : { maxIterations: s.maxIterations }),
-                ...(s.guardrails === undefined ? {} : { guardrails: s.guardrails }),
             };
             scope.nodes.push(node);
             sidecars.push({
@@ -5771,13 +5769,11 @@ export function serialize(built, opts = {}) {
             // 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`).
+            // The node keeps exactly the keys `toAgentShellInputs` keeps;
+            // `maxIterations` and `metadata.isConversational` are in the sidecar.
             node.inputs = {
                 source,
                 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 }),
                 ...(plan.refs.length === 0 ? {} : {
                     agentInputVariables: plan.refs.map((r) => ({
                         id: r.flatName,

package/package.json

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