@uipath/maestro-builder-sdk 6.8.6 → 6.9.1

package/dist/check.d.ts

@@ -1,6 +1,7 @@
 import { type LookupResolutions, type LookupSpec } from './core/lookups.js';
 import type { SchemaReadiness } from './core/library.js';
 import type { BuiltFlow } from './flow-sdk.js';
+import { type BindingsView } from './core/binding-messages.js';
 export interface Diagnostic {
     level: 'error' | 'warning';
     code: string;
@@ -140,12 +141,13 @@ export interface CheckOpts {
         object?: string;
     }, inputs: Record<string, unknown>) => string | undefined;
     /**
-     * The project's `bindings.json`, when there is one — enough of it to detect an
-     * entry that answers with its own name, which `compile` refuses (BINDING_SELF_NAME).
+     * The project's `bindings.json`, when there is one — enough of it to detect the
+     * two labels `compile` refuses: an entry that answers with its own name
+     * (BINDING_SELF_NAME), and a label a populated file does not declare
+     * (BINDING_UNDECLARED). `declared` and `entry` are optional so a caller holding
+     * only `resolve` still gets the first rule; the `Bindings` class has all three.
      */
-    bindings?: {
-        resolve(name?: string): string | undefined;
-    };
+    bindings?: BindingsView;
 }
 export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
 /**
@@ -164,3 +166,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

@@ -10,7 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/lookups.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
-import { bindingSelfNameMessage } from './core/binding-messages.js';
+import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
 import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
 import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
@@ -357,6 +357,14 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkTransform(s.name, s.spec.inputs, diags, typeOf, triggerId);
                 if (s.spec.kind === 'http') {
                     checkHttp(s.name, s.spec.inputs, diags);
+                    // Only a complete pair: an empty half is HTTP_MANAGED_BINDING_INCOMPLETE, which
+                    // serialize refuses before it resolves either name.
+                    const pair = s.spec.inputs;
+                    const filled = (v) => typeof v === 'string' && v.trim() !== '';
+                    if (pair?.managed && filled(pair.connection) && filled(pair.folder)) {
+                        const httpStep = s.name;
+                        checkBindingLabels(`managed http "${httpStep}"`, pair, opts, (code, message) => diags.push({ level: 'error', code, step: httpStep, message }));
+                    }
                     const seen = new Set();
                     for (const b of s.spec.inputs.branches ?? []) {
                         addExpr(b.condition.js, s.name);
@@ -530,6 +538,7 @@ function checkFlow(built, ancestors, opts = {}) {
                     });
                     checkEventSubscription(s.spec.subscription, `waitForEvent "${stepName}"`, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
                     checkEventResolution(s.spec.subscription, `waitForEvent "${stepName}"`, 'event', opts, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
+                    checkBindingLabels(`waitForEvent "${stepName}"`, s.spec.subscription, opts, push('error'), eventTarget(s.spec.subscription));
                 }
                 if (s.spec.kind === 'subflow') {
                     // Only a real child goes in the map: a missing one is reported by
@@ -1470,14 +1479,41 @@ function checkConnectorContract(step, spec, opts, diags) {
     if (inputErr) {
         diags.push({ level: 'error', code: 'CONNECTOR_INPUT', step, message: `Connector step "${step}": ${inputErr}` });
     }
-    if (opts.bindings) {
-        for (const attribute of ['connection', 'folder']) {
-            const name = spec[attribute];
-            if (name !== undefined && opts.bindings.resolve(name) === name) {
-                diags.push({
-                    level: 'error', code: 'BINDING_SELF_NAME', step,
-                    message: bindingSelfNameMessage(`Connector step "${step}"`, name, attribute),
-                });
+    checkBindingLabels(`Connector step "${step}"`, spec, opts, (code, message) => diags.push({ level: 'error', code, step, message }), { key: spec.key, action: spec.action });
+}
+/** What `registry prepare` takes for an event subscription: its connector key and curated event name. */
+function eventTarget(sub) {
+    const { connector, event } = (sub ?? {});
+    return typeof connector === 'string' && connector !== ''
+        ? { key: connector, ...(typeof event === 'string' && event !== '' ? { action: event } : {}) }
+        : undefined;
+}
+/**
+ * The binding-label rules `serialize`'s `resolveBinding` enforces, for one
+ * `{ connection, folder }` pair — reported at every site that resolves one
+ * (connector step, event trigger and `.entryPoint` onEvent, waitForEvent, managed
+ * HTTP), with the sentence compile throws. Without this at the event and HTTP
+ * sites `check` printed `✓ no issues` for a source `compile` then refused.
+ *
+ * Silent without a bindings.json, and for a label that resolves to anything
+ * other than its own name (stub values are compile's CONNECTION_STUB warning).
+ */
+function checkBindingLabels(where, labels, opts, report, target) {
+    const bindings = opts.bindings;
+    if (!bindings || !labels)
+        return;
+    for (const attribute of ['connection', 'folder']) {
+        const name = labels[attribute];
+        if (typeof name !== 'string')
+            continue;
+        const resolved = bindings.resolve(name);
+        if (resolved === name) {
+            report('BINDING_SELF_NAME', bindingSelfNameMessage(where, name, attribute, target));
+        }
+        else if (resolved === undefined) {
+            const declared = undeclaredBinding(bindings, name);
+            if (declared) {
+                report('BINDING_UNDECLARED', bindingUndeclaredMessage(where, name, attribute, declared, target));
             }
         }
     }
@@ -2278,6 +2314,7 @@ function checkTrigger(spec, diags, opts = {}) {
         const sub = spec.subscription;
         checkEventSubscription(sub, 'trigger', at, push('warning'), eventParamsFor(sub, opts));
         checkEventResolution(sub, 'trigger', 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
+        checkBindingLabels('event trigger', sub, opts, at, eventTarget(sub));
         return;
     }
     // manual() is the explicit spelling of the default — nothing to validate.
@@ -3154,6 +3191,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 +3299,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 +3311,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 +3383,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/compile-cli.js

@@ -27,6 +27,7 @@ import { Bindings } from './bindings.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
+import { BindingRefusal } from './core/binding-messages.js';
 function opt(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 ? argv[i + 1] : undefined;
@@ -106,11 +107,27 @@ export async function run(argv) {
     }
     // The serializer's own observations — a connection or folder value that can
     // never be a tenant resource key — printed in the same `⚠ [CODE]` shape as
-    // check()'s, and never fatal: the .flow is still written, exit stays 0.
+    // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
+    // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
+    // label a populated bindings.json does not declare) is an error, not a
+    // warning: the check pass above reports it first, and this is the same refusal
+    // in the same `✗ [CODE]` shape when that pass was skipped (`--no-check`, or an
+    // emit-only project). Nothing is written.
     const warnings = [];
-    const { flow: flowJson, sidecars } = serializeWithSidecars(built, {
-        library, bindings, warn: (w) => warnings.push(w),
-    });
+    let emitted;
+    try {
+        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w) });
+    }
+    catch (error) {
+        if (!(error instanceof BindingRefusal))
+            throw error;
+        for (const w of warnings)
+            console.error(`  ⚠ [${w.code}] ${w.message}`);
+        console.error(`  ✗ [${error.code}] ${error.message}`);
+        console.error('compile: 1 error(s); not emitting.');
+        return 1;
+    }
+    const { flow: flowJson, sidecars } = emitted;
     for (const w of warnings)
         console.error(`  ⚠ [${w.code}] ${w.message}`);
     const out = opt(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;

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/core/binding-messages.d.ts

@@ -1 +1,60 @@
-export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder'): string;
+/** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
+export declare const GUID_RE: RegExp;
+/** The diagnostic codes a label refusal carries, in `check` and on the error `serialize` throws. */
+export type BindingRefusalCode = 'BINDING_SELF_NAME' | 'BINDING_UNDECLARED';
+/**
+ * What `serialize` throws for a label it refuses. It is an ordinary `Error` whose
+ * message is the sentence `check` prints; the `code` lets `compile --no-check`
+ * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
+ */
+export declare class BindingRefusal extends Error {
+    readonly code: BindingRefusalCode;
+    constructor(code: BindingRefusalCode, message: string);
+}
+/** The part of a bindings.json the label rules read — `core/bindings.ts` `Bindings` has all three. */
+export interface BindingsView {
+    resolve(name?: string): string | undefined;
+    declared?(): string[];
+    entry?(name?: string): unknown;
+}
+export declare function bindingSelfNameMessage(where: string, name: string, attribute: 'connection' | 'folder', target?: PrepareTarget): string;
+/**
+ * The names a populated bindings.json declares when it does NOT declare `name`,
+ * else `undefined`.
+ *
+ * `undefined` — nothing to refuse — when no bindings.json is loaded, when it
+ * declares no entries (offline authoring: the symbolic name is the only honest
+ * placeholder there), when `name` is itself a GUID (an author may write the
+ * resource key directly), or when any entry answers to `name`. "Answers" is the
+ * union of `entry()`, `resolve()` and `declared()`, so an entry that is declared
+ * but carries no `resourceKey` is NOT refused here — it stays the
+ * `CONNECTION_STUB` warning, which is the route a simulated or validate-only task
+ * with nothing real to bind is meant to take.
+ */
+export declare function undeclaredBinding(bindings: BindingsView | undefined, name: string): string[] | undefined;
+/**
+ * The connector and operation a label belongs to, when the call site knows them:
+ * a connector step's `key` + `action`, an event's `connector` + `event`. With it
+ * the remedy is a command the author can paste; without it (managed HTTP) the
+ * command keeps its `<connector-key> <action>` placeholders.
+ */
+export interface PrepareTarget {
+    key: string;
+    action?: string;
+}
+/**
+ * Why compile refuses `name`, and how to bind it.
+ *
+ * It names NO declared label as the one to use. bindings.json rows carry a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * they were bound for, so compile cannot tell which declared label — if any — is
+ * this connector's. Suggesting one sent a Data Service step to `connection:
+ * 'slack'` (the only `ConnectionId` row), and following that compiled the Slack
+ * connection id into the Data Service node with no warning at all: a real GUID of
+ * the wrong connector, which nothing downstream detects. The partial-prepare shape
+ * (ipe-drive-to-slack 09-23: `slack` bound, `drive` not yet) is exactly where
+ * that advice was on offer. So the message lists what is declared, says that a
+ * row is only reusable if it was bound for THIS connector, and gives the
+ * `prepare` command for this step's own connector and operation.
+ */
+export declare function bindingUndeclaredMessage(where: string, name: string, attribute: 'connection' | 'folder', declared: readonly string[], target?: PrepareTarget): string;

package/dist/core/binding-messages.js

@@ -1,16 +1,91 @@
 /**
- * The refusal for a bindings.json entry that answers with its own name — shared by
- * `serialize` (which throws it) and `check` (BINDING_SELF_NAME), so the author reads
- * the same sentence from the inner loop as from compile. Before this, `check`
- * printed `0 error(s)` for a source `compile` then refused (teams-decision,
- * 2026-09-01, turn 22 → 23).
+ * The refusals for a connection/folder label `compile` cannot turn into a tenant
+ * resource key — shared by `serialize` (which throws them) and `check`
+ * (BINDING_SELF_NAME, BINDING_UNDECLARED), so the author reads the same sentence
+ * from the inner loop as from compile. Before this, `check` printed `0 error(s)`
+ * for a source `compile` then refused (teams-decision, 2026-09-01, turn 22 → 23).
  */
 import { prepareCommand } from './cli-spelling.js';
-export function bindingSelfNameMessage(where, name, attribute) {
+/** A tenant resource key — an Integration Service connection id or an Orchestrator folder key — is a GUID. */
+export const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * What `serialize` throws for a label it refuses. It is an ordinary `Error` whose
+ * message is the sentence `check` prints; the `code` lets `compile --no-check`
+ * print it in the same `✗ [CODE]` shape as the check pass instead of a bare line.
+ */
+export class BindingRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BindingRefusal';
+        this.code = code;
+    }
+}
+export function bindingSelfNameMessage(where, name, attribute, target) {
     return `${where}: binding "${name}" resolves to its own name, so the ${attribute} would compile to the `
         + `literal string "${name}" and the run would fault with "'Connection' has an invalid GUID value: `
-        + `'${name}'". Set its "resourceKey" to the real id: \`${prepareCommand('<connector-key>', '<action>')}\` `
+        + `'${name}'". Set its "resourceKey" to the real id: \`${prepareFor(target)}\` `
         + `discovers the connection and writes both the connection and the folder entry into bindings.json; by hand, `
         + `read Id and FolderKey from \`uip is connections list --all-folders --output json\` (the default listing `
         + `shows only your own folder, so a connection shared from another folder is invisible without --all-folders).`;
 }
+/**
+ * The names a populated bindings.json declares when it does NOT declare `name`,
+ * else `undefined`.
+ *
+ * `undefined` — nothing to refuse — when no bindings.json is loaded, when it
+ * declares no entries (offline authoring: the symbolic name is the only honest
+ * placeholder there), when `name` is itself a GUID (an author may write the
+ * resource key directly), or when any entry answers to `name`. "Answers" is the
+ * union of `entry()`, `resolve()` and `declared()`, so an entry that is declared
+ * but carries no `resourceKey` is NOT refused here — it stays the
+ * `CONNECTION_STUB` warning, which is the route a simulated or validate-only task
+ * with nothing real to bind is meant to take.
+ */
+export function undeclaredBinding(bindings, name) {
+    if (!bindings || typeof bindings.declared !== 'function')
+        return undefined;
+    const declared = bindings.declared();
+    if (declared.length === 0)
+        return undefined;
+    if (GUID_RE.test(name))
+        return undefined;
+    if (declared.includes(name))
+        return undefined;
+    if (typeof bindings.entry === 'function' && bindings.entry(name) !== undefined)
+        return undefined;
+    if (bindings.resolve(name) !== undefined)
+        return undefined;
+    return declared;
+}
+function prepareFor(target) {
+    return prepareCommand(target?.key ?? '<connector-key>', target?.action ?? '<action>');
+}
+/**
+ * Why compile refuses `name`, and how to bind it.
+ *
+ * It names NO declared label as the one to use. bindings.json rows carry a label,
+ * a resource key and a kind (`ConnectionId` / `FolderKey`), never the connector
+ * they were bound for, so compile cannot tell which declared label — if any — is
+ * this connector's. Suggesting one sent a Data Service step to `connection:
+ * 'slack'` (the only `ConnectionId` row), and following that compiled the Slack
+ * connection id into the Data Service node with no warning at all: a real GUID of
+ * the wrong connector, which nothing downstream detects. The partial-prepare shape
+ * (ipe-drive-to-slack 09-23: `slack` bound, `drive` not yet) is exactly where
+ * that advice was on offer. So the message lists what is declared, says that a
+ * row is only reusable if it was bound for THIS connector, and gives the
+ * `prepare` command for this step's own connector and operation.
+ */
+export function bindingUndeclaredMessage(where, name, attribute, declared, target) {
+    const key = attribute === 'connection' ? 'connection id' : 'folder key';
+    const flag = attribute === 'connection' ? '--bind-connection' : '--bind-folder';
+    return `${where}: ${attribute} "${name}" is not declared in bindings.json (it declares: ${declared.join(', ')}), `
+        + `so the .flow would carry "${name}" as its ${key} and the run would fault with `
+        + `"'Connection' has an invalid GUID value: '${name}'". Bind this one: `
+        + `\`${prepareFor(target)} ${flag} ${name}\` (several candidates: add \`--connection-id <id>\` from the list it prints). `
+        + `Switch to a declared label only if that row was bound for this same connector: bindings.json does not record `
+        + `which connector a row belongs to, and another connector's ${key} compiles without any warning and faults only at run time. `
+        + `A connector with nothing real to bind yet (a simulated or validate-only task, or one not prepared yet) `
+        + `declares the label with a placeholder resourceKey instead, which compiles with a CONNECTION_STUB warning — `
+        + `never an invented GUID.`;
+}