@slashfi/agents-sdk 0.74.0 → 0.76.0

package/src/registry-consumer.ts

@@ -207,23 +207,26 @@ 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;
+  };
 }
 
-/** An agent definition as listed by a registry */
-export interface AgentListing {
+/** Fields common to every agent reference a registry can return. */
+export interface AgentBase {
   /** Agent path (e.g., '@notion') */
   path: string;
   /** Description */
   description?: string;
   /** Publisher (registry name) */
   publisher: string;
-  /** Tools available */
-  tools?: Array<{
-    name: string;
-    description?: string;
-  }>;
-  /** Whether it requires auth */
-  requiresAuth?: boolean;
   /** Security scheme summary (machine-readable auth type) */
   security?: SecuritySchemeSummary;
   /** Available resources (e.g., AUTH.md) */
@@ -232,7 +235,39 @@ export interface AgentListing {
     name?: string;
     mimeType?: string;
   }>;
-  /** Slim tool summaries (when describe_tools called without full: true) */
+}
+
+/**
+ * Lightweight agent entry returned by `list_agents` / `consumer.list()` /
+ * `consumer.browse()` / `consumer.available()`. Registries emit a `toolCount`
+ * instead of the full `tools` array to keep listings small; call `inspect()`
+ * to get the per-tool details.
+ */
+export interface AgentListEntry extends AgentBase {
+  /** Number of tools this agent exposes */
+  toolCount?: number;
+  /** Whether the agent requires auth (populated only for direct MCP/HTTPS refs) */
+  requiresAuth?: boolean;
+  /** Integration config if applicable */
+  integration?: {
+    provider: string;
+    displayName: string;
+    category?: string;
+  };
+}
+
+/**
+ * Full agent detail returned by `describe_tools` / `consumer.inspect()`.
+ * Carries the actual tool definitions (or slim summaries) and extra context
+ * the listing endpoint omits.
+ */
+export interface AgentInspection extends AgentBase {
+  /** Full tool details (returned when `full: true`) */
+  tools?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  /** Slim tool summaries (returned when `full` is not set) */
   toolSummaries?: Array<{
     name: string;
     description: string;
@@ -242,16 +277,16 @@ export interface AgentListing {
   context?: string;
   /** Upstream MCP/API URL for direct connections */
   upstream?: string;
-  /** Integration config if applicable */
-  integration?: {
-    provider: string;
-    displayName: string;
-    category?: string;
-  };
+  /** Agent mode (redirect | proxy | api) */
+  mode?: string;
 }
 
+/** @deprecated Prefer `AgentListEntry` (for listings) or `AgentInspection` (for inspect results). */
+export type AgentListing = AgentListEntry | AgentInspection;
+
 /** Raw agent entry returned by the list_agents MCP tool (before normalization). */
-type ListAgentsEntry = Omit<AgentListing, "publisher" | "tools"> & {
+type ListAgentsEntry = Omit<AgentListEntry, "publisher"> & {
+  /** Legacy field — older registries emitted `tools` instead of `toolCount`. */
   tools?: Array<{ name: string; description?: string } | string>;
 };
 
@@ -333,7 +368,7 @@ async function listFromMcpServer(
   url: string,
   auth: { token?: string; headers?: Record<string, string> },
   fetchFn: FetchFn,
-): Promise<AgentListing[]> {
+): Promise<AgentListEntry[]> {
   const serverUrl = url.replace(/\/$/, "");
 
   const headers: Record<string, string> = {
@@ -383,12 +418,13 @@ async function listFromMcpServer(
 
   const serverName = initResult?.serverInfo?.name ?? new URL(serverUrl).hostname;
 
-  // Return as a single agent listing with all tools
+  // Return as a single agent listing — toolCount keeps listings lightweight;
+  // callers that need per-tool detail should use `inspect()`.
   return [{
     path: serverName,
     description: `MCP server at ${serverUrl}`,
     publisher: serverName,
-    tools: toolsResult?.tools ?? [],
+    toolCount: toolsResult?.tools?.length ?? 0,
     requiresAuth: false,
   }];
 }
@@ -446,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 }),
   };
 }
 
@@ -517,16 +570,14 @@ async function callMcpTool(
  * Returns a single generic 'call' tool since we can't auto-discover REST endpoints
  * without an OpenAPI spec.
  */
-function listFromHttpsApi(url: string): AgentListing[] {
+function listFromHttpsApi(url: string): AgentListEntry[] {
   const hostname = new URL(url).hostname;
   return [{
     path: hostname,
     description: `REST API at ${url}`,
     publisher: hostname,
-    tools: [{
-      name: "call",
-      description: "Make an HTTP request to the API. Params: method, path, body, headers.",
-    }],
+    // Single generic `call` tool — callers can use `inspect()` for details.
+    toolCount: 1,
     requiresAuth: false,
   }];
 }
@@ -598,7 +649,7 @@ export interface RegistryConsumerOptions {
 
 export interface RegistryConsumer {
   /** List all available agents across all connected registries */
-  list(): Promise<AgentListing[]>;
+  list(): Promise<AgentListEntry[]>;
 
   /** List configured refs (from the consumer's config) */
   refs(): ResolvedRef[];
@@ -617,14 +668,14 @@ export interface RegistryConsumer {
   discover(registryUrl: string): Promise<RegistryConfiguration>;
 
   /** Browse agents from a specific registry (or all if url omitted), with optional BM25 search */
-  browse(registryUrl?: string, query?: string): Promise<AgentListing[]>;
+  browse(registryUrl?: string, query?: string): Promise<AgentListEntry[]>;
 
   /** Inspect a specific agent — returns tools, auth requirements, resources */
   inspect(
     agentPath: string,
     registryUrl?: string,
     options?: { full?: boolean },
-  ): Promise<AgentListing | null>;
+  ): Promise<AgentInspection | null>;
 
   /** Resolve a secret URL to its value */
   resolveSecret(url: string): Promise<string>;
@@ -644,7 +695,7 @@ export interface RegistryConsumer {
   index(): ResolvedConfig;
 
   /** Diff: what's available vs what's configured */
-  available(): Promise<AgentListing[]>;
+  available(): Promise<AgentListEntry[]>;
 }
 
 /**
@@ -693,7 +744,7 @@ export async function createRegistryConsumer(
   async function listFromRegistry(
     registry: ResolvedRegistry,
     query?: string,
-  ): Promise<AgentListing[]> {
+  ): Promise<AgentListEntry[]> {
     const mcpUrl = registry.url.replace(/\/$/, "");
 
     const response = await callMcpTool(
@@ -715,15 +766,15 @@ export async function createRegistryConsumer(
     ) as ListAgentsResponse;
     const agents = data.agents ?? [];
 
-    return agents.map((agent) => ({
-      ...agent,
-      ...agent,
-      // Normalize tools: strings become { name } objects
-      tools: agent.tools?.map((t) =>
-        typeof t === "string" ? { name: t } : t,
-      ),
-      publisher: registry.publisher,
-    }));
+    return agents.map((agent) => {
+      // Legacy registries may still emit `tools` instead of `toolCount`; back-fill.
+      const { tools, toolCount, ...rest } = agent;
+      return {
+        ...rest,
+        publisher: registry.publisher,
+        toolCount: toolCount ?? tools?.length,
+      };
+    });
   }
 
   // Send any call_agent request through a registry's MCP endpoint
@@ -821,7 +872,7 @@ export async function createRegistryConsumer(
 
   // Build the consumer
   const consumer: RegistryConsumer = {
-    async list(): Promise<AgentListing[]> {
+    async list(): Promise<AgentListEntry[]> {
       // Collect from standard registries
       const registryResults = await Promise.allSettled(
         resolvedRegistries.map((r) => listFromRegistry(r)),
@@ -925,7 +976,7 @@ export async function createRegistryConsumer(
       return discover(registryUrl, registry);
     },
 
-    async browse(registryUrl?: string, query?: string): Promise<AgentListing[]> {
+    async browse(registryUrl?: string, query?: string): Promise<AgentListEntry[]> {
       // List agents from a specific registry, or all registries if not specified
       const targets = registryUrl
         ? resolvedRegistries.filter(
@@ -945,7 +996,7 @@ export async function createRegistryConsumer(
       agentPath: string,
       registryUrl?: string,
       options?: { full?: boolean },
-    ): Promise<AgentListing | null> {
+    ): Promise<AgentInspection | null> {
       const targetRegistries = registryUrl
         ? resolvedRegistries.filter((r) => r.url === registryUrl || r.name === registryUrl)
         : resolvedRegistries;
@@ -988,7 +1039,7 @@ export async function createRegistryConsumer(
             context: data.context,
             ...(data.upstream && { upstream: data.upstream }),
             ...(data.mode && { mode: data.mode }),
-          } as AgentListing;
+          } as AgentInspection;
         }),
       );
 
@@ -1018,7 +1069,7 @@ export async function createRegistryConsumer(
       };
     },
 
-    async available(): Promise<AgentListing[]> {
+    async available(): Promise<AgentListEntry[]> {
       const all = await consumer.list();
       const configuredRefs = new Set(resolvedRefs.map((r) => r.ref));
       return all.filter((a) => !configuredRefs.has(a.path));

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