@slashfi/agents-sdk 0.34.1 → 0.35.0

package/src/agent-definitions/remote-registry.ts

@@ -27,9 +27,9 @@
 import { defineAgent, defineTool } from "../define.js";
 import type {
   AgentDefinition,
-  IntegrationMethodContext,
   IntegrationMethodResult,
   ToolContext,
+  ToolDefinition,
 } from "../types.js";
 import type { SecretStore } from "./secrets.js";
 
@@ -53,6 +53,39 @@ interface RegistryConnection {
 
 const ENTITY_TYPE = "remote-registry-connections";
 
+/** JSON-RPC response for MCP `tools/call` over HTTP. */
+interface McpToolsCallRpcBody {
+  result?: {
+    content?: Array<{ type: string; text?: string }>;
+  };
+  error?: { message: string };
+}
+
+interface ProxyCallToolInput {
+  registryId: string;
+  action: string;
+  path: string;
+  tool: string;
+  params?: Record<string, unknown>;
+}
+
+interface AddConnectionToolInput {
+  id: string;
+  name?: string;
+  url: string;
+  remoteTenantId?: string;
+}
+
+/** Typical fields from POST /oauth/token JSON body. */
+interface OAuthTokenJsonBody {
+  access_token?: string;
+  tenant_id?: string;
+  user_id?: string;
+  error?: string;
+  error_description?: string;
+  authorize_url?: string;
+}
+
 export function createRemoteRegistryAgent(
   options: RemoteRegistryAgentOptions,
 ): AgentDefinition {
@@ -122,7 +155,7 @@ export function createRemoteRegistryAgent(
     url: string,
     jwt: string,
     request: Record<string, unknown>,
-  ): Promise<any> {
+  ): Promise<unknown> {
     const res = await globalThis.fetch(url, {
       method: "POST",
       headers: {
@@ -136,7 +169,7 @@ export function createRemoteRegistryAgent(
         params: { name: "call_agent", arguments: { request } },
       }),
     });
-    const rpc = (await res.json()) as any;
+    const rpc = (await res.json()) as McpToolsCallRpcBody;
     const text = rpc.result?.content?.[0]?.text;
     if (!text) return rpc.result;
     const parsed = JSON.parse(text);
@@ -167,7 +200,7 @@ export function createRemoteRegistryAgent(
       tool: string;
       params?: Record<string, unknown>;
     },
-  ): Promise<any> {
+  ): Promise<unknown> {
     const conn = await loadConnection(ownerId, registryId);
     if (!conn) {
       throw new Error(
@@ -202,7 +235,7 @@ export function createRemoteRegistryAgent(
       },
       required: ["registryId", "action", "path", "tool"],
     },
-    execute: async (input: any, _ctx: ToolContext) => {
+    execute: async (input: ProxyCallToolInput, _ctx: ToolContext) => {
       return proxyCall("system", input.registryId, {
         action: input.action,
         path: input.path,
@@ -230,7 +263,7 @@ export function createRemoteRegistryAgent(
       },
       required: ["id", "url"],
     },
-    execute: async (input: any, _ctx: ToolContext) => {
+    execute: async (input: AddConnectionToolInput, _ctx: ToolContext) => {
       const conn: RegistryConnection = {
         id: input.id,
         name: input.name ?? input.id,
@@ -248,7 +281,7 @@ export function createRemoteRegistryAgent(
     description: "List all connected remote registries.",
     visibility: "public" as const,
     inputSchema: { type: "object" as const, properties: {} },
-    execute: async (_input: any, _ctx: ToolContext) => {
+    execute: async (_input: Record<string, unknown>, _ctx: ToolContext) => {
       const all = await loadAllConnections("system");
       return {
         connections: Object.values(all).map((c) => ({
@@ -264,7 +297,7 @@ export function createRemoteRegistryAgent(
   // Extract setup/connect as standalone functions to avoid circular reference
   const setupFn = async (
     params: Record<string, unknown>,
-    _ctx: IntegrationMethodContext,
+    _ctx: ToolContext,
   ): Promise<IntegrationMethodResult> => {
     console.log(
       "[remote-registry] setupFn called with:",
@@ -294,7 +327,7 @@ export function createRemoteRegistryAgent(
             redirect_uri: params.redirect_uri ?? "",
           }),
         });
-        const tokenData = (await tokenRes.json()) as any;
+        const tokenData = (await tokenRes.json()) as OAuthTokenJsonBody;
         if (!tokenData.access_token && !tokenData.tenant_id) {
           return {
             success: false,
@@ -319,23 +352,16 @@ export function createRemoteRegistryAgent(
         };
       }
 
-      // Phase 1: Discover JWKS, establish trust, then request OIDC
-      const configUrl = `${baseUrl}/.well-known/configuration`;
-      console.log("[setupFn] fetching config:", configUrl);
-      const configRes = await globalThis.fetch(configUrl);
-      console.log("[setupFn] config status:", configRes.status);
-      if (!configRes.ok)
+      // Phase 1: Verify JWKS at origin, establish trust, then request OIDC
+      const jwksUri = `${new URL(baseUrl).origin}/.well-known/jwks.json`;
+      console.log("[setupFn] fetching JWKS:", jwksUri);
+      const jwksRes = await globalThis.fetch(jwksUri);
+      console.log("[setupFn] JWKS status:", jwksRes.status);
+      if (!jwksRes.ok)
         return {
           success: false,
-          error: `Failed to discover registry at ${configUrl}`,
+          error: `JWKS not reachable at ${jwksUri}`,
         };
-      const remoteConfig = (await configRes.json()) as any;
-      if (remoteConfig.jwks_uri) {
-        console.log("[setupFn] fetching JWKS:", remoteConfig.jwks_uri);
-        const jwksRes = await globalThis.fetch(remoteConfig.jwks_uri);
-        console.log("[setupFn] JWKS status:", jwksRes.status);
-        if (!jwksRes.ok) return { success: false, error: "JWKS not reachable" };
-      }
       if (addTrustedIssuer) {
         console.log("[setupFn] adding trusted issuer:", baseUrl);
         await addTrustedIssuer(baseUrl);
@@ -361,7 +387,7 @@ export function createRemoteRegistryAgent(
         }),
       });
       console.log("[setupFn] token status:", tokenRes.status);
-      const tokenData = (await tokenRes.json()) as any;
+      const tokenData = (await tokenRes.json()) as OAuthTokenJsonBody;
       console.log(
         "[setupFn] tokenData:",
         JSON.stringify(tokenData).substring(0, 300),
@@ -414,7 +440,7 @@ export function createRemoteRegistryAgent(
 
   const connectFn = async (
     params: Record<string, unknown>,
-    ctx: IntegrationMethodContext,
+    ctx: ToolContext,
   ): Promise<IntegrationMethodResult> => {
     const registryId = params.registryId as string;
     const redirectUri = (params.redirectUri as string) ?? "";
@@ -443,7 +469,7 @@ export function createRemoteRegistryAgent(
           redirect_uri: redirectUri,
         }),
       });
-      const tokenData = (await tokenRes.json()) as any;
+      const tokenData = (await tokenRes.json()) as OAuthTokenJsonBody;
       if (tokenData.access_token)
         return {
           success: true,
@@ -498,27 +524,28 @@ export function createRemoteRegistryAgent(
       category: "infrastructure",
       description:
         "Connect to a remote agent registry via JWKS trust exchange.",
-      setup: (params, ctx) => setupFn(params, ctx as any),
-      connect: (params, ctx) => connectFn(params, ctx as any),
+      setup: (params, ctx) => setupFn(params, ctx),
+      connect: (params, ctx) => connectFn(params, ctx),
       async discover(params) {
         const url = (params.url as string) ?? "";
         try {
-          const res = await globalThis.fetch(
-            `${url.replace(/\/$/, "")}/.well-known/configuration`,
-          );
-          if (!res.ok)
+          const base = url.replace(/\/$/, "");
+          const origin = new URL(base).origin;
+          const jwksUri = `${origin}/.well-known/jwks.json`;
+          const res = await globalThis.fetch(jwksUri);
+          if (!res.ok) {
             return {
               success: false,
-              error: `No configuration endpoint at ${url}`,
+              error: `JWKS not reachable at ${jwksUri}`,
             };
-          const config = (await res.json()) as any;
+          }
           return {
             success: true,
             data: {
               url,
-              issuer: config.issuer,
-              grantTypes: config.supported_grant_types,
-              jwksUri: config.jwks_uri,
+              issuer: origin,
+              grantTypes: ["client_credentials", "jwt_exchange"],
+              jwksUri,
             },
           };
         } catch (err) {
@@ -558,6 +585,6 @@ export function createRemoteRegistryAgent(
         return { success: true, data: conn };
       },
     },
-    tools: [proxyTool, listTool, addConnectionTool] as any[],
+    tools: [proxyTool, listTool, addConnectionTool] as ToolDefinition<ToolContext>[],
   });
 }

package/src/agent-definitions/users.ts

@@ -230,6 +230,39 @@ export interface UsersAgentOptions {
   store: UserStore;
 }
 
+interface CreateUserToolInput {
+  id?: string;
+  tenantId: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  metadata?: Record<string, unknown>;
+  externalRef?: { issuer: string; userId: string };
+}
+
+interface UpdateUserToolInput {
+  userId: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface LinkIdentityToolInput {
+  userId: string;
+  provider: string;
+  providerUserId: string;
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType?: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+}
+
 export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
   const { store } = options;
 
@@ -268,7 +301,7 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
       },
       required: ["tenantId"],
     },
-    execute: async (input: any, __ctx: ToolContext) => {
+    execute: async (input: CreateUserToolInput, __ctx: ToolContext) => {
       // If externalRef provided, check if identity already exists
       if (input.externalRef) {
         const existing = await store.findIdentityByProviderUserId(
@@ -365,7 +398,7 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
       },
       required: ["userId"],
     },
-    execute: async (input: any, __ctx: ToolContext) => {
+    execute: async (input: UpdateUserToolInput, __ctx: ToolContext) => {
       const { userId, ...updates } = input;
       const user = await store.updateUser(userId, updates);
       if (!user) return { error: `User '${userId}' not found` };
@@ -416,7 +449,7 @@ export function createUsersAgent(options: UsersAgentOptions): AgentDefinition {
       },
       required: ["userId", "provider", "providerUserId"],
     },
-    execute: async (input: any, __ctx: ToolContext) => {
+    execute: async (input: LinkIdentityToolInput, __ctx: ToolContext) => {
       // Check if identity already exists
       const existing = await store.getIdentityByProvider(
         input.userId,

package/src/auth-governance.ts

@@ -39,7 +39,7 @@ export function canSeeAgent(
   agent: AgentDefinition,
   auth: ResolvedAuth | null,
 ): boolean {
-  const visibility = ((agent as any).visibility ??
+  const visibility = (agent.visibility ??
     agent.config?.visibility ??
     "internal") as Visibility;
   if (hasAdminScope(auth)) return true;
@@ -87,7 +87,7 @@ export function getVisibleTools(
   agent: AgentDefinition,
   auth: ResolvedAuth | null,
 ): typeof agent.tools {
-  const agentVisibility = ((agent as any).visibility ??
+  const agentVisibility = (agent.visibility ??
     agent.config?.visibility ??
     "internal") as Visibility;
   return agent.tools.filter((t) => canSeeTool(t, auth, agentVisibility));

package/src/call-agent-schema.test.ts

@@ -293,7 +293,10 @@ describe("zodToOpenAiJsonSchema", () => {
       required: z.string(),
       optional: z.string().optional(),
     });
-    const jsonSchema = zodToOpenAiJsonSchema(schema) as any;
+    const jsonSchema = zodToOpenAiJsonSchema(schema) as Record<
+      string,
+      unknown
+    >;
 
     // Required field should be in required array
     expect(jsonSchema.required).toContain("required");

package/src/call-agent-schema.ts

@@ -101,8 +101,7 @@ function normalizeJsonSchema(schema: Record<string, unknown>): Record<string, un
 export function zodToOpenAiJsonSchema(
   schema: ZodTypeAny,
 ): Record<string, unknown> {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const raw = zodToJsonSchema(schema as any, { target: "openAi" }) as Record<
+  const raw = zodToJsonSchema(schema, { target: "openAi" }) as Record<
     string,
     unknown
   >;
@@ -170,7 +169,9 @@ export const describeToolsActionSchema = callAgentBaseSchema.extend({
   tools: z
     .array(z.string())
     .optional()
-    .describe("Optional: filter to specific tool names. Omit to list all."),
+    .describe(
+      "Optional filter: specific tool names. Use undefined / omit for all tools; do not use [] (empty array is not 'all tools').",
+    ),
 });
 
 /** Load: get agent definition */

package/src/consumer.test.ts

@@ -70,7 +70,7 @@ describe("Registry Consumer E2E", () => {
     await server.stop();
   });
 
-  test("discover registry via .well-known/configuration", async () => {
+  test("discover registry via MCP initialize", async () => {
     const config = {
       registries: [`http://localhost:${PORT}`],
     };
@@ -80,6 +80,9 @@ describe("Registry Consumer E2E", () => {
 
     expect(discovery).toBeDefined();
     expect(discovery.issuer).toBeDefined();
+    expect(discovery.token_endpoint).toBe(
+      `http://localhost:${PORT}/oauth/token`,
+    );
   });
 
   test("list agents from registry", async () => {

package/src/define.ts

@@ -240,8 +240,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
               config: { type: "object" },
             },
           },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
     if (h.connect) {
@@ -260,8 +261,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
             },
             required: ["registryId"] as const,
           },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
     if (h.discover) {
@@ -275,8 +277,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
             type: "object" as const,
             properties: { url: { type: "string" } },
           },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
     if (h.list) {
@@ -287,8 +290,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
           description: `List connected ${h.displayName} instances.`,
           visibility: "public" as const,
           inputSchema: { type: "object" as const, properties: {} },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
     if (h.get) {
@@ -303,8 +307,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
             properties: { registryId: { type: "string" } },
             required: ["registryId"] as const,
           },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
     if (h.update) {
@@ -323,8 +328,9 @@ export function defineAgent<TContext extends ToolContext = ToolContext>(
             },
             required: ["registryId"] as const,
           },
-          execute: (input: any, ctx: any) => fn(input, ctx),
-        }) as any,
+          execute: (input: Record<string, unknown>, ctx: ToolContext) =>
+            fn(input, ctx),
+        }) as ToolDefinition<ToolContext>,
       );
     }
   }

package/src/index.ts

@@ -90,12 +90,23 @@ export type {
   SecurityScheme,
   AgentResource,
   SecuritySchemeSummary,
+  AuthClientCredentialsTokenResult,
+  AuthSecretValue,
+  ExchangeTokenLinkedSuccess,
+  ExchangeTokenNeedsIdentity,
+  ExchangeTokenRejected,
+  ExchangeTokenToolResult,
   IntegrationMethods,
   IntegrationMethodResult,
   IntegrationMethodContext,
   IntegrationHooks,
   Visibility,
 } from "./types.js";
+export {
+  isCallAgentErrorResponse,
+  isExchangeTokenLinkedSuccess,
+  isExchangeTokenNeedsIdentity,
+} from "./types.js";
 
 // Define functions
 export { defineAgent, defineTool } from "./define.js";

package/src/key-manager.ts

@@ -13,7 +13,14 @@
  * - Signs JWTs with the active key
  */
 
-import { type JWK, SignJWT, exportJWK, generateKeyPair, importJWK } from "jose";
+import {
+  type JWK,
+  type JWTPayload,
+  SignJWT,
+  exportJWK,
+  generateKeyPair,
+  importJWK,
+} from "jose";
 
 // ── Types ──
 
@@ -236,7 +243,7 @@ export async function createKeyManager(
 
     async signJwt(claims: Record<string, unknown>): Promise<string> {
       const key = getActiveKey();
-      let builder = new SignJWT({ ...claims } as any)
+      let builder = new SignJWT({ ...claims } as JWTPayload)
         .setProtectedHeader({ alg: ALG, kid: key.kid })
         .setIssuer(issuer)
         .setIssuedAt();

package/src/registry-consumer.ts

@@ -1,9 +1,10 @@
 /**
  * Registry Consumer — Connects to registries and resolves refs.
  *
- * The consumer reads a `ConsumerConfig`, discovers registries via
- * `/.well-known/configuration`, resolves refs to agent definitions,
- * and provides a unified interface for calling tools across all connected agents.
+ * The consumer reads a `ConsumerConfig`, connects to each registry at its MCP URL,
+ * resolves refs to agent definitions, and provides a unified interface for calling
+ * tools across all connected agents. Registry metadata comes from the MCP
+ * `initialize` handshake (`discover()`).
  *
  * @example
  * ```typescript
@@ -181,16 +182,15 @@ function buildRegistryAuthHeaders(
 // Registry Discovery Types
 // ============================================
 
-/** Registry well-known configuration (from /.well-known/configuration) */
+/**
+ * Registry configuration derived from the MCP `initialize` response and the registry
+ * URL (OAuth/JWKS paths follow the usual layout under `issuer`).
+ */
 export interface RegistryConfiguration {
   issuer: string;
   jwks_uri?: string;
   token_endpoint?: string;
-  agents_endpoint?: string;
-  call_endpoint?: string;
   supported_grant_types?: string[];
-  /** @deprecated Use agents_endpoint + GET /list instead */
-  agents?: string[];
 }
 
 /** An agent definition as listed by a registry */
@@ -367,6 +367,73 @@ async function listFromMcpServer(
   }];
 }
 
+function issuerFromMcpUrlAndServerInfo(
+  serverUrl: string,
+  serverInfo?: { name?: string },
+): string {
+  const name = serverInfo?.name;
+  if (name && /^https?:\/\//.test(name)) {
+    return name.replace(/\/$/, "");
+  }
+  return new URL(serverUrl).origin;
+}
+
+/**
+ * Load registry OAuth-facing metadata via MCP initialize (same URL as tools/call).
+ */
+async function discoverRegistryViaMcp(
+  registryUrl: string,
+  authHeaders: Record<string, string>,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RegistryConfiguration> {
+  const serverUrl = registryUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...authHeaders,
+  };
+
+  let reqId = 0;
+  async function rpc(method: string, params?: Record<string, unknown>) {
+    const res = await fetchFn(serverUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++reqId,
+        method,
+        ...(params && { params }),
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`MCP initialize to ${serverUrl} failed: ${res.status}`);
+    }
+    const json = (await res.json()) as { result?: unknown; error?: { message: string } };
+    if (json.error) {
+      throw new Error(`MCP RPC error: ${json.error.message}`);
+    }
+    return json.result;
+  }
+
+  const initResult = (await rpc("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "agents-sdk-consumer", version: "1.0.0" },
+  })) as {
+    serverInfo?: { name?: string; version?: string };
+  };
+
+  await rpc("notifications/initialized").catch(() => {});
+
+  const issuer = issuerFromMcpUrlAndServerInfo(serverUrl, initResult?.serverInfo);
+
+  return {
+    issuer,
+    jwks_uri: `${issuer}/.well-known/jwks.json`,
+    token_endpoint: `${issuer}/oauth/token`,
+    supported_grant_types: ["client_credentials", "jwt_exchange"],
+  };
+}
+
 /**
  * Call a tool on a direct MCP server.
  */
@@ -571,17 +638,15 @@ export async function createRegistryConsumer(
     const cached = discoveryCache.get(registryUrl);
     if (cached) return cached;
 
-    const url = `${registryUrl.replace(/\/$/, "")}/.well-known/configuration`;
-    const headers: Record<string, string> = registry
+    const authHeaders = 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}`,
-      );
-    }
-    const configuration = (await res.json()) as RegistryConfiguration;
+
+    const configuration = await discoverRegistryViaMcp(
+      registryUrl,
+      authHeaders,
+      fetchFn,
+    );
     discoveryCache.set(registryUrl, configuration);
     return configuration;
   }
@@ -591,9 +656,7 @@ export async function createRegistryConsumer(
     registry: ResolvedRegistry,
     query?: string,
   ): Promise<AgentListing[]> {
-    const configuration = await discover(registry.url, registry);
-    const mcpUrl =
-      configuration.call_endpoint ?? registry.url.replace(/\/$/, "");
+    const mcpUrl = registry.url.replace(/\/$/, "");
 
     const response = await callMcpTool(
       mcpUrl,
@@ -624,9 +687,7 @@ export async function createRegistryConsumer(
     registry: ResolvedRegistry,
     request: CallAgentRequest,
   ): Promise<unknown> {
-    const configuration = await discover(registry.url, registry);
-    const mcpUrl =
-      configuration.call_endpoint ?? registry.url.replace(/\/$/, "");
+    const mcpUrl = registry.url.replace(/\/$/, "");
 
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
@@ -840,7 +901,7 @@ export async function createRegistryConsumer(
           const data = (await callRegistry(registry, {
             action: "describe_tools",
             path: agentPath,
-            tools: [],
+            tools: undefined,
           })) as { tools?: unknown[]; description?: string } | null;
           if (!data) return null;
           return {

package/src/registry.ts

@@ -707,7 +707,9 @@ export function createAgentRegistry(
               ),
             )
             .filter((t: ToolDefinition) =>
-              request.tools ? request.tools.includes(t.name) : true,
+              request.tools && request.tools.length > 0
+                ? request.tools.includes(t.name)
+                : true,
             )
             .map((t: ToolDefinition) => ({
               name: t.name,