@slashfi/agents-sdk 0.35.0 → 0.36.1

package/src/registry.ts

@@ -5,7 +5,7 @@
  */
 
 import { dirname, resolve } from "node:path";
-import type { AgentEvent, BaseEvent, CustomEventMap, EventCallback, EventType } from "./events.js";
+import type { AgentEvent, BaseEvent, CallAgentToolCallEvent, CustomEventMap, EventCallback, EventType, ListAgentsResult, ListAgentsToolCallEvent } from "./events.js";
 import { createEventBus } from "./events.js";
 import type { SerializedAgentDefinition } from "./serialized.js";
 import type {
@@ -96,6 +96,21 @@ export interface AgentRegistry {
   /** Call an agent (execute action) */
   call(request: CallAgentRequest): Promise<CallAgentResponse>;
 
+  /**
+   * List agents with hook support.
+   * Emits `tools/call/list_agents` event so hosts can inject additional agents
+   * (e.g., from remote registries or consumer config) before the callback runs.
+   *
+   * @param params - Query/pagination params from the MCP tool call
+   * @param callback - Processes the (possibly augmented) agent list into the final result.
+   *                   Receives the merged agent list; responsible for visibility, BM25, pagination.
+   * @returns The ListAgentsResult from either the callback or an intercepting listener
+   */
+  listAgents(
+    params: { query?: string; limit?: number; cursor?: string },
+    callback: (agents: AgentDefinition[]) => Promise<ListAgentsResult>,
+  ): Promise<ListAgentsResult>;
+
   /** Register an event listener (global scope — fires for all agents) */
   on<T extends EventType>(eventType: T, callback: EventCallback<T>): void;
 
@@ -183,6 +198,18 @@ export function agentFromSerialized(
   };
 }
 
+/**
+ * Deduplicate agents by path. Later entries (from additionalAgents) override
+ * earlier ones from the base set.
+ */
+function dedupeAgents(agents: AgentDefinition[]): AgentDefinition[] {
+  const seen = new Map<string, AgentDefinition>();
+  for (const agent of agents) {
+    seen.set(agent.path, agent);
+  }
+  return Array.from(seen.values());
+}
+
 export function createAgentRegistry(
   options: AgentRegistryOptions = {},
 ): AgentRegistry {
@@ -484,6 +511,46 @@ export function createAgentRegistry(
       return Array.from(agents.keys());
     },
 
+    async listAgents(
+      params: { query?: string; limit?: number; cursor?: string },
+      callback: (agents: AgentDefinition[]) => Promise<ListAgentsResult>,
+    ): Promise<ListAgentsResult> {
+      const baseAgents = Array.from(agents.values());
+      let intercepted: ListAgentsResult | undefined;
+      let nextCalled = false;
+      let nextResult: ListAgentsResult | undefined;
+
+      const nextFn = async (additionalAgents?: AgentDefinition[]) => {
+        nextCalled = true;
+        const merged = additionalAgents
+          ? dedupeAgents([...baseAgents, ...additionalAgents])
+          : baseAgents;
+        nextResult = await callback(merged);
+        return nextResult;
+      };
+      const resolveFn = (result: ListAgentsResult) => {
+        intercepted = result;
+      };
+
+      await eventBus.emit({
+        type: "tools/call/list_agents",
+        agentPath: "*",
+        timestamp: Date.now(),
+        baseAgents,
+        query: params.query,
+        limit: params.limit,
+        cursor: params.cursor,
+        next: nextFn,
+        resolve: resolveFn,
+      } satisfies ListAgentsToolCallEvent);
+
+      if (intercepted) return intercepted;
+      if (nextCalled) return nextResult!;
+
+      // No listener engaged — run default with base agents
+      return callback(baseAgents);
+    },
+
     on<T extends EventType>(eventType: T, callback: EventCallback<T>): void {
       eventBus.on(eventType, callback);
     },
@@ -500,26 +567,32 @@ export function createAgentRegistry(
     },
 
     async call(request: CallAgentRequest): Promise<CallAgentResponse> {
-      // Emit call event — listeners can next()/resolve() to control flow
+      // Emit tools/call/call_agent event — listeners can next()/resolve() to control flow
       let intercepted: CallAgentResponse | undefined;
       let nextCalled = false;
       let nextResult: CallAgentResponse | undefined;
+
+      const nextFn = async (overrideRequest?: CallAgentRequest) => {
+        nextCalled = true;
+        nextResult = await callInternal(overrideRequest ?? request);
+        return nextResult;
+      };
+      const resolveFn = (response: CallAgentResponse) => {
+        intercepted = response;
+      };
+
+      // Emit the new namespaced event
       await eventBus.emit({
-        type: "call",
+        type: "tools/call/call_agent",
         agentPath: request.path,
         timestamp: Date.now(),
         request,
-        async next(overrideRequest?: CallAgentRequest) {
-          nextCalled = true;
-          nextResult = await callInternal(overrideRequest ?? request);
-          return nextResult;
-        },
-        resolve(response: CallAgentResponse) {
-          intercepted = response;
-        },
-      });
+        next: nextFn,
+        resolve: resolveFn,
+      } satisfies CallAgentToolCallEvent);
       if (intercepted) return intercepted;
       if (nextCalled) return nextResult!;
+
       // No listener engaged — run default
       return callInternal(request);
     },
@@ -721,6 +794,15 @@ export function createAgentRegistry(
           return {
             success: true,
             tools: toolSchemas,
+            description: agent.config?.description,
+            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,
+            })),
           } as CallAgentDescribeToolsResponse;
         }
 

package/src/server.ts

@@ -670,101 +670,108 @@ export function createAgentServer(
           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,
-          }));
 
-          // 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),
-            );
-          }
+        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),
+                );
+              }
 
-          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 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 {
+              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(result);
       }
 
       default:

package/src/types.ts

@@ -750,6 +750,12 @@ export interface CallAgentExecuteToolResponse {
 export interface CallAgentDescribeToolsResponse {
   success: true;
   tools: ToolSchema[];
+  /** Agent description */
+  description?: string;
+  /** Security scheme (if any) */
+  security?: SecuritySchemeSummary;
+  /** Available resources (e.g., AUTH.md) */
+  resources?: Array<{ uri: string; name?: string; mimeType?: string }>;
 }
 
 /** A resolved agent ref with its discovered tools */