@uipath/maestro-builder-sdk 6.10.1 → 6.10.3

package/dist/registry/library-build/enrich.js

@@ -116,11 +116,23 @@ export async function enrichEntry(ctx, entry) {
     }
     if (!truthy(opName))
         return entry; // nothing to do
+    const failuresBefore = ctx.failedFieldDescribes.length;
     let data = await isDescribeOperation(ctx, connectorKey, objectName, opName);
     if (!truthy(data)) {
         const alt = await discoverOperationName(ctx, entry);
-        if (truthy(alt) && alt !== opName)
+        if (truthy(alt) && alt !== opName) {
+            // The registry's verb did not name an operation the object has, so its
+            // `-f` rejection is about a request that is now superseded: the CLI maps
+            // `List` to GET, and Data Service `QueryEntityRecordsCurated` exposes
+            // only POST ("No api-type ObjectAction matched for fields [entityName]
+            // on operation 'List'"). Kept, it made `prepare` refuse
+            // PARENT_FIELDS_REJECTED even when the retry below materialised the
+            // schema (flow-builder-sdk#818: 169 refusals across 15 runs on
+            // query-entity-records and get-entity-record-by-id). Only the describe
+            // whose answer is used may speak for the parent set.
+            ctx.failedFieldDescribes.length = failuresBefore;
             data = await isDescribeOperation(ctx, connectorKey, objectName, alt);
+        }
     }
     if (!truthy(data))
         return entry; // connector might be a stub or recently removed

package/dist/registry/prepare/messages.d.ts

@@ -187,16 +187,27 @@ export declare function candidateResolvesAllLine(label: string, lookups: number)
 export declare function candidateExhaustedLine(label: string, field: string, scanned: number): string;
 /** The terminal report's line for a candidate whose lookup failed for another reason: the error, verbatim. */
 export declare function candidateErrorLine(label: string, error: unknown): string;
+/**
+ * The command that shows what a lookup's collection holds on one connection.
+ *
+ * Every refusal that ends in "check the value" carries it: the value the author
+ * wrote may be one the task never named (an invented Slack channel), and
+ * without this line the only way to learn the real values is to leave the
+ * documented loop. The skills eval customer-escalation dead-ended exactly
+ * there on 2026-09-25 (UiPath/flow-builder-sdk#817).
+ */
+export declare function collectionListingHint(connectorKey: string, collection: string, connectionId: string): string;
 /**
  * An explicit `--connection-id` / `--connection` is the author's decision and
  * is not overridden. The alternatives are still named, because the whole cost
  * of this bug was not knowing they existed. `first` is the exhausted lookup's
- * own message; `others` the pasteable listing of the other candidates.
+ * own message; `others` the pasteable listing of the other candidates; `hint`
+ * the {@link collectionListingHint} for the pinned connection.
  */
-export declare function pinnedConnectionExhaustedMessage(first: string, connectorKey: string, othersCount: number, othersListing: string): string;
+export declare function pinnedConnectionExhaustedMessage(first: string, connectorKey: string, othersCount: number, othersListing: string, hint: string): string;
 /** The listing of other connections itself failed; the original lookup failure is what the author asked about. */
 export declare function candidateListingFailedMessage(first: string, error: unknown): string;
-export declare function onlyConnectionMessage(first: string, connectorKey: string): string;
+export declare function onlyConnectionMessage(first: string, connectorKey: string, hint: string): string;
 /** Two or more candidates resolve everything: reported, never chosen between. */
 export declare function severalConnectionsResolveMessage(count: number, connectorKey: string, listing: string): string;
 /**

package/dist/registry/prepare/messages.js

@@ -443,13 +443,27 @@ export function candidateExhaustedLine(label, field, scanned) {
 export function candidateErrorLine(label, error) {
     return `    ${label}  ${messageOf(error)}`;
 }
+/**
+ * The command that shows what a lookup's collection holds on one connection.
+ *
+ * Every refusal that ends in "check the value" carries it: the value the author
+ * wrote may be one the task never named (an invented Slack channel), and
+ * without this line the only way to learn the real values is to leave the
+ * documented loop. The skills eval customer-escalation dead-ended exactly
+ * there on 2026-09-25 (UiPath/flow-builder-sdk#817).
+ */
+export function collectionListingHint(connectorKey, collection, connectionId) {
+    return (`To see what ${pyRepr(collection)} holds on this connection:\n` +
+        `  uip is resources run list ${connectorKey} ${collection} --connection-id ${connectionId}`);
+}
 /**
  * An explicit `--connection-id` / `--connection` is the author's decision and
  * is not overridden. The alternatives are still named, because the whole cost
  * of this bug was not knowing they existed. `first` is the exhausted lookup's
- * own message; `others` the pasteable listing of the other candidates.
+ * own message; `others` the pasteable listing of the other candidates; `hint`
+ * the {@link collectionListingHint} for the pinned connection.
  */
-export function pinnedConnectionExhaustedMessage(first, connectorKey, othersCount, othersListing) {
+export function pinnedConnectionExhaustedMessage(first, connectorKey, othersCount, othersListing, hint) {
     let extra = "";
     if (othersCount > 0) {
         extra =
@@ -457,14 +471,16 @@ export function pinnedConnectionExhaustedMessage(first, connectorKey, othersCoun
                 `${othersListing}\n` +
                 "Re-run against one of those, or check the value. This run kept the connection you named.";
     }
-    return `${PREFIX}${first}${extra}`;
+    return `${PREFIX}${first}${extra}\n${hint}`;
 }
 /** The listing of other connections itself failed; the original lookup failure is what the author asked about. */
 export function candidateListingFailedMessage(first, error) {
     return `${PREFIX}${first}\n(could not list other connections: ${messageOf(error)})`;
 }
-export function onlyConnectionMessage(first, connectorKey) {
-    return (`${PREFIX}${first}\n` + `This is the only enabled ${connectorKey} connection on the tenant, so the value is what to check.`);
+export function onlyConnectionMessage(first, connectorKey, hint) {
+    return (`${PREFIX}${first}\n` +
+        `This is the only enabled ${connectorKey} connection on the tenant, so the value is what to check.\n` +
+        hint);
 }
 /** Two or more candidates resolve everything: reported, never chosen between. */
 export function severalConnectionsResolveMessage(count, connectorKey, listing) {
@@ -484,9 +500,7 @@ export function noConnectionResolvesMessage(connectorKey, first, lines, connecti
         `${first.field}: ${first.by}=${pyRepr(first.value)}\n` +
         `${lines.join("\n")}\n` +
         "Every candidate was read to the end, so the value is what to check now. " +
-        `To see what ${pyRepr(first.collection)} holds:\n` +
-        `  uip is resources run list ${connectorKey} ${first.collection} ` +
-        `--connection-id ${connectionId}`);
+        collectionListingHint(connectorKey, first.collection, connectionId));
 }
 // ---------------------------------------------------------------------------
 // The event path

package/dist/registry/prepare/overlay.d.ts

@@ -122,6 +122,8 @@ export type OverlayLookupSpec = {
     objectName?: string;
     dependsOn?: string[];
     filterPattern?: string;
+    /** The child collection of a tree lookup, `{Field}` placeholders filled from the parent record. */
+    childPath?: string;
 };
 /**
  * `_lookup_specs_from_overlay`: the prepared operation's lookup specs, read

package/dist/registry/prepare/overlay.js

@@ -426,6 +426,9 @@ function withFilterPatterns(specs, catalogFields) {
         const filterPattern = references.get(field)?.filterPattern;
         if (pyTruthy(filterPattern))
             copy.filterPattern = pyStrAny(filterPattern);
+        const childPath = references.get(field)?.childPath;
+        if (pyTruthy(childPath))
+            copy.childPath = pyStrAny(childPath);
         out.set(field, copy);
     }
     return out;

package/dist/registry/prepare/resolve.d.ts

@@ -93,8 +93,17 @@ export interface ResolveSpec {
     value?: string;
     filterPattern?: string;
     dependsOn?: readonly string[];
+    /** A tree lookup's child collection: `/EventFolderPicker?parentReference={ID}&includeFiles=true`. */
+    childPath?: string;
     [key: string]: unknown;
 }
+/**
+ * A tree walk lists one child collection per parent it opens. Google Drive's
+ * picker root holds three records (`My Drive`, `Shared with me`, `Shared
+ * drives`), so a bare-name search opens three; the cap only matters for a
+ * root that is itself a long list.
+ */
+export declare const MAX_TREE_LISTINGS = 25;
 /**
  * `channel:profile.email=dustin@example.com` -> `[field, by, value]`.
  *
@@ -221,4 +230,14 @@ export declare function scanCollection(client: UipClient, connectorKey: string,
  * the subclass the caller's retry keys on; every other failure is the parent.
  */
 export declare function resolveOne(client: UipClient, connectorKey: string, spec: ResolveSpec, field: string, by: string, value: string, connectionId: string, resolved?: Resolved): Promise<string>;
+/**
+ * The child collection of `parent`: `childPath` with each `{Field}` read off
+ * the parent record (`{ID}` → the folder's id), split into collection and
+ * query as the root path is. `undefined` when the parent lacks a field the
+ * path needs — it cannot be opened.
+ */
+export declare function childCollection(childPath: string, parent: unknown, resolved: Resolved): {
+    collection: string;
+    query: string | undefined;
+} | undefined;
 export {};

package/dist/registry/prepare/resolve.js

@@ -102,6 +102,13 @@ export class LookupExhausted extends ResolutionRefusal {
             this.near = facts.near;
     }
 }
+/**
+ * A tree walk lists one child collection per parent it opens. Google Drive's
+ * picker root holds three records (`My Drive`, `Shared with me`, `Shared
+ * drives`), so a bare-name search opens three; the cap only matters for a
+ * root that is itself a long list.
+ */
+export const MAX_TREE_LISTINGS = 25;
 /**
  * `channel:profile.email=dustin@example.com` -> `[field, by, value]`.
  *
@@ -467,6 +474,16 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         const filtered = pyStrAny(filterPattern).replaceAll("{filter}", value);
         query = query ? `${query}&${filtered}` : filtered;
     }
+    // A tree (`childPath`) is walked rather than scanned: its root is a handful
+    // of containers and every real record sits below one. Scanning only the root
+    // could never match a Google Drive file — the root is `My Drive`, `Shared
+    // with me`, `Shared drives` — and the agent fell back to paging
+    // `uip is resources run list … --query parentReference=…` by hand and
+    // pasting a literal id (flow-builder-sdk#818). A server-side filter still
+    // wins: it answers from the whole collection in one request.
+    if (pyTruthy(spec.childPath) && !pyTruthy(filterPattern)) {
+        return resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, collection, query, send);
+    }
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
     // What the collection DOES hold at `by`, for the refusal: kept only while it
     // could still be listed in full, plus the first case-insensitive equal.
@@ -531,3 +548,127 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         ...(near !== undefined ? { near } : {}),
     });
 }
+async function listAll(client, connectorKey, collection, connectionId, query) {
+    const records = [];
+    const scan = scanCollection(client, connectorKey, collection, connectionId, query);
+    let step = await scan.next();
+    while (!step.done) {
+        records.push(...step.value);
+        step = await scan.next();
+    }
+    return { records, outcome: step.value };
+}
+/**
+ * The child collection of `parent`: `childPath` with each `{Field}` read off
+ * the parent record (`{ID}` → the folder's id), split into collection and
+ * query as the root path is. `undefined` when the parent lacks a field the
+ * path needs — it cannot be opened.
+ */
+export function childCollection(childPath, parent, resolved) {
+    let missing = false;
+    const filled = substitute(childPath, resolved).replace(/\{([^{}]+)\}/g, (_whole, name) => {
+        const at = readPath(parent, name);
+        if (at === null || at === undefined || at === "") {
+            missing = true;
+            return "";
+        }
+        return pyStrAny(at);
+    });
+    if (missing)
+        return undefined;
+    const [beforeQuery, afterQuery] = splitOnce(filled, "?");
+    return { collection: pyStripChars(beforeQuery, "/"), query: afterQuery || undefined };
+}
+/** A record the walk may open: anything not marked as a leaf (`isFolder: false`). */
+function isContainer(record) {
+    const flag = readPath(record, "isFolder");
+    return flag !== false && pyStrAny(flag).toLowerCase() !== "false";
+}
+/**
+ * {@link resolveOne} for a tree lookup (`childPath` declared).
+ *
+ * Two forms of value, both matched EXACTLY on `by`:
+ *
+ * - a path, `My Drive/Reports/q3.csv`: each segment is matched in the listing
+ *   the previous one opened, starting at the root. One listing per segment, so
+ *   depth costs nothing extra and nothing is guessed about where the item is.
+ * - a bare name, `q3.csv`: the root is searched, then one level below every
+ *   root container. That reaches a Drive file at the top of `My Drive` — the
+ *   2026-09-25 run's `000_coder_evals.txt` — in 1 + 3 listings. Deeper items
+ *   need the path form, and the refusal says so.
+ *
+ * A bare-name miss is `capped`: the walk did not read the whole tree, so it is
+ * no evidence the value is absent and must not send `prepare` probing other
+ * connections. A path whose segment is missing from a listing read to the end
+ * IS evidence, and is reported as an exhaustive miss like a flat scan's.
+ */
+async function resolveInTree(client, connectorKey, spec, field, by, value, connectionId, resolved, rootCollection, rootQuery, send) {
+    const childPath = pyStrAny(spec.childPath);
+    const answer = (record) => {
+        const got = readPath(record, send);
+        if (got === null) {
+            throw new ResolutionRefusal(`${field}: matched a record on ${by}=${pyRepr(value)}, but it carries no ${pyRepr(send)} to send.`, "RESOLVE_NO_VALUE");
+        }
+        return pyStrAny(got);
+    };
+    let scanned = 0;
+    let pages = 0;
+    let listings = 0;
+    const list = async (collection, query) => {
+        const listing = await listAll(client, connectorKey, collection, connectionId, query);
+        scanned += listing.outcome.scanned;
+        pages += listing.outcome.pages + 1;
+        listings += 1;
+        return listing;
+    };
+    const root = await list(rootCollection, rootQuery);
+    const exact = root.records.find((record) => matchRecord(record, by, value));
+    if (exact !== undefined)
+        return answer(exact);
+    const segments = value.split("/").map((segment) => pyStrip(segment)).filter((segment) => segment !== "");
+    if (segments.length > 1) {
+        let level = root;
+        let where = rootCollection;
+        for (const [i, segment] of segments.entries()) {
+            const hit = level.records.find((record) => matchRecord(record, by, segment));
+            if (hit === undefined) {
+                const held = level.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
+                const shown = !level.outcome.capped && held.length > 0 && held.length <= CANDIDATE_LIMIT ? ` It holds: ${held.map(pyRepr).join(", ")}.` : "";
+                const facts = { field, collection: where, by, value, scanned, pages, capped: level.outcome.capped };
+                throw new LookupExhausted(`${field}: path ${pyRepr(value)} stops at segment ${i + 1}, ${pyRepr(segment)}: no record in ${pyRepr(where)} ` +
+                    `has ${by}=${pyRepr(segment)} (walked ${listings} listing(s), ${scanned} record(s)` +
+                    (level.outcome.capped ? `; STOPPED AT THE ${MAX_SCANNED}-record cap` : "; that listing exhausted") +
+                    `) on connection ${connectionId}.${shown}`, facts);
+            }
+            if (i === segments.length - 1)
+                return answer(hit);
+            const child = childCollection(childPath, hit, resolved);
+            if (child === undefined) {
+                throw new ResolutionRefusal(`${field}: ${pyRepr(segment)} matched, but its record lacks a field ${pyRepr(childPath)} needs, so it cannot be opened.`, "RESOLVE_TREE_UNOPENABLE");
+            }
+            where = child.collection;
+            level = await list(child.collection, child.query);
+        }
+    }
+    // Bare name: one level below every root container.
+    for (const parent of root.records) {
+        if (!isContainer(parent))
+            continue;
+        if (listings > MAX_TREE_LISTINGS)
+            break;
+        const child = childCollection(childPath, parent, resolved);
+        if (child === undefined)
+            continue;
+        const level = await list(child.collection, child.query);
+        const hit = level.records.find((record) => matchRecord(record, by, value));
+        if (hit !== undefined)
+            return answer(hit);
+    }
+    const top = root.records.map((record) => pyStrAny(readPath(record, by))).filter((text) => text !== "None");
+    const example = `${top[0] ?? "<top-level>"}/<folder>/${value}`;
+    throw new LookupExhausted(`${field}: no record in ${pyRepr(rootCollection)} or one level below it has ${by}=${pyRepr(value)} ` +
+        `(walked ${listings} listing(s), ${scanned} record(s)) on connection ${connectionId}. ` +
+        `This lookup is a tree, and a name is searched only that deep: for an item further down, ` +
+        `pass its path from the top, --resolve '${field}:${by}=${example}'.` +
+        (top.length > 0 && top.length <= CANDIDATE_LIMIT ? ` The top level holds: ${top.map(pyRepr).join(", ")}.` : ""), { field, collection: rootCollection, by, value, scanned, pages, capped: true });
+}

package/dist/registry/prepare/retry.js

@@ -1,5 +1,5 @@
 import { ConnectionRefusal, candidateConnections, candidateListing } from "./connections.js";
-import { PrepareRefusal, candidateErrorLine, candidateExhaustedLine, candidateLabel, candidateListingFailedMessage, candidateResolvesAllLine, noConnectionResolvesMessage, onlyConnectionMessage, pinnedConnectionExhaustedMessage, severalConnectionsResolveMessage, tryingOtherConnectionsLine, } from "./messages.js";
+import { PrepareRefusal, candidateErrorLine, candidateExhaustedLine, candidateLabel, candidateListingFailedMessage, candidateResolvesAllLine, collectionListingHint, noConnectionResolvesMessage, onlyConnectionMessage, pinnedConnectionExhaustedMessage, severalConnectionsResolveMessage, tryingOtherConnectionsLine, } from "./messages.js";
 import { LookupExhausted, ResolutionRefusal, resolveOne } from "./resolve.js";
 import { pyGet, pyStrAny } from "./support.js";
 /**
@@ -61,7 +61,7 @@ export async function retryOtherConnections(ctx, plan, first) {
                 throw error;
             throw new PrepareRefusal(candidateListingFailedMessage(first.message, error), "LOOKUP_EXHAUSTED_PINNED");
         }
-        throw new PrepareRefusal(pinnedConnectionExhaustedMessage(first.message, ctx.connectorKey, others.length, candidateListing(others)), "LOOKUP_EXHAUSTED_PINNED");
+        throw new PrepareRefusal(pinnedConnectionExhaustedMessage(first.message, ctx.connectorKey, others.length, candidateListing(others), collectionListingHint(ctx.connectorKey, first.collection, ctx.connectionId)), "LOOKUP_EXHAUSTED_PINNED");
     }
     let candidates;
     try {
@@ -76,7 +76,7 @@ export async function retryOtherConnections(ctx, plan, first) {
     }
     const others = candidates.filter((row) => !sameId(row));
     if (others.length === 0) {
-        throw new PrepareRefusal(onlyConnectionMessage(first.message, ctx.connectorKey), "LOOKUP_EXHAUSTED_ONLY_CONNECTION");
+        throw new PrepareRefusal(onlyConnectionMessage(first.message, ctx.connectorKey, collectionListingHint(ctx.connectorKey, first.collection, ctx.connectionId)), "LOOKUP_EXHAUSTED_ONLY_CONNECTION");
     }
     ctx.reporter.info(tryingOtherConnectionsLine(first.field, others.length, ctx.connectorKey));
     const winners = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.10.1",
+  "version": "6.10.3",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "388e366bc878b0b6701b2842d56479125f6a9edd"
+  "gitref": "d3639fb590ef392d76c174521c9cc1d280f7125a"
 }