@uipath/maestro-builder-sdk 6.8.6 → 6.9.0

package/dist/check.d.ts

@@ -164,3 +164,22 @@ export declare const SCHEDULE_PATTERN: string;
  * and day names, and the Quartz specials `L W LW ? * #`.
  */
 export declare const SCHEDULE_CRON_PATTERN: string;
+/**
+ * The phrase in `text` that tells a model to answer in JSON TEXT, or `undefined`.
+ *
+ * `check` uses it for `INLINE_AGENT_PROMPT_JSON_TEXT`, passing the step's `returns`
+ * keys so the brace form only counts a brace that spells one of them. Without
+ * `returnKeys` (the example and doc sweeps) any quoted identifier key counts.
+ * `{{input.*}}` placeholders are removed first, so an input named `json` never
+ * matches.
+ *
+ * @example
+ * ```ts
+ * jsonTextDirective('Return ONLY a JSON object with keys "subject" and "body".'); // 'Return ONLY a JSON'
+ * jsonTextDirective('Return ONLY {"category","priority"}.', ['category']);       // '{"category",'
+ * jsonTextDirective('Return a result conforming to the output schema.');          // undefined
+ * jsonTextDirective('Do not return JSON.');                                       // undefined
+ * jsonTextDirective('Answer the question using the JSON data below.');            // undefined
+ * ```
+ */
+export declare function jsonTextDirective(text: string, returnKeys?: readonly string[]): string | undefined;

package/dist/check.js

@@ -3154,6 +3154,106 @@ function checkAgentRead(name, field, rest, spec, step, diags) {
         ...(nearest ? { suggestion: `out('${name}', '${nearest}')` } : {}),
     });
 }
+// ─── an inline agent's prompt asking for JSON text ───────────────────────────────
+//
+// The phrase table behind `INLINE_AGENT_PROMPT_JSON_TEXT`. It is kept narrow on
+// purpose, because the rule is an error. Three shapes count, and each skips a
+// negation anywhere earlier in the same clause ("Do not return JSON", "Do not wrap
+// the answer in JSON", "Return the items, not as JSON"):
+//
+//  - DIRECT: an output verb, then only words from a closed qualifier list, then
+//    `json` — "Return ONLY a JSON object", "Return only the typed JSON contract".
+//  - VIA: an output verb, up to two words, then `as` / `in` / `with`, qualifiers,
+//    `json` — "Format your answer as JSON", "Respond with valid JSON".
+//  - BRACE: a quoted-key brace whose key is one of the step's own `returns` keys —
+//    `Return ONLY {"category","priority"}` next to `returns: { category, priority }`.
+//
+// A word outside the qualifier list ends a DIRECT match, so JSON as DATA does not
+// count in the DIRECT form: "Answer the question using the JSON data below", "Give
+// a summary of the JSON ticket", "Return the invoice number from the JSON". The VIA
+// form allows two free words, so it can still fire on JSON as a topic ("Answer in
+// Spanish with JSON examples"); the tail skips the common data nouns after `json`
+// (keys, data, record, examples, input) and the JSON-family FORMATS a string field
+// legitimately holds (JSON Schema, JSON Patch, JSON-LD, JSON Lines, …). `write` is
+// not a verb here: "You help users write JSON" is a topic, not an answer shape.
+//
+// The skills repo's preview-doc gate (tests/tasks/uipath-maestro-flow/_shared/
+// test_preview_inline_agent_prompts.py) ports this table to Python and loads a
+// byte-identical copy of tests/fixtures/inline-agent-prompt-vectors.json, so
+// change the table, the fixture and the port together.
+const JSON_TEXT_VERBS = 'return|respond|reply|output|answer|produce|emit|format|give|provide';
+/** Words that are only ever qualifiers of the answer's shape, never the thing it is about. */
+const JSON_TEXT_QUALIFIERS = [
+    'only', 'just', 'exactly', 'strictly', 'solely', 'simply', 'a', 'an', 'one', 'single', 'the',
+    'your', 'its', 'this', 'that', 'valid', 'raw', 'pure', 'plain', 'strict', 'compact', 'minified',
+    'well-formed', 'properly', 'formatted', 'typed', 'declared', 'structured', 'following', 'same',
+    'final', 'back', 'proper', 'correct', 'machine-readable', 'parseable', 'parsable',
+];
+/** A negation anywhere earlier in the same clause, or anywhere in the match's gap. */
+const JSON_TEXT_NEGATIONS = new Set(['not', 'never', 'no', 'dont', 'without', 'rather', 'instead', 'avoid']);
+const isJsonTextNegation = (w) => JSON_TEXT_NEGATIONS.has(w) || w.endsWith("n't") || w.endsWith('n’t');
+const JSON_TEXT_WORD = "[A-Za-z][\\w'’-]*";
+/** Words are separated by spaces, tabs or a comma — never a newline or a full stop. */
+const JSON_TEXT_SEP = '[ \\t]*,?[ \\t]+';
+const JSON_TEXT_QUAL = `(?:${[...JSON_TEXT_QUALIFIERS].sort((a, b) => b.length - a.length).join('|')})\\b`;
+// `(?<![-\w])` skips `--output json`; `(?!\.\w)` skips `JSON.parse` / `JSON.stringify`;
+// `(?!-(?:ld|rpc)\b)` skips JSON-LD / JSON-RPC (`\b` matches before the hyphen);
+// the last lookahead skips "the JSON below" / "the JSON provided" / "the JSON you
+// get", data nouns ("the JSON keys", "JSON examples") and JSON-family formats
+// ("JSON Schema", "JSON Patch", "the JSON path", "a JSON Web Token").
+const JSON_TEXT_TAIL = `json\\b(?!\\.\\w)(?!-(?:ld|rpc)\\b)(?![ \\t]+(?:below|above|provided|given|you`
+    + `|keys?|data|records?|examples?|inputs?`
+    + `|schemas?|patch|path|pointer|lines|rpc|web[ \\t]+tokens?)\\b)`;
+const JSON_TEXT_VERB = `(?<![-\\w])(?:${JSON_TEXT_VERBS})\\b`;
+const JSON_TEXT_DIRECT = new RegExp(`${JSON_TEXT_VERB}((?:${JSON_TEXT_SEP}${JSON_TEXT_QUAL}){0,5})${JSON_TEXT_SEP}${JSON_TEXT_TAIL}`, 'gi');
+const JSON_TEXT_VIA = new RegExp(`${JSON_TEXT_VERB}((?:${JSON_TEXT_SEP}${JSON_TEXT_WORD}){0,2}?)${JSON_TEXT_SEP}(?:as|in|with)`
+    + `((?:${JSON_TEXT_SEP}${JSON_TEXT_QUAL}){0,4})${JSON_TEXT_SEP}${JSON_TEXT_TAIL}`, 'gi');
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * The phrase in `text` that tells a model to answer in JSON TEXT, or `undefined`.
+ *
+ * `check` uses it for `INLINE_AGENT_PROMPT_JSON_TEXT`, passing the step's `returns`
+ * keys so the brace form only counts a brace that spells one of them. Without
+ * `returnKeys` (the example and doc sweeps) any quoted identifier key counts.
+ * `{{input.*}}` placeholders are removed first, so an input named `json` never
+ * matches.
+ *
+ * @example
+ * ```ts
+ * jsonTextDirective('Return ONLY a JSON object with keys "subject" and "body".'); // 'Return ONLY a JSON'
+ * jsonTextDirective('Return ONLY {"category","priority"}.', ['category']);       // '{"category",'
+ * jsonTextDirective('Return a result conforming to the output schema.');          // undefined
+ * jsonTextDirective('Do not return JSON.');                                       // undefined
+ * jsonTextDirective('Answer the question using the JSON data below.');            // undefined
+ * ```
+ */
+export function jsonTextDirective(text, returnKeys) {
+    if (typeof text !== 'string' || text === '')
+        return undefined;
+    // A placeholder becomes a hard break (`·` is neither a word nor a gap), and a
+    // quoted or back-ticked `JSON` is read as the bare word.
+    const t = text
+        .replace(/\{\{\s*input\.[^}]*\}\}/g, ' · ')
+        .replace(/[`"'“”](json)[`"'“”]/gi, ' $1 ');
+    const words = (s) => (s.match(new RegExp(JSON_TEXT_WORD, 'g')) ?? []).map((w) => w.toLowerCase());
+    const keys = returnKeys?.length ? returnKeys.map(escapeRegExp).join('|') : '[A-Za-z_]\\w*';
+    const brace = new RegExp(`\\{[ \\t]*["'](?:${keys})["'][ \\t]*[,:}]`, 'g');
+    for (const rule of [JSON_TEXT_DIRECT, JSON_TEXT_VIA, brace]) {
+        rule.lastIndex = 0;
+        for (const m of t.matchAll(rule)) {
+            if (m.slice(1).some((g) => words(g ?? '').some(isJsonTextNegation)))
+                continue;
+            // Any negation earlier in the same clause: "Do not wrap the answer in JSON",
+            // "No need to return JSON". A comma ends a clause, so "Do not guess, return
+            // ONLY a JSON object" still counts.
+            const clause = t.slice(0, m.index).split(/[.;:!?\n,]/).pop() ?? '';
+            if (words(clause).some(isJsonTextNegation))
+                continue;
+            return m[0].trim();
+        }
+    }
+    return undefined;
+}
 /**
  * Check an `inlineAgent(...)` call.
  *
@@ -3162,7 +3262,7 @@ function checkAgentRead(name, field, rest, spec, step, diags) {
  * rules can be certain rather than best-effort — the definition's own `required`
  * list is checkable, and so is whether the prompts and the declared variables agree.
  *
- * Two rules exist because the PLATFORM does something with what you wrote:
+ * Three rules exist because the PLATFORM does something with what you wrote:
  *
  *  - `INLINE_AGENT_SCAFFOLD_MODEL` — the model the platform's own scaffold ships is
  *    stale, and v1's smoke check for this node type fails a flow that keeps it. A
@@ -3174,6 +3274,11 @@ function checkAgentRead(name, field, rest, spec, step, diags) {
  *    input the prompts never mention is pruned deployed while arriving locally: a
  *    disagreement between rungs and the platform, which is the one class that has to
  *    be said out loud rather than left to a run.
+ *  - `INLINE_AGENT_PROMPT_JSON_TEXT` — the platform returns `returns` as a typed
+ *    object: it becomes the `agent.json` `outputSchema`, and the agent runtime ends
+ *    a run with a structured call that fills exactly those fields. A prompt that
+ *    ALSO asks for JSON text makes the model pack its whole answer, serialized, into
+ *    one string field. See {@link jsonTextDirective}.
  */
 function checkInlineAgent(step, inputs, diags) {
     const at = (code, message, suggestion) => {
@@ -3241,6 +3346,40 @@ function checkInlineAgent(step, inputs, diags) {
             + `definition's default, \`{ content: 'string' }\`, which is the scaffold shape. Declare the fields the `
             + `agent must return, or drop the key and read \`content\`.`);
     }
+    // A prompt that asks for JSON TEXT while `returns` declares the fields. The
+    // platform already returns those fields as a typed object — `returns` is the
+    // agent.json `outputSchema`, and the runtime ends a run with a structured call
+    // that fills exactly those keys — so the extra directive does not shape the
+    // answer, it gets serialized INTO it: on 2026-09-23 a writer declaring
+    // `{ subject, body }` came back with `body` = '{"subject":…,"body":…}' in 3 of 3
+    // debug runs, and the flow mailed the JSON. `uip maestro flow validate` accepts
+    // the prompt (it never reads prompt meaning), so this is where it is said. An
+    // ERROR for the same reason `INLINE_AGENT_UNDECLARED_PLACEHOLDER` is one: the
+    // platform accepts the shape and the run still delivers the wrong value, and a
+    // warning is printed past while compile writes the .flow anyway. Only when
+    // `returns` is declared: with the `{ content }` default, JSON text in `content`
+    // may be exactly what the author reads back.
+    const returnKeys = Object.keys(inputs?.returns ?? {});
+    if (returnKeys.length) {
+        for (const field of ['systemPrompt', 'userPrompt']) {
+            const phrase = jsonTextDirective(String(inputs?.[field] ?? ''), returnKeys);
+            if (phrase === undefined)
+                continue;
+            const rewrite = `Return a result conforming to the output schema. `
+                + returnKeys.map((k) => `${k}: <what it holds>.`).join(' ');
+            at('INLINE_AGENT_PROMPT_JSON_TEXT', `Inline agent step "${step}"'s \`${field}\` tells the model to answer in JSON text ("${phrase}"), `
+                + `but \`returns\` already declares the answer: ${returnKeys.map((k) => `\`${k}\``).join(', ')}. `
+                + `The platform returns those fields as a typed object — \`returns\` becomes the agent.json `
+                + `\`outputSchema\`, and the agent runtime ends each run with a structured call that fills exactly `
+                + `those keys — so \`out('${step}', '${returnKeys[0]}')\` reads a value, not text to parse. Asking `
+                + `for JSON as well makes the model pack its whole answer, serialized, into one string field (for `
+                + `example a \`body\` that reads '{"subject":…,"body":…}'). Replace only that JSON instruction (keep the rest `
+                + `of the prompt) with one line per field, in the platform's own wording: "${rewrite}" Declare a field \`'object'\` or `
+                + `\`'array'\` if it should carry structure. \`uip maestro flow validate\` accepts this prompt, so `
+                + `nothing later catches it. If this is a false positive (the prompt only mentions JSON as data), `
+                + `compile with --no-check.`);
+        }
+    }
     // The prompts-vs-variables agreement, in both directions. Both prompts are
     // searched, because flow-v1's pre-pass scans both.
     const prompts = `${String(inputs?.systemPrompt ?? '')}\n${String(inputs?.userPrompt ?? '')}`;

package/dist/core/actions.d.ts

@@ -1376,16 +1376,18 @@ export interface InlineAgentInputs {
      */
     model: string;
     /**
-     * The agent's standing instructions — who it is and what it must return.
-     * Required by the definition (`minLength: 1`).
+     * The agent's standing instructions — who it is, and what each `returns` field
+     * should hold. Required by the definition (`minLength: 1`).
      *
      * **Write it as plain text, and reference a value as `{{input.<name>}}`** — the
      * agent's own template syntax, and the same names `inputs` declares:
      *
      * ```ts
-     * systemPrompt: 'You classify support email. Return ONLY {"category","priority"}.',
+     * systemPrompt: 'You classify support email. Return a result conforming to the output '
+     *   + 'schema. category: billing | technical | account. priority: low | normal | high.',
      * userPrompt: 'Classify this email:\n{{input.body}}',
      * inputs: { body: input('body') },
+     * returns: { category: 'string', priority: 'string' },
      * ```
      *
      * Why a placeholder rather than an interpolated expression: an inline agent is two
@@ -1404,11 +1406,24 @@ export interface InlineAgentInputs {
      * literal text reaches the model. See the inline-agent node reference (`website/reference/inline-agent.md`)
      * §"The three prompt DIALECTS".
      *
-     * If the agent has to answer in a shape the flow then reads, say so here. The
-     * `returns` keys are what a downstream `out(...)` reads, and the engine's own live
-     * path appends a "return ONLY a JSON object with exactly these keys" directive for
-     * the same reason — a system prompt that contradicts it is a fight the model may
-     * lose.
+     * **The answer's shape is `returns`, not the prompt.** `returns` becomes the node's
+     * `agentOutputVariables` and the `agent.json` `outputSchema` — what Studio Web's
+     * Outputs editor writes — and the platform's agent runtime ends each run with a
+     * built-in structured call (`end_execution`) that fills exactly those fields. So
+     * `out('<step>', '<field>')` reads a typed value, not text to parse. Describe what
+     * each field holds, in the product's own wording, as the example above does:
+     * `Return a result conforming to the output schema. <field>: <how to fill it>.`
+     *
+     * Never ask for JSON TEXT as well ("Return ONLY a JSON object with keys …"). The
+     * model then packs its whole answer, serialized, into ONE string field: a writer
+     * declaring `{ subject, body }` came back on 2026-09-23 with
+     * `body: '{"subject":"…","body":"Dear …"}'` in 3 of 3 debug runs, and the flow sent
+     * that text on. A field that should carry structure is declared `'object'` or
+     * `'array'` instead.
+     *
+     * @enforcedBy INLINE_AGENT_PROMPT_JSON_TEXT A prompt that asks for JSON text while
+     * `returns` declares fields is refused; the platform accepts it and the run returns
+     * the packed value.
      */
     systemPrompt: string;
     /**
@@ -1516,7 +1531,8 @@ export interface InlineAgentInputs {
      * ```ts
      * inlineAgent({
      *   model: 'gpt-5.4',
-     *   systemPrompt: 'You decide billing disputes from the SOPs. Return ONLY {"determination","rationale"}.',
+     *   systemPrompt: 'You decide billing disputes from the SOPs. Return a result conforming to the output '
+     *     + 'schema. determination: valid | invalid | needs_review. rationale: the SOP rule that decided it.',
      *   userPrompt: 'Dispute: {{input.description}}',
      *   inputs: { description: input('disputeDescription') },
      *   returns: { determination: 'string', rationale: 'string' },
@@ -3069,8 +3085,8 @@ export declare function agent(inputs: AgentInputs): ActionSpec;
  *   model: 'gpt-5.4',
  *   systemPrompt:
  *     'You are a support triage assistant. Classify the email into exactly one ' +
- *     'category (billing | technical | account) and one priority (low | normal | ' +
- *     'high). Return ONLY a JSON object with keys "category" and "priority".',
+ *     'category and one priority. Return a result conforming to the output schema. ' +
+ *     'category: billing | technical | account. priority: low | normal | high.',
  *   userPrompt: 'Classify this email:\n{{input.body}}',
  *   inputs: { body: input('body') },
  *   returns: { category: 'string', priority: 'string' },

package/dist/core/actions.js

@@ -850,8 +850,8 @@ export function agent(inputs) {
  *   model: 'gpt-5.4',
  *   systemPrompt:
  *     'You are a support triage assistant. Classify the email into exactly one ' +
- *     'category (billing | technical | account) and one priority (low | normal | ' +
- *     'high). Return ONLY a JSON object with keys "category" and "priority".',
+ *     'category and one priority. Return a result conforming to the output schema. ' +
+ *     'category: billing | technical | account. priority: low | normal | high.',
  *   userPrompt: 'Classify this email:\n{{input.body}}',
  *   inputs: { body: input('body') },
  *   returns: { category: 'string', priority: 'string' },

package/dist/serialize.js

@@ -4396,7 +4396,7 @@ export function serialize(built, opts = {}) {
                 ...(s.guardrails === undefined ? {} : { guardrails: s.guardrails }),
                 // The two DESCRIPTOR ARRAYS. `agentInputVariables` entries carry the
                 // binding expression; `agentOutputVariables` entries are name + type only,
-                // and a runner coerces the model's completion to exactly these keys.
+                // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.6",
+  "version": "6.9.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "503ff8140144536c938e0b0ad0356b6ccb41b9f9"
+  "gitref": "b7baf691c4126ec18eb3388d0d0a70b09301f24d"
 }