@uipath/maestro-builder-sdk 6.16.3 → 6.16.4

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/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`).
@@ -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,

package/package.json

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