@slashfi/agents-sdk 0.34.1 → 0.36.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/events.ts

@@ -10,7 +10,7 @@
  * Filtering happens in the callback, not the API.
  */
 
-import type { CallAgentRequest, CallAgentResponse } from "./types.js";
+import type { AgentDefinition, CallAgentRequest, CallAgentResponse } from "./types.js";
 // =============================================================================
 // Event Types
 // =============================================================================
@@ -24,7 +24,8 @@ export type SystemEventType =
   | "tool/error"
   | "step"
   | "invoke"
-  | "call";
+  | "tools/call/call_agent"
+  | "tools/call/list_agents";
 
 /**
  * Augmentable map for custom event types. Consumers extend this
@@ -124,12 +125,28 @@ export interface InvokeEvent extends BaseEvent {
 }
 
 /**
- * Event emitted when a call_agent request is received.
- * Call `resolve(response)` to short-circuit the default handler.
- * If no listener resolves, the default call handler runs.
+ * Event emitted when the `call_agent` MCP tool is invoked.
+ * Replaces the legacy `call` event with a namespaced type.
+ *
+ * Call `next()` to run the default call handler (optionally with a modified request).
+ * Call `resolve(response)` to short-circuit with a custom response.
+ * If neither is called, the default handler runs.
+ *
+ * @example
+ * ```ts
+ * registry.on('tools/call/call_agent', async (event) => {
+ *   // Proxy to a remote registry
+ *   if (isRemoteAgent(event.request.path)) {
+ *     const result = await proxyToRemote(event.request);
+ *     event.resolve(result);
+ *     return;
+ *   }
+ *   // Fall through to default handler
+ * });
+ * ```
  */
-export interface CallEvent extends BaseEvent {
-  type: "call";
+export interface CallAgentToolCallEvent extends BaseEvent {
+  type: "tools/call/call_agent";
   /** The incoming call_agent request */
   request: CallAgentRequest;
   /** Run the default call handler and return its result.
@@ -139,6 +156,61 @@ export interface CallEvent extends BaseEvent {
   resolve(response: CallAgentResponse): void;
 }
 
+/**
+ * Result shape for list_agents responses.
+ */
+export interface ListAgentsResult {
+  success: true;
+  total: number;
+  nextCursor?: string;
+  agents: Array<{
+    path: string;
+    name?: string;
+    description?: string;
+    supportedActions?: string[];
+    integration?: unknown;
+    security?: { type: string };
+    resources?: Array<{ uri: string; name?: string; mimeType?: string }>;
+    tools: string[];
+  }>;
+}
+
+/**
+ * Event emitted when the `list_agents` MCP tool is invoked.
+ *
+ * Gives hosts a chance to inject additional agents (e.g., from remote registries
+ * or consumer config) before BM25 search and pagination run.
+ *
+ * Call `next(additionalAgents?)` to continue default behavior with optional
+ * extra agents merged into the base set.
+ * Call `resolve(result)` to short-circuit with a fully formed response.
+ * If neither is called, the default handler runs with the base agents.
+ *
+ * @example
+ * ```ts
+ * registry.on('tools/call/list_agents', async (event) => {
+ *   const remoteAgents = await fetchRemoteAgents();
+ *   await event.next(remoteAgents);
+ * });
+ * ```
+ */
+export interface ListAgentsToolCallEvent extends BaseEvent {
+  type: "tools/call/list_agents";
+  /** Agents from the local registry (before search/pagination) */
+  baseAgents: AgentDefinition[];
+  /** Search query, if provided */
+  query?: string;
+  /** Requested page size */
+  limit?: number;
+  /** Pagination cursor */
+  cursor?: string;
+  /** Continue with default BM25/pagination behavior.
+   *  Pass additional agents to merge into the base set. */
+  next(additionalAgents?: AgentDefinition[]): Promise<ListAgentsResult>;
+  /** Short-circuit with a complete response (same shape as list_agents output) */
+  resolve(result: ListAgentsResult): void;
+}
+
 /**
  * Union of all built-in event types.
  */
@@ -148,7 +220,8 @@ export type AgentEvent =
   | ToolErrorEvent
   | StepEvent
   | InvokeEvent
-  | CallEvent;
+  | CallAgentToolCallEvent
+  | ListAgentsToolCallEvent;
 
 /**
  * Map from system event type string to event interface.
@@ -159,7 +232,8 @@ export interface SystemEventMap {
   "tool/error": ToolErrorEvent;
   step: StepEvent;
   invoke: InvokeEvent;
-  call: CallEvent;
+  "tools/call/call_agent": CallAgentToolCallEvent;
+  "tools/call/list_agents": ListAgentsToolCallEvent;
 }
 
 /**