@slashfi/agents-sdk 0.83.0 → 0.85.0

package/src/config-store.ts

@@ -1841,8 +1841,15 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         } else {
           throw new AdkError({
             code: "REF_INVALID",
-            message: `Cannot add ref "${entry.ref}": could not determine connection type`,
-            hint: "Use --registry <name> to install from a registry, or --url <url> for a direct connection",
+            message:
+              `Cannot add ref "${entry.ref}": could not determine connection type. ` +
+              `Provide one of:\n` +
+              `  - sourceRegistry: { url: <registry URL>, agentPath?: <agent path on that registry> }  (registry-backed ref)\n` +
+              `  - url: "https://..."                                                                  (direct https/mcp ref)\n` +
+              `For registry-backed refs, run \`registry list\` to find available registry URLs.`,
+            hint:
+              "CLI: pass --registry <name> or --url <url>. " +
+              "Tool input: pass `sourceRegistry: { url, agentPath }` or `url: 'https://...'`.",
             details: { ref: entry.ref },
           });
         }
@@ -1852,18 +1859,42 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       if (entry.scheme === "registry" && !entry.sourceRegistry?.url) {
         throw new AdkError({
           code: "REF_INVALID",
-          message: `Cannot add ref "${entry.ref}": registry scheme requires a source registry`,
-          hint: "Use --registry <name> (e.g. adk ref add notion --registry public)",
-          details: { ref: entry.ref, scheme: entry.scheme },
+          message:
+            `Cannot add ref "${entry.ref}": scheme="registry" requires sourceRegistry.url. ` +
+            `Required shape:\n` +
+            `  {\n` +
+            `    operation: "add",\n` +
+            `    ref: "${entry.ref}",\n` +
+            `    scheme: "registry",\n` +
+            `    sourceRegistry: { url: <registry URL>, agentPath?: <agent path on that registry> }\n` +
+            `  }\n` +
+            `Run \`registry list\` to find the URL of a registered registry by name.`,
+          hint:
+            "CLI: adk ref add <ref> --registry <name>. " +
+            "Tool input: pass sourceRegistry.url alongside agentPath (auto-resolution by registry name only happens when calling addRef() directly with a `registry` field, not via the @config tool).",
+          details: {
+            ref: entry.ref,
+            scheme: entry.scheme,
+            received: { sourceRegistry: entry.sourceRegistry },
+            requiredShape: {
+              sourceRegistry: { url: "<registry URL>", agentPath: "<optional agent path>" },
+            },
+          },
         });
       }
 
       if ((entry.scheme === "mcp" || entry.scheme === "https") && !entry.url) {
         throw new AdkError({
           code: "REF_INVALID",
-          message: `Cannot add ref "${entry.ref}": scheme '${entry.scheme}' requires url`,
-          hint: "Provide the direct agent URL with: url: 'https://...'",
-          details: { ref: entry.ref, scheme: entry.scheme },
+          message:
+            `Cannot add ref "${entry.ref}": scheme="${entry.scheme}" requires url. ` +
+            `Required shape: { operation: "add", ref: "${entry.ref}", scheme: "${entry.scheme}", url: "https://..." }`,
+          hint: "Provide the direct agent URL with `url: 'https://...'`.",
+          details: {
+            ref: entry.ref,
+            scheme: entry.scheme,
+            requiredShape: { url: "<agent URL>" },
+          },
         });
       }
 
@@ -1872,7 +1903,13 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         try {
           const consumer = await buildConsumerForRef(entry);
           const agentToInspect = entry.sourceRegistry?.agentPath ?? entry.ref;
-          const info = await consumer.inspect(agentToInspect);
+          // Same multi-registry hazard as authStatus — target the ref's
+          // own sourceRegistry so an unrelated registry can't shadow the
+          // real lookup with an empty/error response.
+          const info = await consumer.inspect(
+            agentToInspect,
+            entry.sourceRegistry?.url,
+          );
 
           const requiresValidation = !!entry.sourceRegistry;
           if (requiresValidation) {
@@ -2155,8 +2192,15 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       let security: SecuritySchemeSummary | null = null;
       try {
         const consumer = await buildConsumerForRef(entry);
+        // Pass `sourceRegistry.url` so inspect targets the registry the ref
+        // came from. Without this, multi-registry consumers race every
+        // configured registry and the first fulfilled response wins —
+        // including {success:false} bodies from unrelated registries that
+        // don't host this agent — which silently nulls out `security` and
+        // makes `auth()` short-circuit to {type:"none", complete:true}.
         const info = await consumer.inspect(
           entry.sourceRegistry?.agentPath ?? entry.ref,
+          entry.sourceRegistry?.url,
         );
         if (info?.security) security = info.security;
       } catch {

package/src/registry-consumer.ts

@@ -1047,6 +1047,12 @@ export async function createRegistryConsumer(
           })) as unknown as Record<string, unknown> | null;
           if (!raw) return null;
 
+          // `callRegistry` returns {success:false, ...} for upstream 401s
+          // (and other recoverable failures) instead of throwing — treat
+          // these as "this registry doesn't host the agent" so the next
+          // registry gets a chance to answer.
+          if (raw.success === false) return null;
+
           // Some endpoints (e.g. twin MCP) wrap the response in { success, result },
           // while registries return fields flat. Unwrap if needed.
           const data = (
@@ -1063,6 +1069,15 @@ export async function createRegistryConsumer(
             upstream?: string;
             mode?: string;
           };
+
+          // Skip "agent not found" responses (no tools AND no description)
+          // so they don't shadow a registry that actually hosts the agent.
+          const hasContent =
+            (data.tools && data.tools.length > 0) ||
+            (data.toolSummaries && data.toolSummaries.length > 0) ||
+            !!data.description;
+          if (!hasContent) return null;
+
           return {
             path: agentPath,
             publisher: registry.publisher,