@uipath/maestro-builder-sdk 6.8.5 → 6.9.0

package/dist/check-cli.js

@@ -6,15 +6,15 @@
  * Prints diagnostics; exits non-zero if any errors.
  */
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { check } from './check.js';
-import { Library } from './library.js';
+import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { connectorInputErrors } from './serialize.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { ensureTypeScriptRuntime } from './node-runtime.js';
-import { resolveLibraryDir } from './registry/cache.js';
+/** Flags that take a value, so the value is never read as the source argument. */
+const VALUE_FLAGS = new Set(['--library', '--bindings', '--connectors-local']);
 /**
  * Library lookups for the checks whose facts live in the connector corpus:
  * event parameters and measured list envelopes.
@@ -23,33 +23,30 @@ import { resolveLibraryDir } from './registry/cache.js';
  * function of the built flow — with no library it simply cannot know whether an
  * empty `where` is correct, so it fails open (a warning, not an error). Given a
  * library, `compile` and `check` make the same call with the facts in hand.
- * `--library` mirrors compile-cli's flag and default.
+ * `--library` and `--connectors-local` mirror compile-cli's flags and defaults,
+ * through the same `openCliLibrary`.
  */
 function checkOpts(argv) {
-    const flag = argv.indexOf('--library');
-    const libDir = resolveLibraryDir(flag >= 0 ? argv[flag + 1] : undefined);
     // bindings.json beside the source, exactly as compile-cli finds it — so the
     // own-name refusal compile would raise is reported here first.
     const bindFlag = argv.indexOf('--bindings');
     const bindFile = bindFlag >= 0 ? argv[bindFlag + 1] : (existsSync('bindings.json') ? 'bindings.json' : undefined);
     const bindings = bindFile ? new Bindings(bindFile) : undefined;
-    if (!libDir || !existsSync(join(libDir, 'index.json')))
-        return bindings ? { bindings } : {};
     // The overlay matters here as much as it does for compile: `resolutions.json`
     // lives in it, and without it every already-resolved lookup would be reported
     // as still owed — telling the author to re-run a `prepare` they already ran.
-    const overlayDir = existsSync(join('connectors-local', 'index.json'))
-        ? 'connectors-local'
-        : undefined;
-    const library = new Library(libDir, { overlayDir });
+    const library = openCliLibrary(argv);
+    if (!library)
+        return bindings ? { bindings } : {};
     return {
+        eventResolveError: eventResolveErrorFor(library),
         eventParams: (connector, event, object) => {
             try {
                 return library.eventParameterFields(connector, event, object);
             }
             catch {
-                // An unresolvable operation is EVENT_UNKNOWN's business (compile reports
-                // it against the real library); here it just means "unknown".
+                // An unresolvable operation is EVENT_UNKNOWN's business, reported from
+                // `eventResolveError` above; here it just means "unknown".
                 return undefined;
             }
         },
@@ -96,9 +93,9 @@ function checkOpts(argv) {
     };
 }
 export async function run(argv) {
-    const arg = argv.find((a) => !a.startsWith('--')) ?? argv[0];
+    const arg = argv.find((a, i) => !a.startsWith('--') && !VALUE_FLAGS.has(argv[i - 1])) ?? argv[0];
     if (!arg || arg === '-h' || arg === '--help') {
-        console.error('usage: check [--library <dir>] [--bindings <file>] <flow.ts | BaseName>');
+        console.error('usage: check [--library <dir>] [--connectors-local <dir>] [--bindings <file>] <flow.ts | BaseName>');
         return 2;
     }
     const file = resolveFlowFile(arg);

package/dist/check.d.ts

@@ -75,6 +75,26 @@ export interface CheckOpts {
      * and cannot be slowed down by one.
      */
     eventParams?: (connector: string, event: string, object?: string) => EventParamFields | undefined;
+    /**
+     * What `compile` would refuse a connector event subscription with, or
+     * `undefined` when the library resolves it. `kind` is the node form compile
+     * asks for: `trigger` for `onEvent` (the flow's trigger and every entry point),
+     * `event` for `waitForEvent`. Supplied by the CLIs from the same
+     * `library.resolveEvent(kind, connector, event, version, object)` call
+     * `serialize` makes (`eventResolveErrorFor` in `cli-library.ts`), so the two
+     * cannot disagree; omitted (no library) → not checked.
+     *
+     * Before this hook `check` could only warn EVENT_UNPREPARED here, because
+     * `eventParams` answers `undefined` for "cannot resolve" and for "no facts"
+     * alike: it printed `0 error(s)` on a source `compile` then refused
+     * (2026-09-23, `skill-flow-datafabric-trigger-lifecycle`, v2 commands 31 and 46).
+     */
+    eventResolveError?: (kind: 'trigger' | 'event', subscription: {
+        connector: string;
+        event: string;
+        version?: string;
+        object?: string;
+    }) => string | undefined;
     /**
      * Resolve a connector event's FILTERABLE field names — the vocabulary a
      * `filters` leaf may name — sourced the same way as `eventParams`. A GENERIC
@@ -144,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

@@ -529,7 +529,7 @@ function checkFlow(built, ancestors, opts = {}) {
                         ...(suggestion ? { suggestion } : {}),
                     });
                     checkEventSubscription(s.spec.subscription, `waitForEvent "${stepName}"`, push('error'), push('warning'), eventParamsFor(s.spec.subscription, opts));
-                    checkEventResolution(s.spec.subscription, `waitForEvent "${stepName}"`, opts, 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));
                 }
                 if (s.spec.kind === 'subflow') {
                     // Only a real child goes in the map: a missing one is reported by
@@ -1955,12 +1955,18 @@ function eventParamsFor(subscription, opts) {
 }
 /**
  * The event-side resolution rules — the trigger twin of `checkConnectorLookups`,
- * plus two rules with no activity counterpart:
+ * plus three rules with no activity counterpart:
  *
- * - `EVENT_UNPREPARED` — a library resolver is present and knows NOTHING about
- *   this event, not even identity: the fallback case for a connector the
- *   shipped library was not generated against. Prints the one command that
- *   makes the event checkable.
+ * - `EVENT_UNKNOWN` — an ERROR: a library is loaded and it cannot resolve the
+ *   subscription, so `compile` will refuse it. The message is the resolver's
+ *   own (`eventResolveError`), the same text compile throws. Checked first; when
+ *   it fires, EVENT_UNPREPARED and the filter rules below are skipped for this
+ *   subscription, since there is no entry for them to read.
+ * - `EVENT_UNPREPARED` — the event RESOLVES but the library knows nothing
+ *   about its parameters (or no `eventResolveError` resolver was supplied):
+ *   the fallback case for a connector the shipped library was not generated
+ *   against. A warning, because compile still succeeds. Prints the one
+ *   command that makes the event checkable.
  * - `EVENT_FILTER_UNKNOWN_FIELD` — a filter leaf naming a field outside the
  *   prepared vocabulary is an ERROR, not a warning, because the platform's own
  *   configure DROPS an unmatched leaf and reports Success: the deployed
@@ -1972,7 +1978,7 @@ function eventParamsFor(subscription, opts) {
  * (compile repeats it as the hard failure), with the recorded answer looked up
  * under the event-form node type — the form `prepare` stores.
  */
-function checkEventResolution(subscription, where, opts, error, warn, eventParams) {
+function checkEventResolution(subscription, where, kind, opts, error, warn, eventParams) {
     const sub = subscription;
     if (!sub || typeof sub.connector !== 'string' || typeof sub.event !== 'string'
         || sub.connector === '' || sub.event === '')
@@ -1983,6 +1989,18 @@ function checkEventResolution(subscription, where, opts, error, warn, eventParam
     // by interpolating them into template literals, which accept anything.
     const connectorKey = sub.connector;
     const eventName = sub.event;
+    // Exactly what `serialize` passes to `resolveEvent` — `sub.version` and
+    // `sub.object` as the author wrote them — so the verdict is compile's.
+    const unresolved = opts.eventResolveError?.(kind, {
+        connector: connectorKey,
+        event: eventName,
+        ...(typeof sub.version === 'string' ? { version: sub.version } : {}),
+        ...(typeof sub.object === 'string' ? { object: sub.object } : {}),
+    });
+    if (unresolved !== undefined) {
+        error('EVENT_UNKNOWN', `${where}: ${unresolved}`);
+        return;
+    }
     const object = typeof sub.object === 'string' && sub.object !== '' ? sub.object : undefined;
     if (eventParams?.objectUnprepared && object) {
         // The generic template answers for every object, so resolution SUCCEEDS
@@ -2259,7 +2277,7 @@ function checkTrigger(spec, diags, opts = {}) {
     if (spec?.kind === 'event') {
         const sub = spec.subscription;
         checkEventSubscription(sub, 'trigger', at, push('warning'), eventParamsFor(sub, opts));
-        checkEventResolution(sub, 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
+        checkEventResolution(sub, 'trigger', 'trigger', opts, at, push('warning'), eventParamsFor(sub, opts));
         return;
     }
     // manual() is the explicit spelling of the default — nothing to validate.
@@ -3136,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.
  *
@@ -3144,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
@@ -3156,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) => {
@@ -3223,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/cli/commands/flow.js

@@ -25,6 +25,7 @@ export function registerFlowCommands(program) {
         .option('--source', 'check authored TypeScript')
         .option('--compiled', 'check the emitted artifact')
         .option('--library <dir>', 'connector library directory')
+        .option('--connectors-local <dir>', 'connection-resolved connector overlay')
         .option('--json', 'print compiled-check diagnostics as JSON')
         .option('--uip', 'resolve missing schemas with the UiPath CLI')
         .option('--max-errors <count>', 'stop after this many compiled-check errors')
@@ -50,6 +51,7 @@ export function registerFlowCommands(program) {
         if (mode === 'source') {
             const argv = [input];
             addValue(argv, '--library', options.library);
+            addValue(argv, '--connectors-local', options.connectorsLocal);
             await invoke('flow check', () => loadTool(import.meta.url, '../../check-cli.js'), argv);
             return;
         }

package/dist/cli-library.d.ts

@@ -0,0 +1,21 @@
+import type { CheckOpts } from './check.js';
+import { Library } from './library.js';
+/**
+ * The library for this invocation, or `undefined` when there is none.
+ *
+ * `--library <dir>`, else `$FLOW_SDK_LIBRARY_JSON`, else the cache `registry
+ * pull` filled (`resolveLibraryDir`). The overlay is `--connectors-local <dir>`,
+ * else `./connectors-local` when it has an `index.json` — the directory
+ * `registry prepare` writes by default.
+ */
+export declare function openCliLibrary(argv: readonly string[]): Library | undefined;
+/**
+ * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
+ * for a subscription, or `undefined` when it resolves.
+ *
+ * This is the call `serialize` makes for `onEvent` (kind `trigger`, for the
+ * flow's trigger and each entry point) and for `waitForEvent` (kind `event`),
+ * with the subscription's own `version` and `object`, so check reports an error
+ * exactly when compile would throw, with the same text.
+ */
+export declare function eventResolveErrorFor(library: Library): NonNullable<CheckOpts['eventResolveError']>;

package/dist/cli-library.js

@@ -0,0 +1,56 @@
+/**
+ * cli-library — the connector library a flow CLI opens, and the event verdict
+ * `check` shares with `compile`.
+ *
+ * `check-cli` and `compile-cli` used to open the library each in their own way:
+ * compile honoured `--connectors-local <dir>`, check ignored the flag and only
+ * auto-detected `./connectors-local`. As long as check only WARNED from the
+ * library that was harmless. Now check reports EVENT_UNKNOWN as an ERROR when
+ * the library cannot resolve an event, so a different library would make check
+ * refuse a source compile accepts. Both CLIs open it here instead.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Library } from './library.js';
+import { resolveLibraryDir } from './registry/cache.js';
+/** The value after `name` in `argv`, or `undefined`. */
+function flagValue(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/**
+ * The library for this invocation, or `undefined` when there is none.
+ *
+ * `--library <dir>`, else `$FLOW_SDK_LIBRARY_JSON`, else the cache `registry
+ * pull` filled (`resolveLibraryDir`). The overlay is `--connectors-local <dir>`,
+ * else `./connectors-local` when it has an `index.json` — the directory
+ * `registry prepare` writes by default.
+ */
+export function openCliLibrary(argv) {
+    const libDir = resolveLibraryDir(flagValue(argv, '--library'));
+    if (!libDir || !existsSync(join(libDir, 'index.json')))
+        return undefined;
+    const overlayDir = flagValue(argv, '--connectors-local')
+        ?? (existsSync(join('connectors-local', 'index.json')) ? 'connectors-local' : undefined);
+    return new Library(libDir, { overlayDir });
+}
+/**
+ * `check`'s EVENT_UNKNOWN verdict: the message `library.resolveEvent` throws
+ * for a subscription, or `undefined` when it resolves.
+ *
+ * This is the call `serialize` makes for `onEvent` (kind `trigger`, for the
+ * flow's trigger and each entry point) and for `waitForEvent` (kind `event`),
+ * with the subscription's own `version` and `object`, so check reports an error
+ * exactly when compile would throw, with the same text.
+ */
+export function eventResolveErrorFor(library) {
+    return (kind, sub) => {
+        try {
+            library.resolveEvent(kind, sub.connector, sub.event, sub.version, sub.object);
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    };
+}

package/dist/compile-cli.js

@@ -22,8 +22,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars, connectorInputErrors } from './serialize.js';
 import { check } from './check.js';
-import { Library } from './library.js';
-import { resolveLibraryDir } from './registry/cache.js';
+import { eventResolveErrorFor, openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, mergeBindingsV2, readBindingsV2 } from './bindings-v2.js';
@@ -50,14 +49,11 @@ export async function run(argv) {
     // --library, else $FLOW_SDK_LIBRARY_JSON, else the shared cache `registry pull`
     // filled. Resolving through one helper is what stops `pull` and `compile`
     // disagreeing about where the library is — they did, and a pulled library was
-    // invisible to this command.
-    const libDir = resolveLibraryDir(opt(argv, '--library'));
-    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
-    // A `prepare-connector`/`prepare-trigger` overlay: auto-detected next to the
-    // flow (like bindings.json), it shadows the baked library with full,
-    // connection-resolved field schemas. See core/library.ts (LibraryOpts.overlayDir).
-    const overlayDir = opt(argv, '--connectors-local')
-        ?? (existsSync(join('connectors-local', 'index.json')) ? 'connectors-local' : undefined);
+    // invisible to this command. The `prepare-connector`/`prepare-trigger` overlay
+    // is `--connectors-local`, else `./connectors-local` (like bindings.json); it
+    // shadows the baked library with full, connection-resolved field schemas. See
+    // core/library.ts (LibraryOpts.overlayDir). `check-cli` opens it the same way.
+    //
     // Only load the library when it's actually present; flows without connectors
     // (e.g. HTTP-only) then compile fine even if the connector cache isn't built.
     // A connector action with no library resolves to a clear error in serialize().
@@ -66,11 +62,16 @@ export async function run(argv) {
     // event operation declares any event parameters) can only be answered from the
     // library, and answering it from an assumption instead is what made
     // EVENT_NO_SCOPE an error for HTTP Webhook, whose only correct `where` is empty.
-    const library = libDir && existsSync(join(libDir, 'index.json')) ? new Library(libDir, { overlayDir }) : undefined;
+    const library = openCliLibrary(argv);
+    const bindFile = opt(argv, '--bindings') ?? (existsSync('bindings.json') ? 'bindings.json' : undefined);
     const bindings = new Bindings(bindFile);
     if (!noCheck) {
         const diags = check(built, library
             ? {
+                // The refusal serialize() would throw for an event it cannot resolve,
+                // printed as `✗ [EVENT_UNKNOWN]` before stopping instead of hiding
+                // behind "1 error(s); not emitting".
+                eventResolveError: eventResolveErrorFor(library),
                 eventParams: (connector, event) => {
                     try {
                         return library.eventParameterFields(connector, event);

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/library.d.ts

@@ -402,6 +402,26 @@ export declare class Library {
      * that. It resorted to grepping the library's JSON out of `node_modules`.
      */
     private describeMiss;
+    /** Every direct operation id under `prefix` (no further dot), across layers, sorted and de-duplicated. */
+    private opsUnder;
+    /** Whether any layer indexes `nodeType` (at `version`, when one is asked for). */
+    private carries;
+    /** The connector key is in no entry at all. */
+    private noConnector;
+    /**
+     * The event half of {@link describeMiss}: which of the connector's EVENTS the
+     * library carries, read from BOTH namespaces.
+     *
+     * Both, because the library stores almost every event in one form only: the
+     * baseline snapshot of 2026-09-23 (`2a4405dd…`) has 994 `.event.` entries and 4
+     * `.trigger.` ones, and a start trigger resolves from its `.event.` sibling
+     * ({@link resolveEvent}). Reading the asked namespace alone answered `No
+     * connector "uipath-uipath-dataservice"` for a typo'd `onEvent` event on a
+     * connector whose events were all right there, and the same words for a
+     * connector present with eight actions and no events at all (2026-09-23 eval,
+     * `skill-flow-datafabric-trigger-lifecycle`, v2 commands 45/46).
+     */
+    private describeEventMiss;
     /**
      * Resolve the op WITHIN one layer, selecting the entry by `objectName` for a
      * GENERIC operation. Returns undefined when the layer does not carry the op;