@uipath/maestro-builder-sdk 6.10.2 → 6.11.0

package/dist/cli/commands/registry.js

@@ -130,6 +130,7 @@ export function registerRegistryCommands(program) {
         // `uip is connections list` and writes both keys into bindings.json.
         .option('--connection-id <id>', 'connection to read the schema through')
         .option('--connection <name>', 'pick the connection by name when several match')
+        .option('--connection-folder <folder>', 'pick the connection in the folder the flow runs in (name or key) when several match')
         .option('--bindings <file>', 'bindings file to update (default: ./bindings.json)')
         .option('--bind-connection <name>', 'symbolic connection name (default: the one label the source uses for this connector, else the connector suffix)')
         .option('--bind-folder <name>', 'symbolic folder name (default: the one folder label the source uses, else shared)')
@@ -170,6 +171,7 @@ export function registerRegistryCommands(program) {
         const argv = [connectorKey, action];
         addValue(argv, '--connection-id', options.connectionId);
         addValue(argv, '--connection', options.connection);
+        addValue(argv, '--connection-folder', options.connectionFolder);
         addValue(argv, '--bindings', options.bindings);
         addValue(argv, '--bind-connection', options.bindConnection);
         addValue(argv, '--bind-folder', options.bindFolder);

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

@@ -53,7 +53,68 @@ export declare function selectConnection(rows: readonly ConnectionRow[], connect
  * connection where the tenant-wide view is many. Widening first would turn an
  * unambiguous case into an ambiguous one.
  */
-export declare function discoverConnection(client: UipClient, connectorKey: string, name?: string): Promise<ConnectionRow>;
+export declare function discoverConnection(client: UipClient, connectorKey: string, name?: string, prefer?: ConnectionPreference): Promise<ConnectionRow>;
+/**
+ * What settles a choice among several enabled connections for one connector,
+ * consulted in this order, each only when the one before it did not decide.
+ *
+ * The eval tenant holds `is-sandboxes` (Slack), `is.sandboxes.test@gmail.com`
+ * (Drive) and the Outlook connections twice each, once in the
+ * `uipath-maestro-flow` folder and once in `uipath-maestro-case`. A name
+ * cannot tell them apart, and a lookup cannot either when both reach the same
+ * workspace — so every connector task paid one refused call and a re-run with
+ * `--connection-id` (flow-builder-sdk#818: 13 refusals in one run). What does
+ * tell them apart is WHERE the flow runs, and there are two honest sources for
+ * that: the author saying so, and the solution having already recorded it.
+ */
+export interface ConnectionPreference {
+    /**
+     * `--connection-folder`: the folder the flow runs in, by name
+     * (case-insensitive, as Orchestrator folder names are) or by folder key.
+     */
+    folder?: string;
+    /**
+     * Connection ids the solution already records for this connector —
+     * `resources/<folder>/connection/<connectorKey>/*.json`, whose `key` is the
+     * connection id `uip solution resources refresh` bound. See
+     * {@link solutionConnectionIds}.
+     */
+    solutionIds?: ReadonlySet<string>;
+}
+/** How {@link chooseConnection} settled on its row, for the line that reports it. */
+export type ConnectionChoice = "only" | "folder" | "solution";
+/** True when `row` is in `folder`: its `Folder` name ignoring case, or its `FolderKey` exactly. */
+export declare function inFolder(row: ConnectionRow, folder: string): boolean;
+/**
+ * {@link discoverConnection} with the reason it chose. Never guesses: each
+ * step either narrows to exactly one row or hands the choice on, and the last
+ * step is the refusal listing every candidate.
+ *
+ * 1. `--connection-folder` given: every enabled connection in the tenant (own
+ *    folder first, as {@link candidateConnections} orders them) in that
+ *    folder. Exactly one is the answer; none or several is a refusal, because
+ *    the author named a folder and a silent fallback would ignore them.
+ * 2. Otherwise the default discovery — own folder, then the tenant. One row is
+ *    the answer as before.
+ * 3. Several: those the solution already records. Exactly one is the answer.
+ * 4. Otherwise the ambiguity refusal, which names both flags.
+ */
+export declare function chooseConnection(client: UipClient, connectorKey: string, name?: string, prefer?: ConnectionPreference): Promise<{
+    row: ConnectionRow;
+    by: ConnectionChoice;
+}>;
+/**
+ * The connection ids a solution records for `connectorKey`: the `key` of every
+ * `resources/<folder>/connection/<connectorKey>/*.json` under each solution
+ * (a directory holding a `.uipx`) at `cwd`, above it, or one level below it —
+ * the flow-sdk layout keeps the solution as a child of the working directory.
+ *
+ * `uip solution resources refresh` writes these, and a seeded or re-edited
+ * solution carries them, so they are the tenant's own record of which
+ * connection this solution deploys with. A file that will not parse, or whose
+ * `type` names another connector, contributes nothing.
+ */
+export declare function solutionConnectionIds(cwd: string, connectorKey: string): Set<string>;
 /**
  * Every enabled connection for `connectorKey`, own folder FIRST
  * (`_connections.candidate_connections`).

package/dist/registry/prepare/connections.js

@@ -21,7 +21,8 @@
  * a {@link UipClient} and hand the rows to them. Every refusal's text is kept
  * verbatim — agents read these messages and follow them.
  */
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { Refusal, messageOf } from "../errors.js";
 import { isConnectionsList } from "../uip/commands.js";
@@ -102,10 +103,11 @@ export function selectConnection(rows, connectorKey, name, scope = "the tenant")
         const names = new Set(matched.map((row) => pyStrAny(row.Name)));
         // Python tested `name is not None`: an empty-string name takes this branch too.
         const remedy = (name !== undefined && name !== null) || names.size < matched.length
-            ? "They share a name, so --connection <name> cannot pick one; pass " +
-                "the id of the one in the folder you mean with --connection-id:"
-            : "Name the one you want with --connection <name>, or pass its id " +
-                "with --connection-id:";
+            ? "They share a name, so --connection <name> cannot pick one; name " +
+                "the folder the flow runs in with --connection-folder <folder>, or " +
+                "pass the id of the one you mean with --connection-id:"
+            : "Name the one you want with --connection <name>, name its folder " +
+                "with --connection-folder <folder>, or pass its id with --connection-id:";
         throw new ConnectionRefusal(`${matched.length} enabled ${connectorKey} connections in ${scope}, and they ` +
             "are not interchangeable — a record that exists in one workspace need " +
             `not exist in another. ${remedy}\n${listed}`, "CONNECTION_AMBIGUOUS");
@@ -121,14 +123,137 @@ export function selectConnection(rows, connectorKey, name, scope = "the tenant")
  * connection where the tenant-wide view is many. Widening first would turn an
  * unambiguous case into an ambiguous one.
  */
-export async function discoverConnection(client, connectorKey, name) {
+export async function discoverConnection(client, connectorKey, name, prefer = {}) {
+    return (await chooseConnection(client, connectorKey, name, prefer)).row;
+}
+/** True when `row` is in `folder`: its `Folder` name ignoring case, or its `FolderKey` exactly. */
+export function inFolder(row, folder) {
+    const wanted = folder.trim();
+    if (!wanted)
+        return false;
+    return (pyStrAny(pyGet(row, "Folder", "")).toLowerCase() === wanted.toLowerCase() ||
+        pyStrAny(pyGet(row, "FolderKey", "")) === wanted);
+}
+/**
+ * {@link discoverConnection} with the reason it chose. Never guesses: each
+ * step either narrows to exactly one row or hands the choice on, and the last
+ * step is the refusal listing every candidate.
+ *
+ * 1. `--connection-folder` given: every enabled connection in the tenant (own
+ *    folder first, as {@link candidateConnections} orders them) in that
+ *    folder. Exactly one is the answer; none or several is a refusal, because
+ *    the author named a folder and a silent fallback would ignore them.
+ * 2. Otherwise the default discovery — own folder, then the tenant. One row is
+ *    the answer as before.
+ * 3. Several: those the solution already records. Exactly one is the answer.
+ * 4. Otherwise the ambiguity refusal, which names both flags.
+ */
+export async function chooseConnection(client, connectorKey, name, prefer = {}) {
+    if (prefer.folder !== undefined && prefer.folder.trim() !== "") {
+        const folder = prefer.folder.trim();
+        const all = await candidateConnections(client, connectorKey, name);
+        const there = all.filter((row) => inFolder(row, folder));
+        if (there.length === 1)
+            return { row: there[0], by: "folder" };
+        if (there.length === 0) {
+            const qualifier = name ? ` named ${pyRepr(name)}` : "";
+            throw new ConnectionRefusal(`no enabled ${connectorKey} connection${qualifier} in folder ${pyRepr(folder)}. ` +
+                (all.length > 0
+                    ? `The enabled ones are:\n${candidateLines(all)}`
+                    : "List what exists with:\n  uip is connections list --all-folders"), "CONNECTION_NONE_IN_FOLDER");
+        }
+        return { row: selectConnection(there, connectorKey, name, "the tenant"), by: "folder" };
+    }
     let rows = enabledConnections(await listConnections(client, { allFolders: false }), connectorKey, name);
     let scope = "your folder";
     if (rows.length === 0) {
         rows = enabledConnections(await listConnections(client, { allFolders: true }), connectorKey, name);
         scope = "the tenant";
     }
-    return selectConnection(rows, connectorKey, name, scope);
+    if (rows.length > 1 && prefer.solutionIds !== undefined && prefer.solutionIds.size > 0) {
+        const recorded = rows.filter((row) => prefer.solutionIds.has(pyStrAny(pyGet(row, "Id", ""))));
+        if (recorded.length === 1)
+            return { row: recorded[0], by: "solution" };
+    }
+    return { row: selectConnection(rows, connectorKey, name, scope), by: "only" };
+}
+/**
+ * The connection ids a solution records for `connectorKey`: the `key` of every
+ * `resources/<folder>/connection/<connectorKey>/*.json` under each solution
+ * (a directory holding a `.uipx`) at `cwd`, above it, or one level below it —
+ * the flow-sdk layout keeps the solution as a child of the working directory.
+ *
+ * `uip solution resources refresh` writes these, and a seeded or re-edited
+ * solution carries them, so they are the tenant's own record of which
+ * connection this solution deploys with. A file that will not parse, or whose
+ * `type` names another connector, contributes nothing.
+ */
+export function solutionConnectionIds(cwd, connectorKey) {
+    const ids = new Set();
+    const solutions = new Set();
+    const hasUipx = (dir) => {
+        try {
+            return readdirSync(dir).some((entry) => entry.endsWith(".uipx"));
+        }
+        catch {
+            return false;
+        }
+    };
+    let dir = resolvePath(cwd);
+    for (let depth = 0; depth < 6; depth++) {
+        if (hasUipx(dir))
+            solutions.add(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    try {
+        for (const entry of readdirSync(cwd, { withFileTypes: true })) {
+            if (entry.isDirectory() && hasUipx(join(cwd, entry.name)))
+                solutions.add(resolvePath(cwd, entry.name));
+        }
+    }
+    catch {
+        // An unreadable cwd records nothing.
+    }
+    for (const solution of solutions) {
+        const resources = join(solution, "resources");
+        let folders;
+        try {
+            folders = readdirSync(resources);
+        }
+        catch {
+            continue;
+        }
+        for (const folder of folders) {
+            const connectorDir = join(resources, folder, "connection", connectorKey);
+            let files;
+            try {
+                files = readdirSync(connectorDir).filter((file) => file.endsWith(".json"));
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                try {
+                    const resource = pyGet(JSON.parse(readFileSync(join(connectorDir, file), "utf8")), "resource", null);
+                    if (!isPlainObject(resource))
+                        continue;
+                    const type = pyGet(resource, "type", null);
+                    if (pyTruthy(type) && type !== connectorKey)
+                        continue;
+                    const key = pyStrAny(pyGet(resource, "key", ""));
+                    if (key)
+                        ids.add(key);
+                }
+                catch {
+                    // Not JSON: records nothing.
+                }
+            }
+        }
+    }
+    return ids;
 }
 /**
  * Every enabled connection for `connectorKey`, own folder FIRST

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

@@ -42,6 +42,11 @@ export declare class PrepareRefusal extends Refusal {
 export declare function exitText(error: unknown): string;
 /** `  connection: <Name> (<id>)` — `found.get('Name')` renders `None` when the row has none, as Python did. */
 export declare function connectionLine(row: Record<string, unknown>, connectionId: string): string;
+/**
+ * Why discovery chose this connection when several matched: the folder the
+ * author named, or the solution's own record of the connection.
+ */
+export declare function connectionChoiceLine(row: Record<string, unknown>, by: "folder" | "solution", folder?: string): string;
 /** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
 export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
 /** ` (the label Demo.flow.ts uses)` — appended to a bindings line whose name came from the source. */

package/dist/registry/prepare/messages.js

@@ -58,6 +58,16 @@ export function exitText(error) {
 export function connectionLine(row, connectionId) {
     return `  connection: ${pyStrAny(pyGet(row, "Name", null))} (${connectionId})`;
 }
+/**
+ * Why discovery chose this connection when several matched: the folder the
+ * author named, or the solution's own record of the connection.
+ */
+export function connectionChoiceLine(row, by, folder) {
+    const where = pyStrAny(row.Folder);
+    return by === "folder"
+        ? `  connection: chose the one in folder ${pyRepr(pyOr(folder, where))} (--connection-folder)`
+        : `  connection: chose the one the solution records (resources/*/connection/…, folder: ${where})`;
+}
 /** `  bindings: <symbolic name> -> <bindings.json>`, once per row this run changed. */
 export function bindingsLine(symbolicName, bindingsPath) {
     return `  bindings: ${symbolicName} -> ${bindingsPath}`;

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

@@ -10,6 +10,12 @@ export interface PrepareOptions {
     connectionId?: string;
     /** `--connection <name>`: pick the connection by name when several match. */
     connection?: string;
+    /**
+     * `--connection-folder <folder>`: the folder the flow runs in (name or key).
+     * Picks among several enabled connections; without it, the ids the solution
+     * already records are tried before the ambiguity refusal.
+     */
+    connectionFolder?: string;
     /** `--bindings` (default `./bindings.json`). */
     bindings?: string;
     /**

package/dist/registry/prepare/pipeline.js

@@ -36,11 +36,11 @@ import { expandGenericForConnector, genericTemplatesByOp } from "../library-buil
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
 import { registryCatalog } from "./actions.js";
-import { discoverConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } from "./connections.js";
+import { chooseConnection, listConnections, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, solutionConnectionIds, } from "./connections.js";
 import { prepareEvent } from "./event.js";
 import { descriptorUsage } from "./handoff.js";
 import { ResolutionsExhausted, allParentsResolved, resolvedParentValues, writeResolutions } from "./ledger.js";
-import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, ambiguousLabelsMessage, connectionChoiceLine, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, flagDiffersFromSourceLine, keptSchemaMessage, labelTakenMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, sharedLabelMessage, sourceLabelSuffix, tsNote, partlyUnreadableLabelLine, unreadableLabelLine, unresolvedOperationMessage, } from "./messages.js";
 import { ObjectMatchRefusal, RESOLUTIONS_FILENAME, matchObject, recordObjectResolution } from "./objects.js";
 import { countInputFields, keepPreparedSchema, lookupSpecsFromOverlay, mergeFilesInto, parentFields as overlayParentFields, schemaActionParents, } from "./overlay.js";
 import { declaredParents, objectActionRequest, objectActionSpecs, parseFields } from "./parents.js";
@@ -195,12 +195,19 @@ async function connect(options, ports) {
     const labels = options.noBindings ? undefined : chooseLabels(options, ports);
     let row;
     let connectionId;
+    let chosenBy = "only";
     if (!options.connectionId) {
         // Discover the connection when the caller did not name one, and record it
         // in bindings.json so the author never has to look up either key — the
         // step that removes 4-7 tool calls per task.
-        row = await discoverConnection(ports.client, options.connectorKey, options.connection);
+        const cwd = ports.cwd ?? process.cwd();
+        const choice = await chooseConnection(ports.client, options.connectorKey, options.connection, {
+            folder: options.connectionFolder,
+            solutionIds: solutionConnectionIds(cwd, options.connectorKey),
+        });
+        row = choice.row;
         connectionId = pyStrAny(row.Id);
+        chosenBy = choice.by;
     }
     else {
         // An explicit id gets the same gate discovery applies: a `State: Failed`
@@ -209,6 +216,8 @@ async function connect(options, ports) {
         row = await lookupConnection(ports.client, options.connectorKey, connectionId);
     }
     info(connectionLine(row, connectionId));
+    if (chosenBy !== "only")
+        info(connectionChoiceLine(row, chosenBy, options.connectionFolder));
     if (!labels)
         return { connectionId, row };
     // Recorded on BOTH routes. Until 3.30.5 only discovery wrote it, and the
@@ -251,7 +260,9 @@ export async function prepareConnector(options, ports) {
     // Whether the CALLER chose the connection, recorded before discovery answers
     // with its own. An explicit choice is never second-guessed: the retry below
     // is for a connection this command picked, not for one the author named.
-    const pinned = pyTruthy(options.connectionId) || pyTruthy(options.connection);
+    // A named folder is a choice too: probing the other folders' connections
+    // after the author said which folder the flow runs in would overrule them.
+    const pinned = pyTruthy(options.connectionId) || pyTruthy(options.connection) || pyTruthy(options.connectionFolder);
     const connected = await connect(options, ports);
     try {
         return await prepareOnConnection(options, ports, connected);

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-cli.d.ts

@@ -26,6 +26,8 @@ export interface PrepareConnectorOptions {
     connectionId?: string;
     /** Pick the connection by name when several match. */
     connection?: string;
+    /** `--connection-folder`: the folder the flow runs in, when several connections match. */
+    connectionFolder?: string;
     /** bindings file to add the discovered connection to. */
     bindings?: string;
     bindConnection?: string;

package/dist/registry/prepare-cli.js

@@ -15,7 +15,8 @@ import { defaultUipClient } from "./uip/client.js";
 const DEFAULT_CONNECTOR_IMPORT = PACKAGE_NAME;
 const USAGE = [
     "Usage: flow-sdk registry prepare <connector-key> --action <name> [--connection-id <id>]",
-    "                                [--connection <name>] [--bindings <file>] [--no-bindings]",
+    "                                [--connection <name>] [--connection-folder <folder>]",
+    "                                [--bindings <file>] [--no-bindings]",
     "                                [--object <name> | --all-objects] [-f NAME=VALUE ...]",
     "                                [--resolve FIELD:BY=VALUE ...] [--refresh-lookups]",
     "                                [--out <dir>] [--version <v>] [--import <specifier>]",
@@ -29,6 +30,7 @@ export function pipelineOptions(options) {
         action: options.action,
         connectionId: options.connectionId,
         connection: options.connection,
+        connectionFolder: options.connectionFolder,
         bindings: options.bindings,
         bindConnection: options.bindConnection,
         bindFolder: options.bindFolder,
@@ -101,6 +103,7 @@ export function parseArgs(argv) {
     for (const name of [
         "--connection-id",
         "--connection",
+        "--connection-folder",
         "--bindings",
         "--bind-connection",
         "--bind-folder",
@@ -147,6 +150,7 @@ export function parseArgs(argv) {
         action: positionals[1],
         connectionId: value(argv, "--connection-id"),
         connection: value(argv, "--connection"),
+        connectionFolder: value(argv, "--connection-folder"),
         bindings: value(argv, "--bindings"),
         bindConnection: value(argv, "--bind-connection"),
         bindFolder: value(argv, "--bind-folder"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.10.2",
+  "version": "6.11.0",
   "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": "0c68e2f56257719fc7db812ce8cdb3e097c5444c"
+  "gitref": "fa8ffa3eea8369ff520a8214644c971df0c4af74"
 }