@slashfi/agents-sdk 0.76.0 → 0.77.0

package/src/define-config.ts

@@ -58,6 +58,49 @@ export interface RegistryProxy {
   agent?: string;
 }
 
+/**
+ * OAuth state captured after `adk registry auth` completes a dynamic-client
+ * registration + authorization-code flow against a registry. Stored alongside
+ * `auth.token` so the access token can be refreshed without re-prompting the
+ * user. The `auth.token` slot holds the current access token; everything
+ * needed to refresh it lives here.
+ */
+export interface RegistryOAuthState {
+  /** Token endpoint used for code exchange / refresh. */
+  tokenEndpoint: string;
+  /** Client ID issued by dynamic client registration (RFC 7591). */
+  clientId: string;
+  /** Client secret from dynamic registration, when the server issued one. */
+  clientSecret?: string;
+  /** Refresh token returned by the token endpoint, if any. */
+  refreshToken?: string;
+  /** Absolute expiry (ISO 8601) derived from `expires_in` at exchange time. */
+  expiresAt?: string;
+  /** Scopes the access token was granted for. */
+  scopes?: string[];
+}
+
+/**
+ * Captured auth challenge from a registry that rejected an unauthenticated
+ * probe (RFC 6750 `WWW-Authenticate` + RFC 9728 protected-resource metadata).
+ * When present on a `RegistryEntry`, the registry has been seen to require
+ * credentials and ref ops will fail until `adk registry auth` is run.
+ */
+export interface RegistryAuthRequirement {
+  /** Auth scheme advertised in `WWW-Authenticate` (e.g. `Bearer`). */
+  scheme?: string;
+  /** Realm advertised in `WWW-Authenticate`. */
+  realm?: string;
+  /** RFC 9728 `resource_metadata` URL parsed from the challenge. */
+  resourceMetadataUrl?: string;
+  /** Authorization servers from the protected-resource metadata. */
+  authorizationServers?: string[];
+  /** Scopes supported by the resource. */
+  scopes?: string[];
+  /** Bearer-methods advertised by the resource (`header`, `body`, `query`). */
+  bearerMethodsSupported?: string[];
+}
+
 /** A registry endpoint the consumer connects to */
 export interface RegistryEntry {
   /** Registry URL (e.g., 'https://registry.slash.com') */
@@ -84,6 +127,21 @@ export interface RegistryEntry {
    * running locally. See {@link RegistryProxy}.
    */
   proxy?: RegistryProxy;
+
+  /**
+   * Populated by `adk registry add` when the probe returned 401. Cleared
+   * by `adk registry auth`. Registry ops refuse to run while this is set
+   * and no usable auth credentials are configured.
+   */
+  authRequirement?: RegistryAuthRequirement;
+
+  /**
+   * OAuth lifecycle state — refresh token, client credentials from dynamic
+   * registration, token endpoint, expiry. Populated by `adk registry auth`
+   * when the flow went through OAuth; absent for manually-supplied bearer
+   * tokens.
+   */
+  oauth?: RegistryOAuthState;
 }
 
 // ============================================

package/src/mcp-client.ts

@@ -14,6 +14,8 @@
  */
 
 import { generatePkcePair } from "./pkce.js";
+import type { RegistryAuthRequirement } from "./define-config.js";
+import type { FetchFn } from "./fetch-types.js";
 
 // ============================================
 // Types
@@ -239,3 +241,122 @@ export async function refreshAccessToken(
     expiresIn: data.expires_in as number | undefined,
   };
 }
+
+// ============================================
+// Registry Auth Probe (RFC 6750 + RFC 9728)
+// ============================================
+
+/**
+ * Parse a `WWW-Authenticate` header of the form
+ *   `Bearer realm="x", resource_metadata="https://..."`
+ * Returns the scheme and any `key="value"` params. Tolerant of
+ * single-value headers and missing params.
+ */
+export function parseWwwAuthenticate(
+  header: string,
+): { scheme: string; params: Record<string, string> } {
+  const spaceIdx = header.indexOf(" ");
+  const scheme = (spaceIdx === -1 ? header : header.slice(0, spaceIdx)).trim();
+  const rest = spaceIdx === -1 ? "" : header.slice(spaceIdx + 1);
+  const params: Record<string, string> = {};
+  for (const match of rest.matchAll(/([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g)) {
+    params[match[1]!.toLowerCase()] = match[2]!;
+  }
+  return { scheme, params };
+}
+
+/** RFC 9728 protected-resource metadata. */
+export interface ProtectedResourceMetadata {
+  resource: string;
+  authorization_servers?: string[];
+  bearer_methods_supported?: string[];
+  scopes_supported?: string[];
+  resource_documentation?: string;
+}
+
+/** Fetch RFC 9728 metadata. Returns null on any failure. */
+export async function discoverProtectedResourceMetadata(
+  metadataUrl: string,
+  fetchFn: FetchFn = globalThis.fetch,
+): Promise<ProtectedResourceMetadata | null> {
+  try {
+    const res = await fetchFn(metadataUrl);
+    if (!res.ok) return null;
+    return (await res.json()) as ProtectedResourceMetadata;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Probe an MCP URL to see whether it requires authentication.
+ *
+ * Sends a minimal `initialize` request. On 200 the server accepts anonymous
+ * connections; on 401 we parse the `WWW-Authenticate` header and, if it
+ * points at RFC 9728 resource metadata, fetch it so the caller can record
+ * the authorization servers and scopes.
+ *
+ * Returns `{ ok: true }` when no auth is required, or
+ * `{ ok: false, requirement }` when the server challenged the request.
+ * Other failures (DNS, TLS, unexpected status) surface as `{ ok: null }`
+ * — the caller should treat those as probe-inconclusive rather than
+ * asserting auth is required.
+ */
+export async function probeRegistryAuth(
+  registryUrl: string,
+  fetchFn: FetchFn = globalThis.fetch,
+): Promise<
+  | { ok: true }
+  | { ok: false; requirement: RegistryAuthRequirement }
+  | { ok: null }
+> {
+  const url = registryUrl.replace(/\/$/, "");
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "agents-sdk-probe", version: "1.0.0" },
+        },
+      }),
+    });
+  } catch {
+    return { ok: null };
+  }
+
+  if (res.status !== 401) {
+    return res.ok ? { ok: true } : { ok: null };
+  }
+
+  const wwwAuth = res.headers.get("www-authenticate") ?? "";
+  const { scheme, params } = parseWwwAuthenticate(wwwAuth);
+  const requirement: RegistryAuthRequirement = {};
+  if (scheme) requirement.scheme = scheme;
+  if (params.realm) requirement.realm = params.realm;
+
+  const metadataUrl = params.resource_metadata;
+  if (metadataUrl) {
+    requirement.resourceMetadataUrl = metadataUrl;
+    const metadata = await discoverProtectedResourceMetadata(metadataUrl, fetchFn);
+    if (metadata) {
+      if (metadata.authorization_servers?.length) {
+        requirement.authorizationServers = metadata.authorization_servers;
+      }
+      if (metadata.scopes_supported?.length) {
+        requirement.scopes = metadata.scopes_supported;
+      }
+      if (metadata.bearer_methods_supported?.length) {
+        requirement.bearerMethodsSupported = metadata.bearer_methods_supported;
+      }
+    }
+  }
+
+  return { ok: false, requirement };
+}

package/src/registry-consumer.ts

@@ -41,6 +41,8 @@ import type {
 import type { CallAgentRequest } from "./call-agent-schema.js";
 import type { FetchFn } from "./fetch-types.js";
 import type { SecuritySchemeSummary, CallAgentResponse } from "./types.js";
+import { AdkError } from "./adk-error.js";
+import { parseWwwAuthenticate } from "./mcp-client.js";
 import {
   isSecretUri,
   normalizeRef,
@@ -391,12 +393,19 @@ async function listFromMcpServer(
         ...(params && { params }),
       }),
     });
+    if (res.status === 401) throwRegistryAuthError(serverUrl, res);
     if (!res.ok) {
-      throw new Error(`MCP call to ${serverUrl} failed: ${res.status}`);
+      const body = await res.text().catch(() => "");
+      throwRegistryCallError(serverUrl, res.status, body);
     }
     const json = (await res.json()) as { result?: unknown; error?: { message: string } };
     if (json.error) {
-      throw new Error(`MCP RPC error: ${json.error.message}`);
+      throw new AdkError({
+        code: "registry_rpc_error",
+        message: `Registry at ${serverUrl} returned an RPC error: ${json.error.message}`,
+        hint: "Check the tool name and parameters, or inspect the registry.",
+        details: { url: serverUrl, rpcError: json.error.message },
+      });
     }
     return json.result;
   }
@@ -466,12 +475,19 @@ async function discoverRegistryViaMcp(
         ...(params && { params }),
       }),
     });
+    if (res.status === 401) throwRegistryAuthError(serverUrl, res);
     if (!res.ok) {
-      throw new Error(`MCP initialize to ${serverUrl} failed: ${res.status}`);
+      const body = await res.text().catch(() => "");
+      throwRegistryCallError(serverUrl, res.status, body);
     }
     const json = (await res.json()) as { result?: unknown; error?: { message: string } };
     if (json.error) {
-      throw new Error(`MCP RPC error: ${json.error.message}`);
+      throw new AdkError({
+        code: "registry_rpc_error",
+        message: `Registry at ${serverUrl} returned an RPC error: ${json.error.message}`,
+        hint: "Check the registry URL and that the server speaks MCP.",
+        details: { url: serverUrl, rpcError: json.error.message },
+      });
     }
     return json.result;
   }
@@ -513,6 +529,45 @@ async function discoverRegistryViaMcp(
   };
 }
 
+/**
+ * Throw a typed auth error with context parsed from the challenge. Used when
+ * any MCP call returns 401, so callers see a friendly message pointing at
+ * `adk registry auth` rather than a bare "MCP call failed: 401".
+ */
+function throwRegistryAuthError(
+  serverUrl: string,
+  res: Response,
+): never {
+  const wwwAuth = res.headers.get("www-authenticate") ?? "";
+  const { scheme, params } = parseWwwAuthenticate(wwwAuth);
+  throw new AdkError({
+    code: "registry_auth_required",
+    message: `Registry at ${serverUrl} returned 401 Unauthorized.`,
+    hint: `Run: adk registry auth <name> --token <token>`,
+    details: {
+      url: serverUrl,
+      scheme,
+      realm: params.realm,
+      resourceMetadataUrl: params.resource_metadata,
+      status: 401,
+    },
+  });
+}
+
+/** Wrap a generic MCP failure (non-401) in an AdkError so CLI callers get a typed error. */
+function throwRegistryCallError(
+  serverUrl: string,
+  status: number,
+  body: string,
+): never {
+  throw new AdkError({
+    code: "registry_call_failed",
+    message: `Registry at ${serverUrl} returned ${status}.`,
+    hint: "Check the registry URL and that the server is reachable.",
+    details: { url: serverUrl, status, body: body.slice(0, 500) },
+  });
+}
+
 /**
  * Call a tool on a direct MCP server.
  */
@@ -542,12 +597,19 @@ async function callMcpTool(
       params: { name: toolName, arguments: params },
     }),
   });
+  if (res.status === 401) throwRegistryAuthError(serverUrl, res);
   if (!res.ok) {
-    throw new Error(`MCP tool call failed: ${res.status}`);
+    const body = await res.text().catch(() => "");
+    throwRegistryCallError(serverUrl, res.status, body);
   }
   const json = (await res.json()) as { result?: unknown; error?: { message: string } };
   if (json.error) {
-    throw new Error(`MCP RPC error: ${json.error.message}`);
+    throw new AdkError({
+      code: "registry_rpc_error",
+      message: `Registry at ${serverUrl} returned an RPC error: ${json.error.message}`,
+      hint: "Check the tool name and parameters, or inspect the registry.",
+      details: { url: serverUrl, rpcError: json.error.message },
+    });
   }
 
   // Extract text content
@@ -977,19 +1039,19 @@ export async function createRegistryConsumer(
     },
 
     async browse(registryUrl?: string, query?: string): Promise<AgentListEntry[]> {
-      // List agents from a specific registry, or all registries if not specified
+      // List agents from a specific registry, or all registries if not specified.
+      // Errors from any target propagate — previously allSettled silently
+      // dropped rejections (including 401s), so browsing an unreachable or
+      // unauthenticated registry returned 0 agents with no indication why.
       const targets = registryUrl
         ? resolvedRegistries.filter(
             (r) => r.url === registryUrl || r.name === registryUrl,
           )
         : resolvedRegistries;
-      // Pass query to server for BM25 search
-      const results = await Promise.allSettled(
+      const results = await Promise.all(
         targets.map((t) => listFromRegistry(t, query)),
       );
-      return results.flatMap((r) =>
-        r.status === "fulfilled" ? r.value : [],
-      );
+      return results.flat();
     },
 
     async inspect(