@slashfi/agents-sdk 0.75.0 → 0.77.0

package/src/define-config.ts

@@ -34,6 +34,73 @@ export type RegistryAuth =
   | { type: "api-key"; key?: string; header?: string }
   | { type: "jwt"; issuer?: string };
 
+/**
+ * Proxy configuration for a registry.
+ *
+ * When set, ref operations (`auth`, `auth-status`, `call`, `inspect`,
+ * `resources`, `read`, `refresh-token`) for refs sourced from this
+ * registry are forwarded to a server-side agent that implements the
+ * adk-tools surface. Use this for cloud-hosted registries that own
+ * OAuth client credentials and/or user tokens on behalf of consumers
+ * (e.g. `api.twin.slash.com/mcp`).
+ *
+ * - `mode: 'required'` — all ref ops MUST route through the proxy agent.
+ *   Local handshake (`ref.authLocal`) is refused for refs from this
+ *   registry because the local environment has no way to build an
+ *   authorize URL without the server's client credentials.
+ * - `mode: 'optional'` — proxy is the default; callers may opt out via
+ *   `{ preferLocal: true }` on a per-op basis when they already hold
+ *   local credentials.
+ */
+export interface RegistryProxy {
+  mode: 'required' | 'optional';
+  /** Agent path to forward to. Defaults to `@config`. */
+  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') */
@@ -53,6 +120,28 @@ export interface RegistryEntry {
 
   /** Connection status — set by validation/test, used to filter active entries */
   status?: 'active' | 'inactive' | 'error';
+
+  /**
+   * If set, ref ops for refs sourced from this registry are forwarded
+   * to a server-side adk-tools agent (default `@config`) instead of
+   * 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;
 }
 
 // ============================================
@@ -100,35 +189,12 @@ export type RefEntry = {
       status?: 'active' | 'inactive' | 'error';
     };
 
-// ============================================
-// Proxy Config
-// ============================================
-
-/** A proxy target — remote adk server that handles ref/registry operations */
-export interface ProxyEntry {
-  /** Human-readable name */
-  name: string;
-  /** URL of the remote server */
-  url: string;
-  /** Connection type: 'mcp' (direct MCP server) or 'registry' (agent on a registry) */
-  type: 'mcp' | 'registry';
-  /** For type 'registry': the agent path that implements adk tools (e.g. '@config') */
-  agent?: string;
-  /** Auth for connecting to the proxy */
-  auth?: RegistryAuth;
-  /** Whether this is the default proxy when no local refs/registries exist */
-  default?: boolean;
-}
-
 // ============================================
 // Consumer Config
 // ============================================
 
 /** The full consumer configuration */
 export interface ConsumerConfig {
-  /** Remote adk proxies — forward operations to a remote server */
-  proxies?: ProxyEntry[];
-
   /** Registries to connect to, in resolution order */
   registries?: (string | RegistryEntry)[];
 

package/src/index.ts

@@ -306,7 +306,6 @@ export {
 export type {
   RegistryAuth,
   RegistryEntry,
-  ProxyEntry,
   RefConfig,
   RefEntry,
   ConsumerConfig,
@@ -427,7 +426,6 @@ export { createAdk } from "./config-store.js";
 export type {
   Adk,
   AdkOptions,
-  AdkProxyApi,
   AdkRegistryApi,
   AdkRefApi,
   AdkAgentRegistry,

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,
@@ -207,6 +209,16 @@ export interface RegistryConfiguration {
   jwks_uri?: string;
   token_endpoint?: string;
   supported_grant_types?: string[];
+  /**
+   * When the registry advertises proxy support in its `initialize` response,
+   * consumers can auto-populate `RegistryEntry.proxy` at add time so ref ops
+   * forward to the server-side adk-tools agent automatically.
+   */
+  proxy?: {
+    mode: "required" | "optional";
+    /** Agent path to forward to. Defaults to '@config'. */
+    agent?: string;
+  };
 }
 
 /** Fields common to every agent reference a registry can return. */
@@ -381,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;
   }
@@ -456,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;
   }
@@ -472,20 +498,76 @@ async function discoverRegistryViaMcp(
     clientInfo: { name: "agents-sdk-consumer", version: "1.0.0" },
   })) as {
     serverInfo?: { name?: string; version?: string };
+    capabilities?: {
+      registry?: {
+        proxy?: {
+          mode?: "required" | "optional";
+          agent?: string;
+        };
+      };
+    };
   };
 
   await rpc("notifications/initialized").catch(() => {});
 
   const issuer = issuerFromMcpUrlAndServerInfo(serverUrl, initResult?.serverInfo);
 
+  const advertisedProxy = initResult?.capabilities?.registry?.proxy;
+  const proxy = advertisedProxy?.mode
+    ? {
+        mode: advertisedProxy.mode,
+        ...(advertisedProxy.agent && { agent: advertisedProxy.agent }),
+      }
+    : undefined;
+
   return {
     issuer,
     jwks_uri: `${issuer}/.well-known/jwks.json`,
     token_endpoint: `${issuer}/oauth/token`,
     supported_grant_types: ["client_credentials", "jwt_exchange"],
+    ...(proxy && { proxy }),
   };
 }
 
+/**
+ * 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.
  */
@@ -515,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
@@ -950,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(

package/src/server.ts

@@ -206,6 +206,17 @@ export interface AgentServerOptions {
     features?: string[];
     /** OAuth callback URL for shared OAuth flows */
     oauthCallbackUrl?: string;
+    /**
+     * Announce that ref operations for agents sourced from this registry
+     * should be forwarded to a server-side adk-tools agent instead of
+     * running locally. Consumers pick this up during `registry.add` and
+     * auto-populate `RegistryEntry.proxy` — no user flag needed.
+     */
+    proxy?: {
+      mode: "required" | "optional";
+      /** Agent path to forward to. Defaults to '@config'. */
+      agent?: string;
+    };
   };
   /**
    * Structured logger for server-side errors (tool-call failures, JWT
@@ -591,6 +602,14 @@ export function createAgentServer(
                 ...(options.registry.oauthCallbackUrl && {
                   oauthCallbackUrl: options.registry.oauthCallbackUrl,
                 }),
+                ...(options.registry.proxy && {
+                  proxy: {
+                    mode: options.registry.proxy.mode,
+                    ...(options.registry.proxy.agent && {
+                      agent: options.registry.proxy.agent,
+                    }),
+                  },
+                }),
               },
             }),
           },