@uipath/maestro-builder-sdk 6.8.5 → 6.9.0

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

@@ -18,6 +18,7 @@ import { lowerFirst, pyStr, pyStrip, startsWithUpper } from "../compat/pystr.js"
 import { mapConcurrent } from "../concurrency.js";
 import { Refusal } from "../errors.js";
 import { isTriggersDescribe, isTriggersObjects } from "../uip/commands.js";
+import { failureReason } from "../uip/envelope.js";
 import { safeCacheName } from "../uip/response-cache.js";
 import { schemaCacheScope, writeCache } from "./context.js";
 import { objectsComeFromTheConnection } from "./generic-expand.js";
@@ -66,8 +67,8 @@ async function runJson(client, argv, timeoutMs) {
         payload = JSON.parse(result.stdout);
     }
     catch {
-        const text = codePointSlice(pyStrip(result.stderr || result.stdout), 0, 300);
-        throw new EventDiscoveryError(`${head} did not answer JSON: ${text || "no output"}`, result.refused === true);
+        const text = codePointSlice(failureReason(result), 0, 300);
+        throw new EventDiscoveryError(`${head} did not answer JSON: ${text}`, result.refused === true);
     }
     if (get(payload, "Result") !== "Success") {
         // `refused` is carried here too, although the refusing client in this tree

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

@@ -5,7 +5,8 @@ import type { UipClient } from "../uip/client.js";
  * Exact prefix only: the same search returns
  * `uipath.agent.resource.tool.connector.<key>.<action>` and
  * `uipath.connector.trigger.<key>.<event>`, which are not actions of this node
- * and would read as alternatives an author could pass.
+ * and would read as alternatives an author could pass as an action. The events
+ * are listed separately, by {@link registryEventIds}.
  */
 export declare function registryActionIds(payload: unknown, connectorKey: string): string[];
 /**
@@ -19,8 +20,44 @@ export declare function registryActionIds(payload: unknown, connectorKey: string
  */
 export declare function closestActions(action: string, candidates: readonly string[]): string[];
 /**
- * `_registry_actions`: the action ids the registry serves for `connectorKey`,
- * or `[]` when the search fails or does not answer JSON. This runs only on the
- * failure path, where an empty answer is itself the message ("returned nothing").
+ * {@link closestActions}, kept only where the candidate is plausibly what was
+ * meant: it shares MOST of the wanted id's words (`list-all-records` →
+ * `list-records`), or it is a near spelling (`record-creatd` → `record-created`,
+ * `send-mail` → `send-email`). One shared word is not enough: `record-created`
+ * shares "record" with every Data Fabric action, and offering
+ * `update-entity-record` as the closest match to an EVENT name points the
+ * author at the wrong namespace.
  */
-export declare function registryActions(client: UipClient, connectorKey: string, timeoutMs?: number): Promise<string[]>;
+export declare function plausibleMatches(wanted: string, candidates: readonly string[]): string[];
+/** The two node-type forms a connector event is served in. */
+export type EventForm = "trigger" | "event";
+/** One event id in a `registry search` reply, with the forms it was served in. */
+export interface RegistryEvent {
+    id: string;
+    /** `trigger` = `uipath.connector.trigger.<key>.<id>` (starts a flow), `event` = `…event…` (waits mid-flow). */
+    forms: EventForm[];
+}
+/**
+ * The event ids in a `registry search <key>` reply, sorted, each with its forms.
+ *
+ * The form is kept because the two can come and go separately: on 2026-09-16
+ * the Data Fabric `.event.` pair was still served after its `.trigger.` pair
+ * was gone, and `prepare` probes the `.trigger.` form.
+ */
+export declare function registryEventIds(payload: unknown, connectorKey: string): RegistryEvent[];
+/** What `registry search <key>` served, or why it could not say. */
+export interface RegistryCatalog {
+    actions: string[];
+    events: RegistryEvent[];
+    /**
+     * Set when the search itself failed or did not answer JSON. The lists are
+     * then empty because nothing was read, NOT because the catalog is empty, and
+     * a message must not say "returned nothing".
+     */
+    failure?: string;
+}
+/**
+ * `registry search <key>`, read for both catalogs. This runs only on the
+ * failure path, to tell the author what the catalog does serve.
+ */
+export declare function registryCatalog(client: UipClient, connectorKey: string, timeoutMs?: number): Promise<RegistryCatalog>;

package/dist/registry/prepare/actions.js

@@ -3,9 +3,14 @@
  *
  * When `registry get uipath.connector.<key>.<action>` finds nothing — and the
  * event namespaces do not have it either — the one question left is what the
- * tenant actually serves for that connector, so the refusal can list it. That
- * is a `registry search <key>` against the live catalog rather than a cached
- * index, because a stale index is one of the ways this failure happens.
+ * catalog actually serves for that connector, so the refusal can list it: its
+ * actions AND its events, because the author's name may have meant either.
+ * That is one `registry search <key>`.
+ *
+ * `registry get` and `registry search` both answer from the CLI's local node
+ * index and pull the tenant catalog only when that index is missing (uipath-cli
+ * `packages/maestro-sdk/src/registry/node-sync-service.ts:307-323`, `:570-597`),
+ * so what they list can be stale; the refusal says how to refresh it.
  *
  * Ported from `_registry_actions` / `_closest_actions` in
  * `prepare_connector.py`. The fetch goes through the injected {@link UipClient};
@@ -13,6 +18,7 @@
  */
 import { compareCodePoints, sortedStrings } from "../compat/compare.js";
 import { registrySearch } from "../uip/commands.js";
+import { failureReason, findJsonDocument, tail } from "../uip/envelope.js";
 import { isPlainObject, pyOr } from "./support.js";
 /**
  * The action ids in a `registry search <key>` reply, sorted.
@@ -20,7 +26,8 @@ import { isPlainObject, pyOr } from "./support.js";
  * Exact prefix only: the same search returns
  * `uipath.agent.resource.tool.connector.<key>.<action>` and
  * `uipath.connector.trigger.<key>.<event>`, which are not actions of this node
- * and would read as alternatives an author could pass.
+ * and would read as alternatives an author could pass as an action. The events
+ * are listed separately, by {@link registryEventIds}.
  */
 export function registryActionIds(payload, connectorKey) {
     // `json.loads(stdout).get("Data") or []`: a reply that is not an object has
@@ -74,21 +81,88 @@ export function closestActions(action, candidates) {
     });
     return scored.map(({ candidate }) => candidate);
 }
+/** Levenshtein distance, two rows. Short strings only (operation ids). */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
 /**
- * `_registry_actions`: the action ids the registry serves for `connectorKey`,
- * or `[]` when the search fails or does not answer JSON. This runs only on the
- * failure path, where an empty answer is itself the message ("returned nothing").
+ * {@link closestActions}, kept only where the candidate is plausibly what was
+ * meant: it shares MOST of the wanted id's words (`list-all-records` →
+ * `list-records`), or it is a near spelling (`record-creatd` → `record-created`,
+ * `send-mail` → `send-email`). One shared word is not enough: `record-created`
+ * shares "record" with every Data Fabric action, and offering
+ * `update-entity-record` as the closest match to an EVENT name points the
+ * author at the wrong namespace.
  */
-export async function registryActions(client, connectorKey, timeoutMs) {
-    const result = await client.run(registrySearch(connectorKey), timeoutMs === undefined ? undefined : { timeoutMs });
-    if (result.code !== 0)
+export function plausibleMatches(wanted, candidates) {
+    const words = new Set(wanted.split("-"));
+    const limit = Math.max(2, Math.floor(wanted.length / 3));
+    const kept = closestActions(wanted, candidates)
+        .map((candidate, rank) => ({ candidate, rank, distance: editDistance(wanted, candidate) }))
+        .filter(({ candidate, distance }) => {
+        const shared = [...words].filter((word) => candidate.split("-").includes(word)).length;
+        return shared * 2 > words.size || distance <= limit;
+    });
+    // Nearest spelling first; the word-overlap rank breaks ties.
+    kept.sort((a, b) => a.distance - b.distance || a.rank - b.rank);
+    return kept.map(({ candidate }) => candidate);
+}
+/**
+ * The event ids in a `registry search <key>` reply, sorted, each with its forms.
+ *
+ * The form is kept because the two can come and go separately: on 2026-09-16
+ * the Data Fabric `.event.` pair was still served after its `.trigger.` pair
+ * was gone, and `prepare` probes the `.trigger.` form.
+ */
+export function registryEventIds(payload, connectorKey) {
+    if (!isPlainObject(payload))
         return [];
-    let payload;
-    try {
-        payload = JSON.parse(result.stdout);
-    }
-    catch {
+    const data = pyOr(payload.Data, []);
+    if (!Array.isArray(data))
         return [];
+    const forms = new Map();
+    for (const entry of data) {
+        if (!isPlainObject(entry))
+            continue;
+        const nodeType = pyOr(entry.NodeType, "");
+        if (typeof nodeType !== "string")
+            continue;
+        for (const form of ["trigger", "event"]) {
+            const prefix = `uipath.connector.${form}.${connectorKey}.`;
+            if (!nodeType.startsWith(prefix))
+                continue;
+            const rest = nodeType.slice(prefix.length);
+            if (rest.includes("."))
+                continue;
+            if (!forms.has(rest))
+                forms.set(rest, new Set());
+            forms.get(rest).add(form);
+        }
+    }
+    return sortedStrings(forms.keys()).map((id) => ({
+        id,
+        forms: ["trigger", "event"].filter((form) => forms.get(id).has(form)),
+    }));
+}
+/**
+ * `registry search <key>`, read for both catalogs. This runs only on the
+ * failure path, to tell the author what the catalog does serve.
+ */
+export async function registryCatalog(client, connectorKey, timeoutMs) {
+    const result = await client.run(registrySearch(connectorKey), timeoutMs === undefined ? undefined : { timeoutMs });
+    if (result.code !== 0)
+        return { actions: [], events: [], failure: failureReason(result) };
+    const payload = findJsonDocument(result.stdout);
+    if (payload === undefined) {
+        return { actions: [], events: [], failure: `it did not answer JSON: ${tail(result.stdout.trim()) || "no output"}` };
     }
-    return registryActionIds(payload, connectorKey);
+    return { actions: registryActionIds(payload, connectorKey), events: registryEventIds(payload, connectorKey) };
 }

package/dist/registry/prepare/connections.js

@@ -23,10 +23,9 @@
  */
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { pyJsonStringify } from "../codecs/pyjson.js";
-import { pyStrip } from "../compat/pystr.js";
 import { Refusal, messageOf } from "../errors.js";
 import { isConnectionsList } from "../uip/commands.js";
-import { dataItems, parseEnvelope } from "../uip/envelope.js";
+import { dataItems, failureReason, parseEnvelope } from "../uip/envelope.js";
 import { isPlainObject, notJsonReason, pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 /** No usable connection, with the reason and the way forward (`_connections.ConnectionError_`). */
 export class ConnectionRefusal extends Refusal {
@@ -44,7 +43,7 @@ export class ConnectionRefusal extends Refusal {
 export async function listConnections(client, options) {
     const result = await client.run(isConnectionsList({ allFolders: options.allFolders, byoa: options.byoa }));
     if (result.code !== 0) {
-        throw new ConnectionRefusal(`listing connections failed: ${pyStrip(result.stderr) || "no output"}`, "CONNECTION_LISTING_FAILED");
+        throw new ConnectionRefusal(`listing connections failed: ${failureReason(result)}`, "CONNECTION_LISTING_FAILED");
     }
     const envelope = parseEnvelope(result.stdout);
     if (envelope === undefined) {

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

@@ -1,4 +1,4 @@
-import { type BuildContext } from "../library-build/context.js";
+import { type BuildContext, type RegistryMiss } from "../library-build/context.js";
 import { type EventFacts } from "../library-build/events.js";
 import { type Dict } from "../library-build/py.js";
 import type { LibraryEntry } from "../model/library.js";
@@ -87,10 +87,19 @@ export interface EventPrepareResult {
     filterFields: unknown[];
     definition: EventDefinition;
 }
+/** `<key> <action>` is not an event: the `.trigger.` probe missed, and why. */
+export interface EventMiss {
+    missed: RegistryMiss;
+}
 /**
- * `_prepare_event`. Returns `undefined` when `<key> <action>` is not an event
- * either, so the caller can raise the ordinary unknown-action refusal;
- * everything else is handled here, refusals included. `ctx.connectionId` must
- * already be the connection: the trigger definition only answers with one.
+ * `_prepare_event`. Returns an {@link EventMiss} when `<key> <action>` is not
+ * an event either — carrying the probe's reason, so the caller can put it in
+ * the one refusal that names both namespaces; everything else is handled here,
+ * refusals included. `ctx.connectionId` must already be the connection: the
+ * trigger definition only answers with one.
+ *
+ * The probe is quiet. The Python printed a `WARN: registry get failed for …`
+ * here, and the port printed it with an empty reason, because the CLI's reason
+ * is on stdout; the reason now travels in the result instead.
  */
-export declare function prepareEvent(ctx: BuildContext, options: EventPrepareOptions): Promise<EventPrepareResult | undefined>;
+export declare function prepareEvent(ctx: BuildContext, options: EventPrepareOptions): Promise<EventPrepareResult | EventMiss>;

package/dist/registry/prepare/event.js

@@ -20,7 +20,7 @@
  * through its reporter, in the Python's order.
  */
 import { extractCanonical, nodeOf } from "../library-build/canonical.js";
-import { registryGet } from "../library-build/context.js";
+import { registryProbe } from "../library-build/context.js";
 import { EventDiscoveryError, eventFacts, mergeDescribeIntoNode, triggersDescribe, triggersObjects, unionEventParameters, } from "../library-build/events.js";
 import { get, isRecord } from "../library-build/py.js";
 import { planLibrary } from "../library-build/plan.js";
@@ -114,10 +114,15 @@ function fieldsOf(section) {
     return Array.isArray(fields) ? fields : [];
 }
 /**
- * `_prepare_event`. Returns `undefined` when `<key> <action>` is not an event
- * either, so the caller can raise the ordinary unknown-action refusal;
- * everything else is handled here, refusals included. `ctx.connectionId` must
- * already be the connection: the trigger definition only answers with one.
+ * `_prepare_event`. Returns an {@link EventMiss} when `<key> <action>` is not
+ * an event either — carrying the probe's reason, so the caller can put it in
+ * the one refusal that names both namespaces; everything else is handled here,
+ * refusals included. `ctx.connectionId` must already be the connection: the
+ * trigger definition only answers with one.
+ *
+ * The probe is quiet. The Python printed a `WARN: registry get failed for …`
+ * here, and the port printed it with an empty reason, because the CLI's reason
+ * is on stdout; the reason now travels in the result instead.
  */
 export async function prepareEvent(ctx, options) {
     const { connectorKey, action, connectionId, out } = options;
@@ -125,13 +130,16 @@ export async function prepareEvent(ctx, options) {
     const info = (line) => ctx.reporter.info(line);
     const warn = (line) => ctx.reporter.warn(line);
     const { trigger: triggerNodeType, event: eventNodeType } = eventNodeTypes(connectorKey, action);
-    const cacheName = await registryGet(ctx, triggerNodeType);
-    if (cacheName === undefined)
-        return undefined;
-    const payload = ctx.caches.registry.read(cacheName);
+    const probe = await registryProbe(ctx, triggerNodeType);
+    if ("miss" in probe)
+        return { missed: probe.miss };
+    const payload = ctx.caches.registry.read(probe.name);
     const canonical = extractCanonical(nodeOf(payload));
-    if (canonical === undefined)
-        return undefined;
+    if (canonical === undefined) {
+        // An answer, but not one this code can read as a trigger definition. Not
+        // "absent", so the caller must not say it is.
+        return { missed: { nodeType: triggerNodeType, reason: "the registry answered, but not with a node definition", notFound: false } };
+    }
     if (pyTruthy(options.fields))
         throw new PrepareRefusal(eventParentFieldsMessage(), "EVENT_NO_PARENT_FIELDS");
     if (options.allObjects)

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

@@ -21,6 +21,7 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal } from "../errors.js";
+import { type RegistryCatalog } from "./actions.js";
 export declare const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
 export declare const PREPARE_COMMAND = "npx flow-sdk registry prepare";
@@ -45,16 +46,43 @@ export declare function connectionLine(row: Record<string, unknown>, connectionI
 export declare function bindingsLine(symbolicName: string, bindingsPath: string): string;
 /** `_missing_generic_schema_message`: a Generic action that expanded to nothing. */
 export declare function missingGenericSchemaMessage(operation: string, objectName?: string | null): string;
+/** One `registry get` probe that missed, as a refusal quotes it. */
+export interface ProbeMiss {
+    nodeType: string;
+    /** The CLI's reason, never empty (`failureReason`). */
+    reason: string;
+}
 /**
- * `_unresolved_action_message`: what to do when the action id is not a
- * registry key. `actions` is what `registry search <key>` served (see
- * `actions.ts`); the message is pure over it.
+ * What to do when `<key> <name>` is neither an action nor an event: both
+ * `registry get` probes answered "Node not found". Pure over its inputs.
+ *
+ * It names both probes, because the author's name may have meant either
+ * namespace and the SDK cannot know which (so the code is OPERATION_UNKNOWN,
+ * not ACTION_UNKNOWN), and it lists both catalogs `registry search <key>`
+ * served. Until 2026-09 this was an action-only message: it named the action
+ * node type, said "Re-run with a registry action id" and listed only actions,
+ * because `registryActionIds` removes event ids by design. For
+ * `uipath-uipath-dataservice record-created` — an EVENT the catalog had stopped
+ * serving — that sent the author after action ids (2026-09-23 eval,
+ * `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
  *
  * NOT auto-substituted, deliberately: the baked action id and the registry key
  * are different namespaces, and guessing between them would emit a node both
  * offline validators accept and the runtime dispatches to the wrong operation.
  */
-export declare function unresolvedActionMessage(connectorKey: string, action: string, nodeType: string, actions: readonly string[]): string;
+export declare function unresolvedOperationMessage(input: {
+    connectorKey: string;
+    name: string;
+    probes: readonly ProbeMiss[];
+    catalog: RegistryCatalog;
+}): string;
+/**
+ * A `registry get` probe failed for a reason other than "Node not found" — an
+ * error inside the CLI, a refusal, a timeout, a reply that is not JSON. That is
+ * not evidence the node is absent, so this refusal says so and carries the
+ * CLI's own reasons instead of listing alternatives.
+ */
+export declare function registryGetFailedMessage(connectorKey: string, name: string, probes: readonly ProbeMiss[]): string;
 export declare function noCanonicalEntryMessage(nodeType: string): string;
 /** The `-f` names do not match any api-type ObjectAction; `specs` are the actions' parent lists. */
 export declare function parentFieldNamesMismatchMessage(given: readonly string[], specs: ReadonlyArray<readonly [string, readonly string[]]>): string;

package/dist/registry/prepare/messages.js

@@ -21,7 +21,7 @@
  *     `core/cli-spelling.ts`) without this module reading the environment.
  */
 import { Refusal, messageOf } from "../errors.js";
-import { closestActions } from "./actions.js";
+import { plausibleMatches } from "./actions.js";
 import { pyGet, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 export const PREFIX = "prepare-connector: ";
 /** The spelling the Python hard-coded into every pasteable re-run. */
@@ -74,33 +74,98 @@ export function missingGenericSchemaMessage(operation, objectName) {
         "not need connection-specific fields, use the baked connector descriptor " +
         "without custom fields instead.");
 }
+function probeLines(probes) {
+    return probes.map((probe) => `  registry get ${probe.nodeType} → ${probe.reason}`);
+}
+/** `record-created (trigger, event)`: an event id with the forms the registry served it in. */
+function eventLabel(event) {
+    return `${event.id} (${event.forms.join(", ")})`;
+}
+/** How many of `wanted`'s hyphen tokens `candidate` shares. */
+function sharedTokens(wanted, candidate) {
+    const tokens = new Set(candidate.split("-"));
+    return [...new Set(wanted.split("-"))].filter((token) => tokens.has(token)).length;
+}
 /**
- * `_unresolved_action_message`: what to do when the action id is not a
- * registry key. `actions` is what `registry search <key>` served (see
- * `actions.ts`); the message is pure over it.
+ * What to do when `<key> <name>` is neither an action nor an event: both
+ * `registry get` probes answered "Node not found". Pure over its inputs.
+ *
+ * It names both probes, because the author's name may have meant either
+ * namespace and the SDK cannot know which (so the code is OPERATION_UNKNOWN,
+ * not ACTION_UNKNOWN), and it lists both catalogs `registry search <key>`
+ * served. Until 2026-09 this was an action-only message: it named the action
+ * node type, said "Re-run with a registry action id" and listed only actions,
+ * because `registryActionIds` removes event ids by design. For
+ * `uipath-uipath-dataservice record-created` — an EVENT the catalog had stopped
+ * serving — that sent the author after action ids (2026-09-23 eval,
+ * `skill-flow-datafabric-trigger-lifecycle`, v2 command 33).
  *
  * NOT auto-substituted, deliberately: the baked action id and the registry key
  * are different namespaces, and guessing between them would emit a node both
  * offline validators accept and the runtime dispatches to the wrong operation.
  */
-export function unresolvedActionMessage(connectorKey, action, nodeType, actions) {
+export function unresolvedOperationMessage(input) {
+    const { connectorKey: key, name, probes, catalog } = input;
     const lines = [
-        `${PREFIX}\`registry get ${nodeType}\` found no such node.`,
+        `${PREFIX}\`${key} ${name}\` is neither an action nor an event the registry serves:`,
+        ...probeLines(probes),
         "",
-        "The baked library's action id is not always the registry's key — a Generic",
-        "op is `list-all-records` in the library and materializes per object, while",
-        "the registry serves the un-expanded form. Re-run with a registry action id.",
+        // flow-v1 `packages/flow-core/src/manifest/fetchers.ts:286`, `:336-337`: the
+        // node catalog is the typecache Search/Catalog, and a trigger node exists
+        // only where it serves one.
+        "A Flow node exists only if the tenant's Flow node catalog serves it. An event that",
+        "`uip is triggers objects` lists but this registry does not cannot be prepared or",
+        "compiled, and hand-writing its node JSON does not make it offered.",
     ];
-    if (actions.length === 0) {
-        lines.push("", `\`registry search ${connectorKey}\` returned nothing. If the catalog looks`, "stale, refresh it first: `uip maestro flow registry pull --force`.");
+    if (catalog.failure !== undefined) {
+        lines.push("", `\`registry search ${key}\` failed: ${catalog.failure}`, "so what the registry does serve for it could not be listed.");
         return lines.join("\n");
     }
-    const close = closestActions(action, actions);
-    if (close.length > 0)
-        lines.push("", `Closest to "${action}": ${close.slice(0, 3).join(", ")}`);
-    lines.push("", `All actions the registry serves for ${connectorKey}:`, ...actions.map((a) => `  ${a}`));
+    if (catalog.events.length > 0) {
+        const close = plausibleMatches(name, catalog.events.map((event) => event.id));
+        const byId = new Map(catalog.events.map((event) => [event.id, event]));
+        if (close.length > 0)
+            lines.push("", `Closest event to "${name}": ${close.slice(0, 3).map((id) => eventLabel(byId.get(id))).join(", ")}`);
+        lines.push("", `Events the registry serves for ${key}:`, ...catalog.events.map((event) => `  ${eventLabel(event)}`));
+    }
+    else {
+        lines.push("", `\`registry search ${key}\` lists no \`uipath.connector.{trigger,event}.${key}.*\` node: the`, `registry serves no event for ${key}.`);
+    }
+    if (catalog.actions.length > 0) {
+        const close = plausibleMatches(name, catalog.actions);
+        if (close.length > 0)
+            lines.push("", `Closest action to "${name}": ${close.slice(0, 3).join(", ")}`);
+        // The Generic explanation only where the name reads like one of these
+        // actions (most of its words shared): `list-all-records` against
+        // `list-records`, not `record-created` against `create-entity-record`,
+        // where it would point an event request at action ids again.
+        const wanted = new Set(name.split("-")).size;
+        if (close.length > 0 && sharedTokens(name, close[0]) * 2 > wanted) {
+            lines.push("The baked library's action id is not always the registry's key — a Generic", "op is `list-all-records` in the library and materializes per object, while", "the registry serves the un-expanded form. For an action, re-run with a registry action id.");
+        }
+        lines.push("", `All actions the registry serves for ${key}:`, ...catalog.actions.map((a) => `  ${a}`));
+    }
+    else {
+        lines.push("", `\`registry search ${key}\` lists no action for ${key} either.`);
+    }
+    lines.push("", "`registry get` and `registry search` answer from the CLI's local copy of the catalog.", "If it looks stale, refresh it first: `uip maestro flow registry pull --force`.");
     return lines.join("\n");
 }
+/**
+ * A `registry get` probe failed for a reason other than "Node not found" — an
+ * error inside the CLI, a refusal, a timeout, a reply that is not JSON. That is
+ * not evidence the node is absent, so this refusal says so and carries the
+ * CLI's own reasons instead of listing alternatives.
+ */
+export function registryGetFailedMessage(connectorKey, name, probes) {
+    return [
+        `${PREFIX}could not tell whether \`${connectorKey} ${name}\` is an action or an event: a registry`,
+        "lookup failed, which does not mean the node is absent.",
+        ...probeLines(probes),
+        "",
+        "Resolve the failure above and re-run prepare.",
+    ].join("\n");
+}
 export function noCanonicalEntryMessage(nodeType) {
     return `${PREFIX}no canonical entry for ${nodeType} (unexpected registry shape).`;
 }

package/dist/registry/prepare/pipeline.js

@@ -28,17 +28,17 @@ import { resolve } from "node:path";
 import { PACKAGE_NAME } from "../../package-name.js";
 import { afterLast } from "../compat/pystr.js";
 import { extractCanonical, isHttpPassthrough, nodeOf } from "../library-build/canonical.js";
-import { createBuildContext, isResourcesList, registryGet } from "../library-build/context.js";
+import { createBuildContext, isResourcesList, registryProbe } from "../library-build/context.js";
 import { enrichEntry } from "../library-build/enrich.js";
 import { expandGenericForConnector, genericTemplatesByOp } from "../library-build/generic-expand.js";
 import { planLibrary } from "../library-build/plan.js";
 import { MemoryResponseCache } from "../uip/response-cache.js";
-import { registryActions } from "./actions.js";
+import { registryCatalog } from "./actions.js";
 import { discoverConnection, lookupConnection, mergeBindings, restoreBindings, snapshotBindings, } 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, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, tsNote, unresolvedActionMessage, } from "./messages.js";
+import { PREPARE_COMMAND, PrepareRefusal, bindingsLine, candidateLabel, connectionLine, generatedModulesLine, genericActionNeedsObjectMessage, inputFieldNote, keptSchemaMessage, lookupVocabularyLines, missingGenericSchemaMessage, missingParentsNote, nextLine, noCanonicalEntryMessage, objectFlagsOnlyForGenericMessage, objectNoteLine, objectRecordedLine, parentFieldNamesMismatchMessage, parentOnlyMessage, prefixed, preparedSummaryLine, rejectedParentFieldsMessage, rerunAgainstLine, resolvedParentsNote, registryGetFailedMessage, tsNote, 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";
@@ -207,8 +207,8 @@ async function prepareOnConnection(options, ports, connected) {
     const { connectionId, bound, rollback } = connected;
     const ctx = createBuildContext({ client: ports.client, caches: ports.caches ?? memoryCaches(), reporter: ports.reporter, concurrency: 1, timeoutMs: ports.timeoutMs }, { connectionId, parentFields });
     const nodeType = `uipath.connector.${connectorKey}.${action}`;
-    const cacheName = await registryGet(ctx, nodeType, true);
-    if (cacheName === undefined) {
+    const actionProbe = await registryProbe(ctx, nodeType);
+    if ("miss" in actionProbe) {
         // Not an activity. Connector EVENTS live one namespace over, and their
         // registry definition only answers with a connection, which this command
         // has by now. Same loop, different twin pair.
@@ -230,13 +230,19 @@ async function prepareOnConnection(options, ports, connected) {
             bindings: rollback,
             prepareCommand: command,
         });
-        if (event !== undefined) {
+        if (!("missed" in event)) {
             return { kind: "event", nodeType: event.eventNodeType, connectionId, bound, objectName: event.objectName };
         }
-        const actions = await registryActions(ports.client, connectorKey, ports.timeoutMs);
-        throw new PrepareRefusal(unresolvedActionMessage(connectorKey, action, nodeType, actions), "ACTION_UNKNOWN");
+        const probes = [actionProbe.miss, event.missed];
+        // Only the CLI's "Node not found" says a node is absent. Any other failure
+        // of either lookup is reported as the failure it is, never as a verdict.
+        if (probes.some((probe) => !probe.notFound)) {
+            throw new PrepareRefusal(registryGetFailedMessage(connectorKey, action, probes), "REGISTRY_GET_FAILED");
+        }
+        const catalog = await registryCatalog(ports.client, connectorKey, ports.timeoutMs);
+        throw new PrepareRefusal(unresolvedOperationMessage({ connectorKey, name: action, probes, catalog }), "OPERATION_UNKNOWN");
     }
-    const payload = ctx.caches.registry.read(cacheName);
+    const payload = ctx.caches.registry.read(actionProbe.name);
     // The registry's own declaration of parent inputs, read from the same reply.
     const declared = declaredParents(payload);
     let entry = extractCanonical(nodeOf(payload));

package/dist/registry/prepare/resolve.js

@@ -22,6 +22,7 @@ import { pyFloatRepr } from "../codecs/pyjson.js";
 import { pyStrip, pyStripChars, splitOnce } from "../compat/pystr.js";
 import { Refusal } from "../errors.js";
 import { isResourcesRunList } from "../uip/commands.js";
+import { failureReason } from "../uip/envelope.js";
 import { isPlainObject, notJsonReason, pyOr, pyRepr, pyStrAny, pyTruthy } from "./support.js";
 /**
  * A scan has to stop somewhere, and the caps must be set against the MEASURED
@@ -361,7 +362,7 @@ export function parseListingDocument(text) {
 export async function listPage(client, connectorKey, collection, connectionId, query) {
     const result = await client.run(isResourcesRunList(connectorKey, collection, connectionId, query));
     if (result.code !== 0) {
-        throw new ResolutionRefusal(`listing ${collection} failed: ${pyStrip(result.stderr) || "no output"}`, "RESOLVE_LISTING_FAILED");
+        throw new ResolutionRefusal(`listing ${collection} failed: ${failureReason(result)}`, "RESOLVE_LISTING_FAILED");
     }
     const envelope = parseListingDocument(result.stdout);
     if (!isPlainObject(envelope)) {