@slashfi/agents-sdk 0.31.0 → 0.32.0

package/dist/cjs/server.js

@@ -5,7 +5,7 @@
  * Minimal JSON-RPC server implementing the MCP protocol for agent interaction.
  * Handles only core SDK concerns:
  * - MCP protocol (initialize, tools/list, tools/call)
- * - Agent registry routing (call_agent, list_agents, search_agent_tools)
+ * - Agent registry routing (call_agent, list_agents)
  * - Auth resolution (Bearer tokens, root key, JWT)
  * - OAuth2 token exchange (client_credentials)
  * - Health check
@@ -26,10 +26,9 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasAdminScope = hasAdminScope;
+exports.getVisibleTools = exports.canSeeTool = exports.canSeeAgent = exports.hasAdminScope = void 0;
 exports.detectAuth = detectAuth;
 exports.resolveAuth = resolveAuth;
-exports.canSeeAgent = canSeeAgent;
 exports.createAgentServer = createAgentServer;
 const secrets_js_1 = require("./agent-definitions/secrets.js");
 const bm25_js_1 = require("./bm25.js");
@@ -37,12 +36,13 @@ const jwt_js_1 = require("./jwt.js");
 const jwt_js_2 = require("./jwt.js");
 const oidc_signin_js_1 = require("./oidc-signin.js");
 const call_agent_schema_js_1 = require("./call-agent-schema.js");
-/** Check if auth has admin-level access (wildcard or admin scope) */
-function hasAdminScope(auth) {
-    if (!auth)
-        return false;
-    return auth.scopes.includes("*") || auth.scopes.includes("admin");
-}
+// Auth governance — single source of truth for visibility/access control
+var auth_governance_js_1 = require("./auth-governance.js");
+Object.defineProperty(exports, "hasAdminScope", { enumerable: true, get: function () { return auth_governance_js_1.hasAdminScope; } });
+Object.defineProperty(exports, "canSeeAgent", { enumerable: true, get: function () { return auth_governance_js_1.canSeeAgent; } });
+Object.defineProperty(exports, "canSeeTool", { enumerable: true, get: function () { return auth_governance_js_1.canSeeTool; } });
+Object.defineProperty(exports, "getVisibleTools", { enumerable: true, get: function () { return auth_governance_js_1.getVisibleTools; } });
+const auth_governance_js_2 = require("./auth-governance.js");
 // ============================================
 // HTTP Helpers
 // ============================================
@@ -195,18 +195,6 @@ async function resolveAuth(req, authConfig, jwksOptions) {
         claims: {},
     };
 }
-function canSeeAgent(agent, auth) {
-    const visibility = (agent.visibility ??
-        agent.config?.visibility ??
-        "internal");
-    if (hasAdminScope(auth))
-        return true;
-    if (visibility === "public")
-        return true;
-    if (visibility === "internal" && auth)
-        return true;
-    return false;
-}
 /**
  * Resolve an agent by path, handling @ prefix normalization.
  * Tries the path as-is first, then with @ prefix.
@@ -215,35 +203,6 @@ function resolveAgent(registry, path) {
     const normalized = path.replace(/^@/, "");
     return registry.get(normalized) ?? registry.get(`@${normalized}`);
 }
-/**
- * Filter tools visible on a public agent endpoint.
- * For /agents/ routes, tools inherit the agent's visibility:
- * - If agent is public, tools without explicit visibility are shown
- * - Tool-level visibility still overrides (e.g. visibility: "private" hides it)
- */
-function getVisibleTools(agent, auth) {
-    const agentVisibility = (agent.visibility ??
-        agent.config?.visibility ??
-        "internal");
-    return agent.tools.filter((t) => {
-        const tv = t.visibility;
-        if (hasAdminScope(auth))
-            return true;
-        // Tool has explicit visibility — respect it
-        if (tv === "public")
-            return true;
-        if (tv === "private")
-            return hasAdminScope(auth) ?? false;
-        if (tv === "internal" && auth)
-            return true;
-        // No explicit tool visibility — inherit from agent
-        if (!tv && agentVisibility === "public")
-            return true;
-        if (!tv && agentVisibility === "internal" && auth)
-            return true;
-        return false;
-    });
-}
 // ============================================
 // MCP Tool Definitions
 // ============================================
@@ -256,34 +215,8 @@ function getToolDefinitions() {
         },
         {
             name: "list_agents",
-            description: "List all registered agents and their available tools.",
-            inputSchema: {
-                type: "object",
-                properties: {},
-            },
-        },
-        {
-            name: "search_agent_tools",
-            description: "Search across all registered agent tools using natural language. Returns tools ranked by relevance using BM25 scoring.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: {
-                        type: "string",
-                        description: "Natural language search query (e.g. 'send a message', 'database query')",
-                    },
-                    agents: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Optional list of agent paths to search within (e.g. ['@notifications', '@db']). Searches all agents if omitted.",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Maximum number of results to return (default: 10)",
-                    },
-                },
-                required: ["query"],
-            },
+            description: "List all registered agents and their available tools. Optionally search/filter by query using BM25 ranking.",
+            inputSchema: call_agent_schema_js_1.listAgentsInputSchema,
         },
     ];
 }
@@ -360,7 +293,7 @@ function createAgentServer(registry, options = {}) {
                     if (auth.issuer)
                         req.metadata.issuer = auth.issuer;
                 }
-                if (hasAdminScope(auth)) {
+                if ((0, auth_governance_js_2.hasAdminScope)(auth)) {
                     req.callerType = "system";
                 }
                 // Process secret params: resolve refs, store raw secrets
@@ -376,11 +309,64 @@ function createAgentServer(registry, options = {}) {
                 return mcpResult(result);
             }
             case "list_agents": {
+                const { query: listQuery, limit: listLimit, cursor: listCursor } = call_agent_schema_js_1.listAgentsToolInputSchema.parse(args);
                 const agents = registry.list();
-                const visible = agents.filter((agent) => canSeeAgent(agent, auth));
+                let visible = agents.filter((agent) => (0, auth_governance_js_2.canSeeAgent)(agent, auth));
+                // Decode cursor if provided
+                const after = listCursor
+                    ? JSON.parse(Buffer.from(listCursor, "base64url").toString())
+                    : undefined;
+                const pageSize = listLimit ?? 20;
+                let page;
+                let nextCursor;
+                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) => (0, auth_governance_js_2.canSeeTool)(t, auth))
+                                .map((t) => `${t.name} ${t.description}`),
+                        ].join(" "),
+                    }));
+                    const index = (0, bm25_js_1.createBM25Index)(docs);
+                    const ranked = index.search(listQuery);
+                    let scored = 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));
+                    }
+                    page = scored.slice(0, pageSize);
+                    if (scored.length > pageSize) {
+                        const last = scored[pageSize - 1];
+                        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);
+                    }
+                    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 mcpResult({
                     success: true,
-                    agents: visible.map((agent) => ({
+                    total: agents.filter((a) => (0, auth_governance_js_2.canSeeAgent)(a, auth)).length,
+                    nextCursor,
+                    agents: page.map((agent) => ({
                         path: agent.path,
                         name: agent.config?.name,
                         description: agent.config?.description,
@@ -395,104 +381,11 @@ function createAgentServer(registry, options = {}) {
                             mimeType: r.mimeType,
                         })),
                         tools: agent.tools
-                            .filter((t) => {
-                            const tv = t.visibility ?? "internal";
-                            if (hasAdminScope(auth))
-                                return true;
-                            if (tv === "public")
-                                return true;
-                            if (tv === "authenticated" &&
-                                auth?.callerId &&
-                                auth.callerId !== "anonymous")
-                                return true;
-                            if (tv === "internal" && auth)
-                                return true;
-                            return false;
-                        })
+                            .filter((t) => (0, auth_governance_js_2.canSeeTool)(t, auth))
                             .map((t) => t.name),
                     })),
                 });
             }
-            case "search_agent_tools": {
-                const { query, agents: agentFilter, limit: resultLimit } = args;
-                const agents = registry.list();
-                const visible = agents.filter((agent) => {
-                    if (!canSeeAgent(agent, auth))
-                        return false;
-                    if (agentFilter && agentFilter.length > 0) {
-                        return agentFilter.includes(agent.path);
-                    }
-                    return true;
-                });
-                // Build search documents from all visible tools
-                const documents = [];
-                for (const agent of visible) {
-                    const visibleTools = agent.tools.filter((t) => {
-                        const tv = t.visibility ?? "internal";
-                        if (hasAdminScope(auth))
-                            return true;
-                        if (tv === "public")
-                            return true;
-                        if (tv === "authenticated" &&
-                            auth?.callerId &&
-                            auth.callerId !== "anonymous")
-                            return true;
-                        if (tv === "internal" && auth)
-                            return true;
-                        return false;
-                    });
-                    for (const tool of visibleTools) {
-                        // Build searchable text from tool name, description, agent context, and schema
-                        const parts = [
-                            tool.name,
-                            tool.description,
-                            agent.config?.name ?? "",
-                            agent.config?.description ?? "",
-                            agent.path,
-                        ];
-                        // Include property names and descriptions from input schema
-                        const schema = tool.inputSchema;
-                        if (schema?.properties) {
-                            for (const [key, prop] of Object.entries(schema.properties)) {
-                                parts.push(key);
-                                if (prop?.description) {
-                                    parts.push(prop.description);
-                                }
-                            }
-                        }
-                        documents.push({
-                            id: `${agent.path}/${tool.name}`,
-                            text: parts.join(" "),
-                            agentPath: agent.path,
-                            toolName: tool.name,
-                            description: tool.description,
-                            agentName: agent.config?.name,
-                            agentDescription: agent.config?.description,
-                        });
-                    }
-                }
-                const index = (0, bm25_js_1.createBM25Index)(documents);
-                const results = index.search(query, resultLimit ?? 10);
-                // Map results back to tool details
-                const docMap = new Map(documents.map((d) => [d.id, d]));
-                const matches = results.map((r) => {
-                    const doc = docMap.get(r.id);
-                    return {
-                        agentPath: doc.agentPath,
-                        tool: doc.toolName,
-                        description: doc.description,
-                        agentName: doc.agentName,
-                        agentDescription: doc.agentDescription,
-                        score: r.score,
-                    };
-                });
-                return mcpResult({
-                    success: true,
-                    query,
-                    results: matches,
-                    total: matches.length,
-                });
-            }
             default:
                 throw new Error(`Unknown tool: ${toolName}`);
         }
@@ -847,8 +740,11 @@ function createAgentServer(registry, options = {}) {
             // Only exposed when the server requires auth (private registries).
             // 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,
@@ -865,32 +761,76 @@ function createAgentServer(registry, options = {}) {
                 });
                 return cors ? addCors(res) : res;
             }
-            // ── GET /list → List agents (legacy endpoint) ──
+            // ── GET /list → List agents (──
             if (path === "/list" && req.method === "GET") {
                 const agents = registry.list();
-                const visible = agents.filter((agent) => canSeeAgent(agent, effectiveAuth));
-                const res = jsonResponse(visible.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) => {
-                        const tv = t.visibility ?? "internal";
-                        if (hasAdminScope(effectiveAuth))
-                            return true;
-                        if (tv === "public")
-                            return true;
-                        if (tv === "internal" && effectiveAuth)
-                            return true;
-                        return false;
-                    })
-                        .map((t) => ({
-                        name: t.name,
-                        description: t.description,
+                let visible = agents.filter((agent) => (0, auth_governance_js_2.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())
+                    : undefined;
+                const httpPageSize = searchLimit ? Number(searchLimit) : 20;
+                let httpPage;
+                let httpNextCursor;
+                if (searchQuery) {
+                    const docs = visible.map((agent, i) => ({
+                        id: String(i),
+                        text: [
+                            agent.path,
+                            agent.config?.name ?? "",
+                            agent.config?.description ?? "",
+                            ...agent.tools
+                                .filter((t) => (0, auth_governance_js_2.canSeeTool)(t, effectiveAuth))
+                                .map((t) => `${t.name} ${t.description}`),
+                        ].join(" "),
+                    }));
+                    const index = (0, bm25_js_1.createBM25Index)(docs);
+                    const ranked = index.search(searchQuery);
+                    let scored = 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];
+                        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) => (0, auth_governance_js_2.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) => (0, auth_governance_js_2.canSeeTool)(t, effectiveAuth))
+                            .map((t) => ({
+                            name: t.name,
+                            description: t.description,
+                        })),
                     })),
-                })));
+                });
                 return cors ? addCors(res) : res;
             }
             // ── GET /agents → List public agents (discovery endpoint) ──
@@ -900,7 +840,7 @@ function createAgentServer(registry, options = {}) {
                     // Only show agents with explicit visibility
                     if (!agent.visibility)
                         return false;
-                    return canSeeAgent(agent, effectiveAuth);
+                    return (0, auth_governance_js_2.canSeeAgent)(agent, effectiveAuth);
                 });
                 const res = jsonResponse(visible.map((agent) => ({
                     path: agent.path,
@@ -908,7 +848,7 @@ function createAgentServer(registry, options = {}) {
                     description: agent.config?.description ?? agent.entrypoint?.slice(0, 200),
                     mode: agent.mode ?? 'direct',
                     ...(agent.upstream && { upstream: agent.upstream }),
-                    tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
+                    tools: (0, auth_governance_js_2.getVisibleTools)(agent, effectiveAuth).map((t) => ({
                         name: t.name,
                         description: t.description,
                     })),
@@ -919,7 +859,7 @@ function createAgentServer(registry, options = {}) {
             if (path.startsWith("/agents/") && req.method === "GET") {
                 const agentPath = path.slice("/agents/".length); // e.g. "notion"
                 const agent = resolveAgent(registry, agentPath);
-                if (!agent || !canSeeAgent(agent, effectiveAuth)) {
+                if (!agent || !(0, auth_governance_js_2.canSeeAgent)(agent, effectiveAuth)) {
                     const res = jsonResponse({ error: "not_found", message: `Agent not found: ${agentPath}` }, 404);
                     return cors ? addCors(res) : res;
                 }
@@ -929,7 +869,7 @@ function createAgentServer(registry, options = {}) {
                     description: agent.config?.description ?? agent.entrypoint?.slice(0, 200),
                     mode: agent.mode ?? 'direct',
                     ...(agent.upstream && { upstream: agent.upstream }),
-                    tools: getVisibleTools(agent, effectiveAuth).map((t) => ({
+                    tools: (0, auth_governance_js_2.getVisibleTools)(agent, effectiveAuth).map((t) => ({
                         name: t.name,
                         description: t.description,
                         inputSchema: t.inputSchema,
@@ -943,11 +883,11 @@ function createAgentServer(registry, options = {}) {
             if (path === "/call" && req.method === "POST") {
                 const body = (await req.json());
                 const agent = resolveAgent(registry, body.path);
-                if (!agent || !canSeeAgent(agent, effectiveAuth)) {
+                if (!agent || !(0, auth_governance_js_2.canSeeAgent)(agent, effectiveAuth)) {
                     const res = jsonResponse({ error: "not_found", message: `Agent not found: ${body.path}` }, 404);
                     return cors ? addCors(res) : res;
                 }
-                const visibleTools = getVisibleTools(agent, effectiveAuth);
+                const visibleTools = (0, auth_governance_js_2.getVisibleTools)(agent, effectiveAuth);
                 if (!visibleTools.find((t) => t.name === body.tool)) {
                     const res = jsonResponse({ error: "not_found", message: `Tool not found: ${body.tool}` }, 404);
                     return cors ? addCors(res) : res;
@@ -979,7 +919,7 @@ function createAgentServer(registry, options = {}) {
             if (path.startsWith("/agents/") && req.method === "POST") {
                 const agentPath = path.slice("/agents/".length);
                 const agent = resolveAgent(registry, agentPath);
-                if (!agent || !canSeeAgent(agent, effectiveAuth)) {
+                if (!agent || !(0, auth_governance_js_2.canSeeAgent)(agent, effectiveAuth)) {
                     const res = jsonResponse({ error: "not_found", message: `Agent not found: ${agentPath}` }, 404);
                     return cors ? addCors(res) : res;
                 }
@@ -997,7 +937,7 @@ function createAgentServer(registry, options = {}) {
                     return cors ? addCors(res) : res;
                 }
                 if (body.method === "tools/list") {
-                    const tools = getVisibleTools(agent, effectiveAuth).map((t) => ({
+                    const tools = (0, auth_governance_js_2.getVisibleTools)(agent, effectiveAuth).map((t) => ({
                         name: t.name,
                         description: t.description,
                         inputSchema: t.inputSchema,
@@ -1113,7 +1053,7 @@ function createAgentServer(registry, options = {}) {
                 throw new Error("No signing keys available. Call start() or initKeys() first.");
             }
             const key = serverSigningKeys[0];
-            return (0, jwt_js_2.signJwtES256)({ sub: "system", name: "atlas-os", scopes: ["*"], ...claims }, key.privateKey, key.kid, options.serverName ?? "agents-sdk", "1h");
+            return (0, jwt_js_2.signJwtES256)({ sub: "system", name: "atlas-os", scopes: ["*"], ...claims }, key.privateKey, key.kid, options.serverName ?? "agents-sdk", claims.exp != null ? undefined : "1h");
         },
         async resolveAuth(req) {
             const customAuth = options.resolveAuth