@slashfi/agents-sdk 0.30.1 → 0.31.0-pr.dev.4fd2a3c

package/src/registry-consumer.ts

@@ -37,6 +37,8 @@ import type {
   ResolvedRef,
   ResolvedRegistry,
 } from "./define-config.js";
+import type { CallAgentRequest } from "./call-agent-schema.js";
+import type { SecuritySchemeSummary } from "./types.js";
 import {
   isSecretUri,
   normalizeRef,
@@ -121,6 +123,60 @@ async function resolveTemplates<T>(
   return obj;
 }
 
+// ============================================
+// Registry Auth Headers
+// ============================================
+
+/**
+ * Build auth headers for a registry based on its auth config and custom headers.
+ * Merges typed auth (bearer, api-key) with arbitrary custom headers.
+ */
+function buildRegistryAuthHeaders(
+  registry: ResolvedRegistry,
+  fallbackToken?: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  // Apply typed auth
+  switch (registry.auth.type) {
+    case "bearer": {
+      const token = ("token" in registry.auth ? registry.auth.token : undefined) ?? fallbackToken;
+      if (token) {
+        headers.Authorization = `Bearer ${token}`;
+      }
+      break;
+    }
+    case "api-key": {
+      if ("key" in registry.auth && registry.auth.key) {
+        const headerName = ("header" in registry.auth ? registry.auth.header : undefined) ?? "x-api-key";
+        headers[headerName] = registry.auth.key;
+      }
+      break;
+    }
+    case "jwt": {
+      // JWT auth would require token exchange — not yet implemented
+      if (fallbackToken) {
+        headers.Authorization = `Bearer ${fallbackToken}`;
+      }
+      break;
+    }
+    case "none":
+    default: {
+      if (fallbackToken) {
+        headers.Authorization = `Bearer ${fallbackToken}`;
+      }
+      break;
+    }
+  }
+
+  // Merge custom headers (these override auth-generated headers)
+  if (registry.headers) {
+    Object.assign(headers, registry.headers);
+  }
+
+  return headers;
+}
+
 // ============================================
 // Registry Discovery Types
 // ============================================
@@ -152,6 +208,14 @@ export interface AgentListing {
   }>;
   /** Whether it requires auth */
   requiresAuth?: boolean;
+  /** Security scheme summary (machine-readable auth type) */
+  security?: SecuritySchemeSummary;
+  /** Available resources (e.g., AUTH.md) */
+  resources?: Array<{
+    uri: string;
+    name?: string;
+    mimeType?: string;
+  }>;
   /** Integration config if applicable */
   integration?: {
     provider: string;
@@ -441,6 +505,15 @@ export interface RegistryConsumer {
   /** Discover a registry's configuration */
   discover(registryUrl: string): Promise<RegistryConfiguration>;
 
+  /** Browse agents from a specific registry (or all if url omitted) */
+  browse(registryUrl?: string): Promise<AgentListing[]>;
+
+  /** Inspect a specific agent — returns tools, auth requirements, resources */
+  inspect(
+    agentPath: string,
+    registryUrl?: string,
+  ): Promise<AgentListing | null>;
+
   /** Resolve a secret URL to its value */
   resolveSecret(url: string): Promise<string>;
 
@@ -481,12 +554,15 @@ export async function createRegistryConsumer(
   const discoveryCache = new Map<string, RegistryConfiguration>();
 
   // Discover a registry
-  async function discover(registryUrl: string): Promise<RegistryConfiguration> {
+  async function discover(registryUrl: string, registry?: ResolvedRegistry): Promise<RegistryConfiguration> {
     const cached = discoveryCache.get(registryUrl);
     if (cached) return cached;
 
     const url = `${registryUrl.replace(/\/$/, "")}/.well-known/configuration`;
-    const res = await fetchFn(url);
+    const headers: Record<string, string> = registry
+      ? buildRegistryAuthHeaders(registry, options.token)
+      : (options.token ? { Authorization: `Bearer ${options.token}` } : {});
+    const res = await fetchFn(url, { headers });
     if (!res.ok) {
       throw new Error(
         `Failed to discover registry ${registryUrl}: ${res.status}`,
@@ -501,17 +577,12 @@ export async function createRegistryConsumer(
   async function listFromRegistry(
     registry: ResolvedRegistry,
   ): Promise<AgentListing[]> {
-    const configuration = await discover(registry.url);
+    const configuration = await discover(registry.url, registry);
     const listUrl =
       configuration.agents_endpoint ??
       `${registry.url.replace(/\/$/, "")}/list`;
 
-    const headers: Record<string, string> = {};
-    if (registry.auth.type === "bearer" && "token" in registry.auth) {
-      headers.Authorization = `Bearer ${registry.auth.token}`;
-    } else if (options.token) {
-      headers.Authorization = `Bearer ${options.token}`;
-    }
+    const headers = buildRegistryAuthHeaders(registry, options.token);
 
     const res = await fetchFn(listUrl, { headers });
     if (!res.ok) {
@@ -537,26 +608,19 @@ export async function createRegistryConsumer(
     }));
   }
 
-  // Call a tool via a registry using MCP JSON-RPC (tools/call)
-  async function callTool(
+  // Send any call_agent request through a registry's MCP endpoint
+  async function callRegistry(
     registry: ResolvedRegistry,
-    agentPath: string,
-    tool: string,
-    params: Record<string, unknown>,
+    request: CallAgentRequest,
   ): Promise<unknown> {
-    const configuration = await discover(registry.url);
-    // MCP endpoint is the base URL (POST /), not /call
+    const configuration = await discover(registry.url, registry);
     const mcpUrl =
       configuration.call_endpoint ?? registry.url.replace(/\/$/, "");
 
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
+      ...buildRegistryAuthHeaders(registry, options.token),
     };
-    if (registry.auth.type === "bearer" && "token" in registry.auth) {
-      headers.Authorization = `Bearer ${registry.auth.token}`;
-    } else if (options.token) {
-      headers.Authorization = `Bearer ${options.token}`;
-    }
 
     const requestId = `call-${Date.now()}`;
     const res = await fetchFn(mcpUrl, {
@@ -568,14 +632,7 @@ export async function createRegistryConsumer(
         method: "tools/call",
         params: {
           name: "call_agent",
-          arguments: {
-            request: {
-              action: "execute_tool",
-              path: agentPath,
-              tool,
-              params,
-            },
-          },
+          arguments: { request },
         },
       }),
     });
@@ -583,7 +640,7 @@ export async function createRegistryConsumer(
     if (!res.ok) {
       const text = await res.text().catch(() => "unknown error");
       throw new Error(
-        `Tool call failed (${registry.url}/${agentPath}/${tool}): ${res.status} ${text}`,
+        `Registry call failed (${registry.url}): ${res.status} ${text}`,
       );
     }
 
@@ -599,7 +656,7 @@ export async function createRegistryConsumer(
 
     if (rpcResponse.error) {
       throw new Error(
-        `Tool call RPC error (${agentPath}/${tool}): ${rpcResponse.error.message}`,
+        `Registry RPC error: ${rpcResponse.error.message}`,
       );
     }
 
@@ -607,10 +664,10 @@ export async function createRegistryConsumer(
     if (mcpResult?.isError) {
       const errorText =
         mcpResult.content?.map((c) => c.text).join("\n") ?? "Unknown error";
-      throw new Error(`Tool call error (${agentPath}/${tool}): ${errorText}`);
+      throw new Error(`Registry call error: ${errorText}`);
     }
 
-    // Parse text content - call_agent returns JSON-stringified results
+    // Parse text content
     const textContent = mcpResult?.content?.find((c) => c.type === "text");
     if (textContent?.text) {
       try {
@@ -623,6 +680,21 @@ export async function createRegistryConsumer(
     return mcpResult;
   }
 
+  // Call a tool via a registry (convenience wrapper)
+  async function callTool(
+    registry: ResolvedRegistry,
+    agentPath: string,
+    tool: string,
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    return callRegistry(registry, {
+      action: "execute_tool",
+      path: agentPath,
+      tool,
+      params,
+    });
+  }
+
   // Build the consumer
   const consumer: RegistryConsumer = {
     async list(): Promise<AgentListing[]> {
@@ -721,7 +793,56 @@ export async function createRegistryConsumer(
       return callTool(registry, ref.ref, tool, params);
     },
 
-    discover,
+    discover(registryUrl: string) {
+      // Find matching resolved registry for auth headers
+      const registry = resolvedRegistries.find((r) => r.url === registryUrl);
+      return discover(registryUrl, registry);
+    },
+
+    async browse(registryUrl?: string): Promise<AgentListing[]> {
+      // List agents from a specific registry, or all registries if not specified
+      const targets = registryUrl
+        ? resolvedRegistries.filter(
+            (r) => r.url === registryUrl || r.name === registryUrl,
+          )
+        : resolvedRegistries;
+      const results = await Promise.allSettled(targets.map(listFromRegistry));
+      return results.flatMap((r) =>
+        r.status === "fulfilled" ? r.value : [],
+      );
+    },
+
+    async inspect(
+      agentPath: string,
+      registryUrl?: string,
+    ): Promise<AgentListing | null> {
+      const targetRegistries = registryUrl
+        ? resolvedRegistries.filter((r) => r.url === registryUrl || r.name === registryUrl)
+        : resolvedRegistries;
+
+      // Parallel O(1) lookups via describe_tools
+      const results = await Promise.allSettled(
+        targetRegistries.map(async (registry) => {
+          const data = (await callRegistry(registry, {
+            action: "describe_tools",
+            path: agentPath,
+            tools: [],
+          })) as { tools?: unknown[]; description?: string } | null;
+          if (!data) return null;
+          return {
+            path: agentPath,
+            publisher: registry.publisher,
+            tools: data.tools,
+            description: data.description,
+          } as AgentListing;
+        }),
+      );
+
+      for (const r of results) {
+        if (r.status === "fulfilled" && r.value) return r.value;
+      }
+      return null;
+    },
 
     async resolveSecret(url: string): Promise<string> {
       return resolveSecretFn(url, { token: options.token });

package/src/registry.ts

@@ -17,6 +17,8 @@ import type {
   CallAgentExecuteToolResponse,
   CallAgentLoadRequest,
   CallAgentLoadResponse,
+  CallAgentListResourcesResponse,
+  CallAgentReadResourcesResponse,
   CallAgentRequest,
   CallAgentResponse,
   ToolContext,
@@ -31,6 +33,8 @@ const DEFAULT_SUPPORTED_ACTIONS: AgentAction[] = [
   "execute_tool",
   "describe_tools",
   "load",
+  "list_resources",
+  "read_resources",
 ];
 
 // ============================================
@@ -729,6 +733,41 @@ export function createAgentRegistry(
           return defaultLoad(agent, request);
         }
 
+        case "list_resources": {
+          const resources = (agent.config?.resources ?? []).map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            mimeType: r.mimeType,
+          }));
+          return {
+            success: true,
+            agentPath: agent.path,
+            resources,
+          } as CallAgentListResourcesResponse;
+        }
+
+        case "read_resources": {
+          const uris = request.uris;
+          const agentResources = agent.config?.resources ?? [];
+          const results = uris.map((uri) => {
+            const resource = agentResources.find((r) => r.uri === uri);
+            if (!resource) {
+              return { uri, error: `Resource not found: ${uri}` };
+            }
+            return {
+              uri: resource.uri,
+              name: resource.name,
+              mimeType: resource.mimeType,
+              content: resource.content,
+            };
+          });
+          return {
+            success: true,
+            agentPath: agent.path,
+            resources: results,
+          } as CallAgentReadResourcesResponse;
+        }
+
         default: {
           // TypeScript exhaustiveness check
           const _exhaustive: never = request;

package/src/server.ts

@@ -120,6 +120,28 @@ export interface AgentServerOptions {
   keyStore?: import("./key-manager.js").KeyStore;
   /** OIDC provider for user sign-in (authorization code flow) */
   oidcProvider?: OIDCProviderConfig;
+  /**
+   * Custom auth resolver — called before the built-in JWT/header auth.
+   * Return a ResolvedAuth to authenticate the request, or null to fall
+   * through to the default auth chain.
+   *
+   * Use this when the server is mounted behind a proxy or middleware
+   * that handles its own auth (e.g., API key validation).
+   *
+   * @example
+   * ```typescript
+   * createAgentServer(registry, {
+   *   resolveAuth: async (req) => {
+   *     const apiKey = req.headers.get('x-api-key');
+   *     if (apiKey === process.env.API_KEY) {
+   *       return { callerId: 'api-client', callerType: 'system', scopes: ['*'], claims: {} };
+   *     }
+   *     return null;
+   *   },
+   * });
+   * ```
+   */
+  resolveAuth?: (req: Request) => Promise<ResolvedAuth | null>;
   /**
    * Registry capabilities — advertised in MCP initialize response.
    * When set, this server identifies as an agent registry (superset of MCP).
@@ -454,7 +476,7 @@ function getToolDefinitions() {
     {
       name: "call_agent",
       description:
-        "Execute a tool on a registered agent. Provide the agent path and tool name.",
+        "Execute a tool on a registered agent. Provide the agent path and tool name.\n\nSupported actions:\n- invoke: Fire-and-forget agent invocation\n- ask: Invoke and wait for response\n- execute_tool: Call a specific tool on an agent\n- describe_tools: Get tool schemas for an agent\n- load: Get agent definition/system prompt\n- list_resources: List all resources available on an agent (docs, auth instructions, config schemas, etc.)\n- read_resources: Fetch one or more resources by URI",
       inputSchema: callAgentInputSchema,
     },
     {
@@ -647,6 +669,14 @@ export function createAgentServer(
             description: agent.config?.description,
             supportedActions: agent.config?.supportedActions,
             integration: agent.config?.integration || null,
+            security: agent.config?.security
+              ? { type: agent.config.security.type }
+              : undefined,
+            resources: agent.config?.resources?.map((r) => ({
+              uri: r.uri,
+              name: r.name,
+              mimeType: r.mimeType,
+            })),
             tools: agent.tools
               .filter((t) => {
                 const tv = t.visibility ?? "internal";
@@ -1024,11 +1054,16 @@ export function createAgentServer(
         return new Response(null, { status: 204, headers: corsHeaders() });
       }
 
-      // Resolve auth for all requests
-      const auth = await resolveAuth(req, authConfig, {
-        signingKeys: serverSigningKeys,
-        trustedIssuers: configTrustedIssuers,
-      });
+      // Resolve auth: custom resolver first, then built-in JWT/header chain
+      const customAuth = options.resolveAuth
+        ? await options.resolveAuth(req)
+        : null;
+      const auth =
+        customAuth ??
+        (await resolveAuth(req, authConfig, {
+          signingKeys: serverSigningKeys,
+          trustedIssuers: configTrustedIssuers,
+        }));
 
       // Also check header-based identity (for proxied requests)
       const headerAuth: ResolvedAuth | null = !auth
@@ -1231,9 +1266,12 @@ export function createAgentServer(
       // Public registries (e.g. registry.slash.com) skip this entirely.
       if (
         path === "/.well-known/oauth-authorization-server" &&
-        req.method === "GET" &&
-        (options.registry?.oauthCallbackUrl || serverSigningKeys.length > 0)
+        req.method === "GET"
       ) {
+        if (!(options.registry?.oauthCallbackUrl || serverSigningKeys.length > 0)) {
+          const res = new Response("Not Found", { status: 404 });
+          return cors ? addCors(res) : res;
+        }
         const baseUrl = resolveBaseUrl(req);
         const res = jsonResponse({
           issuer: baseUrl,
@@ -1581,10 +1619,16 @@ export function createAgentServer(
     },
 
     async resolveAuth(req: Request): Promise<ResolvedAuth | null> {
-      return resolveAuth(req, authConfig, {
-        signingKeys: serverSigningKeys,
-        trustedIssuers: configTrustedIssuers,
-      });
+      const customAuth = options.resolveAuth
+        ? await options.resolveAuth(req)
+        : null;
+      return (
+        customAuth ??
+        resolveAuth(req, authConfig, {
+          signingKeys: serverSigningKeys,
+          trustedIssuers: configTrustedIssuers,
+        })
+      );
     },
 
     addTrustedIssuer(issuerUrl: string, scopes?: string[]): void {

package/src/types.ts

@@ -259,6 +259,32 @@ export type SecurityScheme =
   | HttpSecurityScheme
   | NoneSecurityScheme;
 
+/**
+ * Lightweight security summary for agent listings.
+ * The full SecurityScheme has all the details; this is the
+ * directory-level overview (e.g., in list_agents responses).
+ */
+export interface SecuritySchemeSummary {
+  type: SecurityScheme['type'];
+  [key: string]: unknown;
+}
+
+/**
+ * A static resource exposed by an agent.
+ * Well-known resources:
+ * - `AUTH.md` — LLM-readable auth/connection setup instructions
+ */
+export interface AgentResource {
+  /** Resource URI (e.g., 'AUTH.md') */
+  uri: string;
+  /** Human-readable name */
+  name?: string;
+  /** MIME type (defaults to text/markdown for .md) */
+  mimeType?: string;
+  /** The resource content (populated on read_resources, omitted on list) */
+  content?: string;
+}
+
 // ============================================
 // Agent Configuration
 // ============================================
@@ -313,6 +339,13 @@ export interface AgentConfig {
    */
   security?: SecurityScheme;
 
+  /**
+   * Agent resources — static files/documents the agent exposes.
+   * Well-known resources:
+   * - `AUTH.md` — LLM-readable auth setup instructions
+   */
+  resources?: AgentResource[];
+
   /** Additional configuration */
   /** Agent refs (paths to other agents this agent can call) */
   refs?: Record<string, { description?: string }>;
@@ -747,6 +780,30 @@ export interface CallAgentCallbackResponse {
   callbackId: string;
 }
 
+/** List resources response */
+export interface CallAgentListResourcesResponse {
+  success: true;
+  agentPath: string;
+  resources: Array<{
+    uri: string;
+    name?: string;
+    mimeType?: string;
+  }>;
+}
+
+/** Read resources response */
+export interface CallAgentReadResourcesResponse {
+  success: true;
+  agentPath: string;
+  resources: Array<{
+    uri: string;
+    name?: string;
+    mimeType?: string;
+    content?: string;
+    error?: string;
+  }>;
+}
+
 /** Error response */
 export interface CallAgentErrorResponse {
   success: false;
@@ -762,4 +819,6 @@ export type CallAgentResponse =
   | CallAgentDescribeToolsResponse
   | CallAgentLoadResponse
   | CallAgentCallbackResponse
+  | CallAgentListResourcesResponse
+  | CallAgentReadResourcesResponse
   | CallAgentErrorResponse;