@uipath/maestro-builder-sdk 6.11.3 → 6.11.5

package/dist/check.js

@@ -8,6 +8,7 @@
 import { Expr, SCHEDULE_PRESETS, DELAY_PRESETS, VARIANT_OPERATION, parseIxpProjectType, flatNameOf, flatNameSegmentsOf, FLAT_SEP } from './flow-sdk.js';
 import { FlowNode } from './core/node-classes.js';
 import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/lookups.js';
+import { QUEUE_ITEM_RECORD_SCHEMA } from './core/queue-record.js';
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
 import { bindingSelfNameMessage, bindingUndeclaredMessage, undeclaredBinding } from './core/binding-messages.js';
@@ -145,20 +146,12 @@ function checkFlow(built, ancestors, opts = {}) {
     // form's ANSWER fields (plus `Action`), so a read of it is checked against the
     // form the author wrote rather than waved through (see HITL_READ_* below).
     const hitlForms = new Map();
-    const apiWorkflows = new Map();
-    const publishedFunctions = new Map();
-    // Agentic-process step name → its call. Same reason as api-workflow's map: the
-    // step publishes the job's output arguments and the only offline statement of
-    // what those are is the step's own `returns`.
+    // Agentic-process step name → its call, for the form-field rules below. Its
+    // output READS go through OUTPUT_READ_RULES like every `returns` family.
     const agenticProcesses = new Map();
-    // Published-agent step name → its call. Same reason again: the step publishes the
-    // agent job's output arguments, and the only offline statement of what those are
-    // is the step's own `returns`.
-    const agents = new Map();
-    // Inline-agent step name → its call. NOT the same reason: an inline agent's
-    // contract is AUTHORED rather than looked up on a tenant, so a read outside the
-    // declared `returns` is a mistake the compiler can be certain about.
-    const inlineAgents = new Map();
+    // Step name → the read rule for its output, bound to its inputs. Filled from
+    // OUTPUT_READ_RULES for every kind whose inputs take a `returns`.
+    const outputReaders = new Map();
     const connectorSteps = new Map();
     // Subflow step name → the child flow it runs. A subflow's output is the
     // OBJECT of the child's declared outputs, so a read of it is checked against
@@ -434,11 +427,9 @@ function checkFlow(built, ancestors, opts = {}) {
                     checkRpaWorkflow(s.name, s.spec.inputs, diags);
                 if (s.spec.kind === 'apiWorkflow') {
                     checkApiWorkflow(s.name, s.spec.inputs, diags);
-                    apiWorkflows.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'publishedFunction') {
                     checkPublishedFunction(s.name, s.spec.inputs, diags);
-                    publishedFunctions.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'sendMessage' || s.spec.kind === 'waitForMessage'
                     || s.spec.kind === 'conversationContext') {
@@ -456,14 +447,20 @@ function checkFlow(built, ancestors, opts = {}) {
                 }
                 if (s.spec.kind === 'agent') {
                     checkAgent(s.name, s.spec.inputs, diags);
-                    agents.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'inlineAgent') {
                     checkInlineAgent(s.name, s.spec.inputs, diags);
-                    inlineAgents.set(s.name, s.spec.inputs);
                 }
                 if (s.spec.kind === 'queueItem')
                     checkQueueItem(s.name, s.spec.inputs, diags);
+                {
+                    const rule = OUTPUT_READ_RULES[s.spec.kind];
+                    if (typeof rule === 'function') {
+                        const stepName = s.name;
+                        const inputs = s.spec.inputs;
+                        outputReaders.set(stepName, (field, rest, at, d) => rule(stepName, field, rest, inputs, at, d));
+                    }
+                }
                 if (s.spec.kind === 'documentClassify' || s.spec.kind === 'dynamicExtract') {
                     const fr = s.spec.inputs.fileRef;
                     const empty = fr === undefined || fr === null || (typeof fr === 'string' && fr.trim() === '');
@@ -1142,7 +1139,8 @@ function checkFlow(built, ancestors, opts = {}) {
                     code: 'MOCK_HAS_NO_OUTPUT',
                     message: `Placeholder "${name}" publishes nothing, but "$vars.${name}${field ? '.' + field : ''}" reads it in "${step}". `
                         + 'A mock() is a marker for a node that does not exist yet — its output is null at run time, always. '
-                        + 'Replace it with the real step before reading it.',
+                        + 'Keep the placeholder while the real node does not exist, and have the reader use a value you supply instead (a flow input, as example/ClaimScaffold.flow.ts does). '
+                        + 'Replace the placeholder only with the real node, once `registry search` finds it; a script returning fixed values is not the real node.',
                     step,
                 });
                 continue;
@@ -1167,49 +1165,13 @@ function checkFlow(built, ancestors, opts = {}) {
                 checkHitlRead(name, field, rest, form, step, diags);
                 continue;
             }
-            // An API workflow publishes the job's output arguments, and the only offline
-            // statement of what those are is the step's own `returns`. A read of anything
-            // else is `undefined` on every rung and on the platform — and with no
-            // `returns` at all the node declares no output schema, so nothing downstream
-            // can tell a real field from a typo.
-            const apiwf = apiWorkflows.get(name);
-            if (apiwf) {
-                checkApiWorkflowRead(name, field, rest, apiwf, step, diags);
-                continue;
-            }
-            // A published function publishes its result the same way, and the same
-            // three read mistakes are decidable from the same place — so the reader is
-            // shared, with the family named in the codes.
-            const fn = publishedFunctions.get(name);
-            if (fn) {
-                checkPublishedFunctionRead(name, field, rest, fn, step, diags);
-                continue;
-            }
-            // An agentic process publishes its job's output arguments the same way, so
-            // the same three read mistakes are decidable from the same place.
-            const agentic = agenticProcesses.get(name);
-            if (agentic) {
-                checkAgenticProcessRead(name, field, rest, agentic, step, diags);
-                continue;
-            }
-            // A published agent publishes its job's output arguments the same way its
-            // three siblings do, so the same three read mistakes are decidable — with one
-            // extra that only this family has: a read whose CASE differs from the declared
-            // field. That used to be a live-only defect (the poll verb PascalCased the
-            // answer, flow-builder-sdk #122), so the wrong case was right live and wrong
-            // offline for a while. Now it is simply wrong, and worth naming as itself
-            // rather than as an unknown field.
-            const published = agents.get(name);
-            if (published) {
-                checkAgentRead(name, field, rest, published, step, diags);
-                continue;
-            }
-            // An inline agent's readable fields are exactly its declared `returns` — the
-            // node's `agentOutputVariables`, which is also what the engine's live path
-            // coerces the model's completion to. Nothing on a tenant to consult.
-            const inline = inlineAgents.get(name);
-            if (inline) {
-                checkInlineAgentRead(name, field, rest, inline, step, diags);
+            // Every family that declares its output's fields — the author's `returns`, or
+            // a shape the SDK fixes — has its read rule in OUTPUT_READ_RULES, keyed by
+            // kind. A read outside the declared set is undefined on every rung and on
+            // the platform, so it is refused here rather than at `flow debug`.
+            const readOutput = outputReaders.get(name);
+            if (readOutput) {
+                readOutput(field, rest, step, diags);
                 continue;
             }
             // A loop step exposes a fixed set of fields, and only those resolve at run
@@ -2814,6 +2776,175 @@ function checkPublishedFunctionRead(name, field, rest, spec, step, diags) {
         suggestion: `returns: { ${wanted}: 'string' }`,
     });
 }
+/**
+ * The fields every HTTP response carries at the top of `output`, whatever the
+ * API answered. `core.action.http`'s definition declares all three; the author's
+ * `returns` describes what is INSIDE `body`, never beside it.
+ */
+const HTTP_ENVELOPE_FIELDS = ['body', 'statusCode', 'headers'];
+/**
+ * A read of an `http()` step's result.
+ *
+ * The response is an envelope — `{ body, statusCode, headers }` — and `returns`
+ * declares the parsed JSON body's top-level fields, so a declared field is read
+ * at `output.body.<field>` (`out('<step>', 'body.<field>')`). That nesting is the
+ * one thing this family does not share with the process families, and it is
+ * exactly where flow-builder-sdk#850's run went wrong: a branch kept reading
+ * `output.currentDayForecast…` (the Azure Maps connector's path) after the step
+ * became an Open-Meteo `http()`, passed `check` and `validate`, and faulted at
+ * `flow debug` as `[400302]`.
+ */
+function checkHttpRead(name, field, rest, spec, step, diags) {
+    if (field === undefined)
+        return; // `out('fetch')` — the whole response.
+    if (field === 'error')
+        return; // the failure envelope (managed http's error port).
+    if (field !== 'output') {
+        diags.push({
+            level: 'error', code: 'HTTP_READ_NOT_OUTPUT', step,
+            message: `HTTP step "${name}" publishes its response under "output", but "$vars.${name}.${field}" `
+                + `(read in "${step}") asks for "${field}", which is undefined at run time.`,
+            suggestion: `out('${name}', 'body.<field>')`,
+        });
+        return;
+    }
+    const [top, inner] = (rest ?? '').replace(/^\./, '').split('.');
+    if (!top)
+        return; // `$vars.<name>.output` — the whole envelope.
+    const declared = Object.keys(spec?.returns ?? {});
+    if (!HTTP_ENVELOPE_FIELDS.includes(top)) {
+        // The commonest form: a declared body field read one level too high.
+        const hoisted = declared.includes(top) ? top : undefined;
+        const nearest = hoisted ?? nearestName(top, declared);
+        diags.push({
+            level: 'error', code: 'HTTP_READ_UNKNOWN_FIELD', step,
+            message: `"$vars.${name}.output.${top}" (read in "${step}") is not a field of HTTP step "${name}"'s `
+                + `response. An HTTP response publishes ${HTTP_ENVELOPE_FIELDS.map((f) => `"${f}"`).join(', ')}; `
+                + `the fields \`returns\` declares live under "body"`
+                + (hoisted ? `, so "${top}" is read as "$vars.${name}.output.body.${top}".` : '.')
+                + ` A read outside that shape resolves to undefined and faults a gateway at run time.`,
+            ...(nearest !== undefined ? { suggestion: `out('${name}', 'body.${nearest}')` } : {}),
+        });
+        return;
+    }
+    if (top !== 'body' || !inner)
+        return; // `statusCode`, `headers`, or the whole body.
+    if (declared.length === 0) {
+        diags.push({
+            level: 'error', code: 'HTTP_READ_WITHOUT_RETURNS', step,
+            message: `"$vars.${name}.output.body.${inner}" (read in "${step}") reads a field of HTTP step "${name}"'s `
+                + `response body, but the step declares no \`returns\` — so the node carries no body schema and nothing `
+                + `can tell a real field from a typo. Only the API being called knows its body; declare the fields you read.`,
+            suggestion: `returns: { ${inner}: 'string' }`,
+        });
+        return;
+    }
+    if (declared.includes(inner))
+        return;
+    const nearest = nearestName(inner, declared);
+    diags.push({
+        level: 'error', code: 'HTTP_READ_UNKNOWN_FIELD', step,
+        message: `HTTP step "${name}" declares no body field "${inner}" (read as "$vars.${name}.output.body.${inner}" `
+            + `in "${step}"). Its \`returns\` names: ${declared.join(', ')}. A read outside that set resolves to undefined.`,
+        ...(nearest !== undefined ? { suggestion: `out('${name}', 'body.${nearest}')` } : {}),
+    });
+}
+/**
+ * The read rule the process-shaped families share: the result is published
+ * under `output`, keyed by a known field list — the author's `returns`, or a
+ * shape the SDK itself fixes. `declared: undefined` means "the author declared
+ * nothing", which is its own mistake (`<PREFIX>_READ_WITHOUT_RETURNS`).
+ */
+function checkDeclaredOutputRead(o) {
+    const { prefix, what, name, field, rest, step, diags } = o;
+    if (field === undefined || field === 'error')
+        return;
+    if (field !== 'output') {
+        diags.push({
+            level: 'error', code: `${prefix}_READ_NOT_OUTPUT`, step,
+            message: `${what} "${name}" publishes its result under "output", but "$vars.${name}.${field}" `
+                + `(read in "${step}") asks for "${field}", which is undefined at run time.`,
+            suggestion: `out('${name}', '<field>')`,
+        });
+        return;
+    }
+    const wanted = (rest ?? '').replace(/^\./, '').split('.')[0];
+    if (!wanted)
+        return;
+    if (o.declared === undefined) {
+        diags.push({
+            level: 'error', code: `${prefix}_READ_WITHOUT_RETURNS`, step,
+            message: `"$vars.${name}.output.${wanted}" (read in "${step}") reads a field of ${what} "${name}"'s result, `
+                + `but the step declares no \`returns\` — so the node carries no output schema and nothing can tell a `
+                + `real field from a typo. ${o.withoutReturns}`,
+            suggestion: `returns: { ${wanted}: 'string' }`,
+        });
+        return;
+    }
+    if (o.declared.includes(wanted))
+        return;
+    const nearest = nearestName(wanted, o.declared);
+    diags.push({
+        level: 'error', code: `${prefix}_READ_UNKNOWN_FIELD`, step,
+        message: `${what} "${name}" declares no output "${wanted}" (read as "$vars.${name}.output.${wanted}" in `
+            + `"${step}"). It publishes: ${o.declared.join(', ')}. A read outside that set resolves to undefined.`,
+        ...(nearest !== undefined ? { suggestion: `out('${name}', '${nearest}')` } : {}),
+    });
+}
+function checkRpaWorkflowRead(name, field, rest, spec, step, diags) {
+    const declared = Object.keys(spec?.returns ?? {});
+    checkDeclaredOutputRead({
+        prefix: 'RPA', what: 'RPA process', name, field, rest, step, diags,
+        declared: declared.length ? declared : undefined,
+        withoutReturns: `The process's output arguments live on the tenant; declare the ones you read. `
+            + `\`uip maestro flow registry get uipath.core.rpa-workflow.${spec?.key}\` shows what the platform `
+            + `synthesizes for it.`,
+    });
+}
+/**
+ * A queue step publishes one of two shapes: a plain enqueue publishes the queue
+ * ITEM's Orchestrator record (fixed, declared by the serializer from
+ * `QUEUE_ITEM_RECORD_SCHEMA`), a `wait: true` publishes the processed result,
+ * whose fields only the author's `returns` states.
+ */
+function checkQueueItemRead(name, field, rest, spec, step, diags) {
+    const waitReturns = Object.keys(spec?.returns ?? {});
+    checkDeclaredOutputRead({
+        prefix: 'QUEUE', what: spec?.wait ? 'Queue wait' : 'Queue item', name, field, rest, step, diags,
+        declared: !spec?.wait
+            ? Object.keys(QUEUE_ITEM_RECORD_SCHEMA.properties)
+            : waitReturns.length ? waitReturns : undefined,
+        withoutReturns: `What the consumer writes into the processed item's result is that automation's business; `
+            + `declare the fields you read.`,
+    });
+}
+/**
+ * THE GATE (flow-builder-sdk#850). Each `returns`-bearing kind maps to the rule
+ * that checks a read of its output, or to a stated reason it has none.
+ *
+ * Before this table each family's rule was wired by hand — a map filled in the
+ * walk plus a branch in the `$vars` dispatch — and nothing tied "this family
+ * takes `returns`" to "this family has a read rule". `http`, `rpaWorkflow` and
+ * `queueItem` shipped without one, so a read of an undeclared field passed
+ * `check` and `validate` and only faulted live. The type below is exhaustive
+ * over the derived kinds: give a new family a `returns` and `tsc` refuses to
+ * build until it lands here.
+ */
+const OUTPUT_READ_RULES = {
+    http: checkHttpRead,
+    rpaWorkflow: checkRpaWorkflowRead,
+    apiWorkflow: checkApiWorkflowRead,
+    publishedFunction: checkPublishedFunctionRead,
+    agenticProcess: checkAgenticProcessRead,
+    agent: checkAgentRead,
+    inlineAgent: checkInlineAgentRead,
+    queueItem: checkQueueItemRead,
+    script: {
+        exempt: 'Not yet: only the field-map form of a script\'s `returns` gives a list to check against (the '
+            + 'type form and the inferred form do not), and script is the most-used step, so its rule lands with '
+            + 'its own false-positive sweep — flow-builder-sdk#855.',
+    },
+};
 function checkApiWorkflowRead(name, field, rest, spec, step, diags) {
     if (field === undefined)
         return; // `out('call')` — the whole output object.

package/dist/core/actions.d.ts

@@ -82,6 +82,16 @@ interface HttpInputsBase {
      * fields, and nothing downstream can tell a real field from a typo. Same rule,
      * and the same word, as
      * `rpaWorkflow`'s `returns`.
+     *
+     * **Where a declared field is read:** under `body`, never beside it. The
+     * response is an envelope — `{ body, statusCode, headers }` — and these are the
+     * body's fields, so `returns: { items: 'array' }` is read as
+     * `out('fetch', 'body.items')`, which is `$vars.fetch.output.body.items`.
+     * `$vars.fetch.output.items` is undefined at run time.
+     *
+     * @enforcedBy HTTP_READ_UNKNOWN_FIELD A read must be `output.body.<declared field>`,
+     * `output.statusCode` or `output.headers`.
+     * @enforcedBy HTTP_READ_WITHOUT_RETURNS Reading a body field requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
     /**
@@ -991,6 +1001,9 @@ export interface RpaWorkflowInputs {
      * the fields here is the same thing the platform's own definition does when it
      * can reach the process, and it is what lets a misspelled read be caught at
      * `uip maestro flow check` instead of at run time.
+     *
+     * @enforcedBy RPA_READ_UNKNOWN_FIELD A read of the output must name a field declared here.
+     * @enforcedBy RPA_READ_WITHOUT_RETURNS Reading a field off the result requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
 }
@@ -2035,6 +2048,11 @@ export interface QueueItemInputs {
      * `wait: false` needs none: what it publishes is the queue ITEM's own
      * Orchestrator record (`Key`, `Status`, `Reference`, `SpecificContent`, …),
      * which is the same for every queue, so the serializer declares it for you.
+     *
+     * @enforcedBy QUEUE_READ_UNKNOWN_FIELD A read must name a field of the record
+     * (`wait: false`) or of this `returns` (`wait: true`).
+     * @enforcedBy QUEUE_READ_WITHOUT_RETURNS Reading a field off a `wait: true` result
+     * requires declaring it here.
      */
     returns?: Record<string, ReturnFieldType>;
 }

package/dist/core/queue-record.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The queue item's own Orchestrator record — the fields `core.action.queue.create`
+ * publishes, declared so a downstream read is checkable. Shared by the serializer
+ * (which declares it on the node) and `check` (which refuses a read outside it).
+ *
+ * Unlike an rpa process's output arguments, this shape is NOT per-tenant: it is
+ * Orchestrator's queue-item record, the same for every queue, so the author has
+ * nothing to declare and `returns` is not needed for a fire-and-forget enqueue.
+ * The dispatcher returns `env.Data` from `uip or queue-items add` verbatim, and
+ * these are the fields a real add answered with (pinned 2026-07-28 against
+ * `Shared/SupplierInvoices` on codereval; `gen-tests`' fixture for the node is the
+ * same list). Declaring the EVIDENCED fields and no more is PR 10's payload-schema
+ * pattern — an invented field would be #73's `firedAt` again.
+ */
+export declare const QUEUE_ITEM_RECORD_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly Id: {
+            readonly type: "number";
+        };
+        readonly Key: {
+            readonly type: "string";
+        };
+        readonly UniqueKey: {
+            readonly type: "string";
+        };
+        readonly Reference: {
+            readonly type: "string";
+        };
+        readonly Status: {
+            readonly type: "string";
+        };
+        readonly Priority: {
+            readonly type: "string";
+        };
+        readonly QueueDefinitionName: {
+            readonly type: "string";
+        };
+        readonly QueueDefinitionKey: {
+            readonly type: "string";
+        };
+        readonly CreationTime: {
+            readonly type: "string";
+        };
+        readonly StartProcessing: {
+            readonly type: "string";
+        };
+        readonly EndProcessing: {
+            readonly type: "string";
+        };
+        readonly Progress: {
+            readonly type: "string";
+        };
+        readonly ReviewStatus: {
+            readonly type: "string";
+        };
+        readonly DueDate: {
+            readonly type: "string";
+        };
+        readonly RiskSlaDate: {
+            readonly type: "string";
+        };
+        readonly DeferDate: {
+            readonly type: "string";
+        };
+        readonly Encrypted: {
+            readonly type: "boolean";
+        };
+        readonly SpecificContent: {
+            readonly type: "object";
+        };
+        readonly Output: {
+            readonly type: "object";
+        };
+        readonly OutputData: {
+            readonly type: "string";
+        };
+        readonly Analytics: {
+            readonly type: "object";
+        };
+        readonly AnalyticsData: {
+            readonly type: "string";
+        };
+        readonly ProcessingExceptionType: {
+            readonly type: "string";
+        };
+        readonly ProcessingExceptionReason: {
+            readonly type: "string";
+        };
+        readonly SecondsInPreviousAttempts: {
+            readonly type: "number";
+        };
+        readonly RetryNumber: {
+            readonly type: "number";
+        };
+        readonly CreatorJobKey: {
+            readonly type: "string";
+        };
+        readonly ExecutorJobKey: {
+            readonly type: "string";
+        };
+        readonly RobotKey: {
+            readonly type: "string";
+        };
+    };
+};

package/dist/core/queue-record.js

@@ -0,0 +1,48 @@
+/**
+ * The queue item's own Orchestrator record — the fields `core.action.queue.create`
+ * publishes, declared so a downstream read is checkable. Shared by the serializer
+ * (which declares it on the node) and `check` (which refuses a read outside it).
+ *
+ * Unlike an rpa process's output arguments, this shape is NOT per-tenant: it is
+ * Orchestrator's queue-item record, the same for every queue, so the author has
+ * nothing to declare and `returns` is not needed for a fire-and-forget enqueue.
+ * The dispatcher returns `env.Data` from `uip or queue-items add` verbatim, and
+ * these are the fields a real add answered with (pinned 2026-07-28 against
+ * `Shared/SupplierInvoices` on codereval; `gen-tests`' fixture for the node is the
+ * same list). Declaring the EVIDENCED fields and no more is PR 10's payload-schema
+ * pattern — an invented field would be #73's `firedAt` again.
+ */
+export const QUEUE_ITEM_RECORD_SCHEMA = {
+    type: 'object',
+    properties: {
+        Id: { type: 'number' },
+        Key: { type: 'string' },
+        UniqueKey: { type: 'string' },
+        Reference: { type: 'string' },
+        Status: { type: 'string' },
+        Priority: { type: 'string' },
+        QueueDefinitionName: { type: 'string' },
+        QueueDefinitionKey: { type: 'string' },
+        CreationTime: { type: 'string' },
+        StartProcessing: { type: 'string' },
+        EndProcessing: { type: 'string' },
+        Progress: { type: 'string' },
+        ReviewStatus: { type: 'string' },
+        DueDate: { type: 'string' },
+        RiskSlaDate: { type: 'string' },
+        DeferDate: { type: 'string' },
+        Encrypted: { type: 'boolean' },
+        SpecificContent: { type: 'object' },
+        Output: { type: 'object' },
+        OutputData: { type: 'string' },
+        Analytics: { type: 'object' },
+        AnalyticsData: { type: 'string' },
+        ProcessingExceptionType: { type: 'string' },
+        ProcessingExceptionReason: { type: 'string' },
+        SecondsInPreviousAttempts: { type: 'number' },
+        RetryNumber: { type: 'number' },
+        CreatorJobKey: { type: 'string' },
+        ExecutorJobKey: { type: 'string' },
+        RobotKey: { type: 'string' },
+    },
+};

package/dist/flow-sdk.d.ts

@@ -974,7 +974,7 @@ declare class StepList {
      * **Paginate until the API says stop**
      * ```ts
      * .var('page', types.number, 1)
-     * .doWhile('paginate', js`$vars.fetch.output.hasNextPage === true`, (b) => b
+     * .doWhile('paginate', js`$vars.fetch.output.body.hasNextPage === true`, (b) => b
      *   .step('fetch', http({ url: tmpl`https://api.example.test/items?page=${v('page')}`, method: 'GET', managed: false, returns: { hasNextPage: 'boolean' } }), {
      *     updates: { page: js`$vars.page + 1` },
      *   }), { limit: 50 })

package/dist/flow-sdk.js

@@ -709,7 +709,7 @@ class StepList {
      * **Paginate until the API says stop**
      * ```ts
      * .var('page', types.number, 1)
-     * .doWhile('paginate', js`$vars.fetch.output.hasNextPage === true`, (b) => b
+     * .doWhile('paginate', js`$vars.fetch.output.body.hasNextPage === true`, (b) => b
      *   .step('fetch', http({ url: tmpl`https://api.example.test/items?page=${v('page')}`, method: 'GET', managed: false, returns: { hasNextPage: 'boolean' } }), {
      *     updates: { page: js`$vars.page + 1` },
      *   }), { limit: 50 })

package/dist/registry/cache.d.ts

@@ -21,6 +21,15 @@
 export declare const LIBRARY_JSON_DIR = "library-json";
 export declare const LIBRARY_MARKDOWN_DIR = "library-md";
 export declare const CURRENT_LINK = "current";
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export declare const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/registry/cache.js

@@ -24,6 +24,15 @@ import { join } from "node:path";
 export const LIBRARY_JSON_DIR = "library-json";
 export const LIBRARY_MARKDOWN_DIR = "library-md";
 export const CURRENT_LINK = "current";
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/registry/path-cli.js

@@ -1,6 +1,6 @@
 import { reportResult } from '../cli-result.js';
 import { join } from "node:path";
-import { CURRENT_LINK, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
+import { CURRENT_LINK, PULL_COMMAND, currentEntrySha, libraryCacheRoot, resolveCachedLibrary, resolveCachedMarkdown, } from "./cache.js";
 /**
  * Say where the connector library is.
  *
@@ -34,7 +34,7 @@ export async function run(argv) {
     const single = (field, value) => {
         reportResult({ [field]: value ?? null });
         if (!value) {
-            console.error("No connector library in the cache yet. Run `flow-sdk registry pull`.");
+            console.error(`No connector library in the cache yet. Run \`${PULL_COMMAND}\`.`);
             return 1;
         }
         console.log(value);

package/dist/registry/search-cli.js

@@ -1,6 +1,6 @@
 import { reportResult } from '../cli-result.js';
 import { readFile, stat } from "node:fs/promises";
-import { resolveLibraryDir } from "./cache.js";
+import { PULL_COMMAND, resolveLibraryDir } from "./cache.js";
 import { dirname, join } from "node:path";
 export const DEFAULT_SEARCH_LIMIT = 20;
 const USAGE = "Usage: flow-sdk registry search [query] [--library <dir>] [--library-md <dir>] [--connector <key>] [--limit <n>]";
@@ -52,7 +52,7 @@ export async function searchRegistryOperations(options) {
         content = await readFile(indexPath, "utf-8");
     }
     catch {
-        throw new Error(`Could not read ${indexPath}. Run \`flow-sdk registry pull\`, or point` +
+        throw new Error(`Could not read ${indexPath}. Run \`${PULL_COMMAND}\`, or point` +
             " --library at an extracted connector library.");
     }
     let parsed;
@@ -120,6 +120,10 @@ export async function run(argv) {
     // verbs defaulted it was the inconsistency an author hit first.
     const libraryPath = resolveLibraryDir(value(argv, "--library"));
     if (!libraryPath) {
+        // Say why. A bare usage line here read as "no match" to an agent deciding
+        // between a connector and http(): it took the failed search for a miss.
+        console.error(`No connector library is cached. Run \`${PULL_COMMAND}\`, or pass` +
+            " --library <dir>.");
         console.error(USAGE);
         return 2;
     }