@slashfi/agents-sdk 0.75.0 → 0.76.0

package/src/define-config.ts

@@ -34,6 +34,30 @@ 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;
+}
+
 /** A registry endpoint the consumer connects to */
 export interface RegistryEntry {
   /** Registry URL (e.g., 'https://registry.slash.com') */
@@ -53,6 +77,13 @@ 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;
 }
 
 // ============================================
@@ -100,35 +131,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/registry-consumer.ts

@@ -207,6 +207,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. */
@@ -472,17 +482,34 @@ 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 }),
   };
 }
 

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,
+                    }),
+                  },
+                }),
               },
             }),
           },