@slashfi/agents-sdk 0.34.1 → 0.36.0

package/src/server.ts

@@ -31,9 +31,10 @@ import {
   processSecretParams,
 } from "./agent-definitions/secrets.js";
 import { createBM25Index } from "./bm25.js";
-import { verifyJwt } from "./jwt.js";
-import type { SigningKey } from "./jwt.js";
 import {
+  verifyJwt,
+  type AgentJwtPayload,
+  type SigningKey,
   buildJwks,
   exportSigningKey,
   generateSigningKey,
@@ -44,8 +45,6 @@ import {
 } from "./jwt.js";
 import { type OIDCProviderConfig, createOIDCSignIn } from "./oidc-signin.js";
 import type { AgentRegistry } from "./registry.js";
-import type { AgentDefinition, CallAgentRequest } from "./types.js";
-
 import {
   callAgentInputSchema,
   callAgentValidationSchema,
@@ -53,7 +52,33 @@ import {
   listAgentsValidationSchema,
   nullTolerant,
   zodToOpenAiJsonSchema,
+  type CallAgentExecuteToolRequest,
+  type CallerType,
 } from "./call-agent-schema.js";
+import type {
+  AgentDefinition,
+  AuthClientCredentialsTokenResult,
+  CallAgentRequest,
+  ExchangeTokenToolResult,
+} from "./types.js";
+import {
+  isCallAgentErrorResponse,
+  isExchangeTokenLinkedSuccess,
+  isExchangeTokenNeedsIdentity,
+} from "./types.js";
+
+/** JWT payload claims used for reverse registry registration (jwt_exchange). */
+interface RegistryAssertionPayload {
+  type?: string;
+  iss?: string;
+  name?: string;
+  tenantId?: string;
+}
+
+function parseProxyCallerType(raw: string | null): CallerType {
+  if (raw === "agent" || raw === "user" || raw === "system") return raw;
+  return "agent";
+}
 
 // ============================================
 // Server Types
@@ -231,7 +256,6 @@ export interface AuthConfig {
   tokenTtl?: number;
 }
 
-
 // Auth governance — single source of truth for visibility/access control
 export {
   type ResolvedAuth,
@@ -539,8 +563,12 @@ export function createAgentServer(
             ...(options.registry && {
               registry: {
                 version: options.registry.version ?? "1.0",
-                ...(options.registry.features && { features: options.registry.features }),
-                ...(options.registry.oauthCallbackUrl && { oauthCallbackUrl: options.registry.oauthCallbackUrl }),
+                ...(options.registry.features && {
+                  features: options.registry.features,
+                }),
+                ...(options.registry.oauthCallbackUrl && {
+                  oauthCallbackUrl: options.registry.oauthCallbackUrl,
+                }),
               },
             }),
           },
@@ -598,9 +626,11 @@ export function createAgentServer(
       case "call_agent": {
         // Validate + strip nulls (OpenAI convention: null = absent)
         const parsed = callAgentValidate.safeParse(args);
-        const req = (parsed.success
-          ? (parsed.data as Record<string, unknown>).request ?? parsed.data
-          : (args.request ?? args)) as CallAgentRequest;
+        const req = (
+          parsed.success
+            ? ((parsed.data as Record<string, unknown>).request ?? parsed.data)
+            : (args.request ?? args)
+        ) as CallAgentRequest;
 
         // Inject auth context
         if (auth) {
@@ -615,18 +645,19 @@ export function createAgentServer(
         }
 
         // Process secret params: resolve refs, store raw secrets
-        if ((req as any).params && secretStore) {
+        if (req.action === "execute_tool" && req.params && secretStore) {
+          const execReq: CallAgentExecuteToolRequest = req;
           const ownerId = auth?.callerId ?? "anonymous";
-          const agent = registry.get(req.path);
-          const tool = agent?.tools.find((t) => t.name === (req as any).tool);
-          const schema = tool?.inputSchema as any;
+          const agent = registry.get(execReq.path);
+          const tool = agent?.tools.find((t) => t.name === execReq.tool);
+          const schema = tool?.inputSchema;
           const { resolved } = await processSecretParams(
-            (req as any).params as Record<string, unknown>,
-            schema,
+            execReq.params as Record<string, unknown>,
+            schema as Parameters<typeof processSecretParams>[1],
             secretStore,
             ownerId,
           );
-          (req as any).params = resolved;
+          execReq.params = resolved;
         }
 
         const result = await registry.call(req);
@@ -634,102 +665,113 @@ export function createAgentServer(
       }
 
       case "list_agents": {
-        const { query: listQuery, limit: listLimit, cursor: listCursor } =
-          listAgentsValidate.parse(args);
-        const agents = registry.list();
-        let visible = agents.filter((agent) => canSeeAgent(agent, auth));
-
-        // Decode cursor if provided
-        const after = listCursor
-          ? (JSON.parse(
-              Buffer.from(listCursor, "base64url").toString(),
-            ) as { path: string; score?: number })
-          : undefined;
-
-        const pageSize = listLimit ?? 20;
-        let page: typeof visible;
-        let nextCursor: string | undefined;
-
-        if (listQuery) {
-          // BM25 search — ranked by score desc, path asc for tie-breaking
-          const docs = visible.map((agent, i) => ({
-            id: String(i),
-            text: [
-              agent.path,
-              agent.config?.name ?? "",
-              agent.config?.description ?? "",
-              ...agent.tools
-                .filter((t) => canSeeTool(t, auth))
-                .map((t) => `${t.name} ${t.description}`),
-            ].join(" "),
-          }));
-          const index = createBM25Index(docs);
-          const ranked = index.search(listQuery);
-
-          // Build scored list
-          type ScoredAgent = (typeof visible)[number] & { _score: number };
-          let scored: ScoredAgent[] = ranked.map((r) => ({
-            ...visible[Number(r.id)],
-            _score: r.score,
-          }));
+        const {
+          query: listQuery,
+          limit: listLimit,
+          cursor: listCursor,
+        } = listAgentsValidate.parse(args);
+
+        const result = await registry.listAgents(
+          { query: listQuery, limit: listLimit, cursor: listCursor },
+          async (allAgents) => {
+            let visible = allAgents.filter((agent) => canSeeAgent(agent, auth));
+
+            // Decode cursor if provided
+            const after = listCursor
+              ? (JSON.parse(Buffer.from(listCursor, "base64url").toString()) as {
+                  path: string;
+                  score?: number;
+                })
+              : undefined;
+
+            const pageSize = listLimit ?? 20;
+            let page: typeof visible;
+            let nextCursor: string | undefined;
+
+            if (listQuery) {
+              // BM25 search — ranked by score desc, path asc for tie-breaking
+              const docs = visible.map((agent, i) => ({
+                id: String(i),
+                text: [
+                  agent.path,
+                  agent.config?.name ?? "",
+                  agent.config?.description ?? "",
+                  ...agent.tools
+                    .filter((t) => canSeeTool(t, auth))
+                    .map((t) => `${t.name} ${t.description}`),
+                ].join(" "),
+              }));
+              const index = createBM25Index(docs);
+              const ranked = index.search(listQuery);
+
+              // Build scored list
+              type ScoredAgent = (typeof visible)[number] & { _score: number };
+              let scored: ScoredAgent[] = ranked.map((r) => ({
+                ...visible[Number(r.id)],
+                _score: r.score,
+              }));
+
+              // Apply cursor: skip past the after position
+              if (after?.score !== undefined) {
+                scored = scored.filter(
+                  (a) =>
+                    a._score < after.score! ||
+                    (a._score === after.score! && a.path > after.path),
+                );
+              }
 
-          // Apply cursor: skip past the after position
-          if (after?.score !== undefined) {
-            scored = scored.filter(
-              (a) =>
-                a._score < after.score! ||
-                (a._score === after.score! && a.path > after.path),
-            );
-          }
+              page = scored.slice(0, pageSize);
+              if (scored.length > pageSize) {
+                const last = scored[pageSize - 1] as ScoredAgent;
+                nextCursor = Buffer.from(
+                  JSON.stringify({ path: last.path, score: last._score }),
+                ).toString("base64url");
+              }
+            } else {
+              // Alphabetical listing — sorted by path
+              visible.sort((a, b) => a.path.localeCompare(b.path));
 
-          page = scored.slice(0, pageSize);
-          if (scored.length > pageSize) {
-            const last = scored[pageSize - 1] as ScoredAgent;
-            nextCursor = Buffer.from(
-              JSON.stringify({ path: last.path, score: last._score }),
-            ).toString("base64url");
-          }
-        } else {
-          // Alphabetical listing — sorted by path
-          visible.sort((a, b) => a.path.localeCompare(b.path));
+              // Apply cursor: skip past afterPath
+              if (after) {
+                visible = visible.filter((a) => a.path > after.path);
+              }
 
-          // Apply cursor: skip past afterPath
-          if (after) {
-            visible = visible.filter((a) => a.path > after.path);
-          }
+              page = visible.slice(0, pageSize);
+              if (visible.length > pageSize) {
+                const last = page[page.length - 1];
+                nextCursor = Buffer.from(
+                  JSON.stringify({ path: last.path }),
+                ).toString("base64url");
+              }
+            }
 
-          page = visible.slice(0, pageSize);
-          if (visible.length > pageSize) {
-            const last = page[page.length - 1];
-            nextCursor = Buffer.from(
-              JSON.stringify({ path: last.path }),
-            ).toString("base64url");
-          }
-        }
+            return {
+              success: true as const,
+              total: allAgents.filter((a) => canSeeAgent(a, auth)).length,
+              nextCursor,
+              agents: page.map((agent) => ({
+                path: agent.path,
+                name: agent.config?.name,
+                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) => canSeeTool(t, auth))
+                  .map((t) => t.name),
+              })),
+            };
+          },
+        );
 
-        return mcpResult({
-          success: true,
-          total: agents.filter((a) => canSeeAgent(a, auth)).length,
-          nextCursor,
-          agents: page.map((agent) => ({
-            path: agent.path,
-            name: agent.config?.name,
-            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) => canSeeTool(t, auth))
-              .map((t) => t.name),
-          })),
-        });
+        return mcpResult(result);
       }
 
       default:
@@ -798,27 +840,36 @@ export function createAgentServer(
           callerType: "system",
         });
 
-        const exchangeResult = (result as any)?.result;
-        // If the tool call failed, forward the error
-        if ((result as any)?.success === false) {
+        if (isCallAgentErrorResponse(result)) {
           return jsonResponse(
             {
               error: "server_error",
-              error_description:
-                (result as any)?.error ?? "Exchange tool failed",
+              error_description: result.error ?? "Exchange tool failed",
               raw: JSON.stringify(result)?.slice(0, 300),
             },
             500,
           );
         }
 
+        if (!("result" in result)) {
+          return jsonResponse(
+            {
+              error: "server_error",
+              error_description: `Unexpected exchange response: ${JSON.stringify(result)?.slice(0, 300)}`,
+            },
+            500,
+          );
+        }
+
+        const exchangeResult = result.result as ExchangeTokenToolResult;
+
         // ── Reverse registration: if caller is an agent-registry, auto-store connection ──
         try {
           const assertionParts = assertion.split(".");
           if (assertionParts.length === 3) {
             const assertionPayload = JSON.parse(
               Buffer.from(assertionParts[1], "base64url").toString(),
-            ) as any;
+            ) as RegistryAssertionPayload;
             if (
               assertionPayload.type === "agent-registry" &&
               assertionPayload.iss
@@ -844,7 +895,7 @@ export function createAgentServer(
               } else {
                 console.error(
                   "[jwt_exchange] Reverse connection failed:",
-                  (addResult as any).error,
+                  addResult.error,
                 );
               }
             }
@@ -867,7 +918,7 @@ export function createAgentServer(
         }
 
         // User not linked yet — needs OAuth identity linking
-        if (exchangeResult.needsAuth) {
+        if (isExchangeTokenNeedsIdentity(exchangeResult)) {
           const baseUrl = resolveBaseUrl(req);
           const authorizeUrl = new URL(`${baseUrl}${basePath}/oauth/authorize`);
           authorizeUrl.searchParams.set("token", assertion);
@@ -890,7 +941,10 @@ export function createAgentServer(
         }
 
         // User found — sign a local access token
-        if (exchangeResult.userId && serverSigningKeys.length > 0) {
+        if (
+          isExchangeTokenLinkedSuccess(exchangeResult) &&
+          serverSigningKeys.length > 0
+        ) {
           const sigKey = serverSigningKeys[0];
           const token = await signJwtES256(
             {
@@ -951,8 +1005,28 @@ export function createAgentServer(
           callerType: "system",
         });
 
-        const tokenResult = (result as any)?.result;
-        if (!tokenResult?.accessToken) {
+        if (isCallAgentErrorResponse(result)) {
+          return jsonResponse(
+            {
+              error: "invalid_client",
+              error_description: result.error ?? "Authentication failed",
+            },
+            401,
+          );
+        }
+
+        if (!("result" in result)) {
+          return jsonResponse(
+            {
+              error: "invalid_client",
+              error_description: "Authentication failed",
+            },
+            401,
+          );
+        }
+
+        const tokenResult = result.result as AuthClientCredentialsTokenResult;
+        if (tokenResult.accessToken == null) {
           return jsonResponse(
             {
               error: "invalid_client",
@@ -1020,7 +1094,7 @@ export function createAgentServer(
             if (actorId) {
               return {
                 callerId: actorId,
-                callerType: (actorType as any) ?? "agent",
+                callerType: parseProxyCallerType(actorType),
                 scopes: ["*"],
                 claims: {},
               };
@@ -1119,12 +1193,12 @@ export function createAgentServer(
               claims = result as unknown as Record<string, unknown>;
               break;
             }
-          } catch (e: any) {
+          } catch (e: unknown) {
             console.log(
               "[oauth/authorize] verify",
               issuerUrl,
               "-> ERROR:",
-              e.message,
+              e instanceof Error ? e.message : String(e),
             );
           }
         }
@@ -1190,24 +1264,6 @@ export function createAgentServer(
         return cors ? addCors(res) : res;
       }
 
-      // ── GET /.well-known/configuration → Server discovery (deprecated, use MCP initialize capabilities) ──
-      if (path === "/.well-known/configuration" && req.method === "GET") {
-        const baseUrl = resolveBaseUrl(req);
-        const res = jsonResponse({
-          issuer: baseUrl,
-          jwks_uri: `${baseUrl}/.well-known/jwks.json`,
-          token_endpoint: `${baseUrl}/oauth/token`,
-          agents_endpoint: `${baseUrl}/list`,
-          call_endpoint: baseUrl,
-          supported_grant_types: ["client_credentials", "jwt_exchange"],
-          authorization_endpoint: `${baseUrl}/oauth/authorize`,
-          ...(oidcSignIn
-            ? { signin_endpoint: `${baseUrl}/signin/authorize` }
-            : {}),
-        });
-        return cors ? addCors(res) : res;
-      }
-
       // ── GET /.well-known/oauth-authorization-server → OAuth Server Metadata (RFC 8414) ──
       // Only exposed when the server requires auth (private registries).
       // Public registries (e.g. registry.slash.com) skip this entirely.
@@ -1215,7 +1271,9 @@ export function createAgentServer(
         path === "/.well-known/oauth-authorization-server" &&
         req.method === "GET"
       ) {
-        if (!(options.registry?.oauthCallbackUrl || serverSigningKeys.length > 0)) {
+        if (
+          !(options.registry?.oauthCallbackUrl || serverSigningKeys.length > 0)
+        ) {
           const res = new Response("Not Found", { status: 404 });
           return cors ? addCors(res) : res;
         }
@@ -1226,7 +1284,11 @@ export function createAgentServer(
           token_endpoint: `${baseUrl}/oauth/token`,
           jwks_uri: `${baseUrl}/.well-known/jwks.json`,
           response_types_supported: ["code"],
-          grant_types_supported: ["authorization_code", "client_credentials", "jwt_exchange"],
+          grant_types_supported: [
+            "authorization_code",
+            "client_credentials",
+            "jwt_exchange",
+          ],
           code_challenge_methods_supported: ["S256"],
           token_endpoint_auth_methods_supported: ["client_secret_post", "none"],
           ...(options.registry?.oauthCallbackUrl && {
@@ -1236,98 +1298,6 @@ export function createAgentServer(
         return cors ? addCors(res) : res;
       }
 
-      // ── GET /list → List agents (──
-      if (path === "/list" && req.method === "GET") {
-        const agents = registry.list();
-        let visible = agents.filter((agent) =>
-          canSeeAgent(agent, effectiveAuth),
-        );
-
-        const searchQuery = url.searchParams.get("q");
-        const searchLimit = url.searchParams.get("limit");
-        const searchCursor = url.searchParams.get("cursor");
-
-        // Decode cursor
-        const httpAfter = searchCursor
-          ? (JSON.parse(
-              Buffer.from(searchCursor, "base64url").toString(),
-            ) as { path: string; score?: number })
-          : undefined;
-
-        const httpPageSize = searchLimit ? Number(searchLimit) : 20;
-        let httpPage: typeof visible;
-        let httpNextCursor: string | undefined;
-
-        if (searchQuery) {
-          const docs = visible.map((agent, i) => ({
-            id: String(i),
-            text: [
-              agent.path,
-              agent.config?.name ?? "",
-              agent.config?.description ?? "",
-              ...agent.tools
-                .filter((t) => canSeeTool(t, effectiveAuth))
-                .map((t) => `${t.name} ${t.description}`),
-            ].join(" "),
-          }));
-          const index = createBM25Index(docs);
-          const ranked = index.search(searchQuery);
-
-          type ScoredAgent = (typeof visible)[number] & { _score: number };
-          let scored: ScoredAgent[] = ranked.map((r) => ({
-            ...visible[Number(r.id)],
-            _score: r.score,
-          }));
-
-          if (httpAfter?.score !== undefined) {
-            scored = scored.filter(
-              (a) =>
-                a._score < httpAfter.score! ||
-                (a._score === httpAfter.score! && a.path > httpAfter.path),
-            );
-          }
-
-          httpPage = scored.slice(0, httpPageSize);
-          if (scored.length > httpPageSize) {
-            const last = scored[httpPageSize - 1] as ScoredAgent;
-            httpNextCursor = Buffer.from(
-              JSON.stringify({ path: last.path, score: last._score }),
-            ).toString("base64url");
-          }
-        } else {
-          visible.sort((a, b) => a.path.localeCompare(b.path));
-          if (httpAfter) {
-            visible = visible.filter((a) => a.path > httpAfter.path);
-          }
-          httpPage = visible.slice(0, httpPageSize);
-          if (visible.length > httpPageSize) {
-            const last = httpPage[httpPage.length - 1];
-            httpNextCursor = Buffer.from(
-              JSON.stringify({ path: last.path }),
-            ).toString("base64url");
-          }
-        }
-
-        const res = jsonResponse({
-          total: agents.filter((a) => canSeeAgent(a, effectiveAuth)).length,
-          nextCursor: httpNextCursor,
-          agents: httpPage.map((agent) => ({
-            path: agent.path,
-            name: agent.config?.name,
-            description: agent.config?.description,
-            supportedActions: agent.config?.supportedActions,
-            integration: agent.config?.integration || null,
-            tools: agent.tools
-              .filter((t) => canSeeTool(t, effectiveAuth))
-              .map((t) => ({
-                name: t.name,
-                description: t.description,
-              })),
-          })),
-        });
-        return cors ? addCors(res) : res;
-      }
-
       // ── GET /agents → List public agents (discovery endpoint) ──
       if (path === "/agents" && req.method === "GET") {
         const agents = registry.list();
@@ -1342,7 +1312,7 @@ export function createAgentServer(
             name: agent.config?.name,
             description:
               agent.config?.description ?? agent.entrypoint?.slice(0, 200),
-            mode: agent.mode ?? 'direct',
+            mode: agent.mode ?? "direct",
             ...(agent.upstream && { upstream: agent.upstream }),
             tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
               name: t.name,
@@ -1369,7 +1339,7 @@ export function createAgentServer(
           name: agent.config?.name,
           description:
             agent.config?.description ?? agent.entrypoint?.slice(0, 200),
-          mode: agent.mode ?? 'direct',
+          mode: agent.mode ?? "direct",
           ...(agent.upstream && { upstream: agent.upstream }),
           tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
             name: t.name,
@@ -1595,7 +1565,7 @@ export function createAgentServer(
         hostname,
         fetch,
       });
-      (this as any).url = `http://${hostname}:${port}`;
+      this.url = `http://${hostname}:${port}`;
       console.log(
         `[agents-sdk] Server listening on http://${hostname}:${port}`,
       );
@@ -1605,7 +1575,7 @@ export function createAgentServer(
       if (serverInstance) {
         serverInstance.stop();
         serverInstance = null;
-        (this as any).url = null;
+        this.url = null;
       }
     },
 
@@ -1618,8 +1588,14 @@ export function createAgentServer(
         );
       }
       const key = serverSigningKeys[0];
+      const payload: Omit<AgentJwtPayload, "iat" | "exp"> = {
+        sub: "system",
+        name: "atlas-os",
+        scopes: ["*"],
+        ...(claims as Partial<Omit<AgentJwtPayload, "iat" | "exp">>),
+      };
       return signJwtES256(
-        { sub: "system", name: "atlas-os", scopes: ["*"], ...claims } as any,
+        payload,
         key.privateKey,
         key.kid,
         options.serverName ?? "agents-sdk",