@slashfi/agents-sdk 0.31.0-pr.dev.9f92286 → 0.32.0

package/src/auth-governance.ts

@@ -0,0 +1,94 @@
+/**
+ * Auth Governance
+ *
+ * Single source of truth for visibility and access control decisions.
+ * Used by the server, middleware, and any custom implementations.
+ */
+
+import type { Visibility, AgentDefinition } from "./types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ResolvedAuth {
+  issuer?: string;
+  callerId: string;
+  callerType: "agent" | "user" | "system";
+  scopes: string[];
+  /** All JWT claims from the verified token (passthrough) */
+  claims: Record<string, unknown>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Governance Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if the auth context has admin scope.
+ */
+export function hasAdminScope(auth: ResolvedAuth | null): boolean {
+  if (!auth) return false;
+  return auth.scopes.includes("*") || auth.scopes.includes("admin");
+}
+
+/**
+ * Check if an agent is visible to the given auth context.
+ */
+export function canSeeAgent(
+  agent: AgentDefinition,
+  auth: ResolvedAuth | null,
+): boolean {
+  const visibility = ((agent as any).visibility ??
+    agent.config?.visibility ??
+    "internal") as Visibility;
+  if (hasAdminScope(auth)) return true;
+  if (visibility === "public") return true;
+  if (visibility === "internal" && auth) return true;
+  return false;
+}
+
+/**
+ * Check if a tool is visible to the given auth context.
+ *
+ * When agentVisibility is provided, tools without explicit visibility
+ * inherit from their parent agent.
+ */
+export function canSeeTool(
+  tool: { visibility?: Visibility },
+  auth: ResolvedAuth | null,
+  agentVisibility?: Visibility,
+): boolean {
+  const tv = tool.visibility;
+  if (hasAdminScope(auth)) return true;
+  // Tool has explicit visibility — respect it
+  if (tv === "public") return true;
+  if (tv === "private") return false;
+  if (
+    tv === "authenticated" &&
+    auth?.callerId &&
+    auth.callerId !== "anonymous"
+  )
+    return true;
+  if (tv === "internal" && auth) return true;
+  // No explicit tool visibility — inherit from agent or default to internal
+  if (!tv) {
+    const inherited = agentVisibility ?? "internal";
+    if (inherited === "public") return true;
+    if (inherited === "internal" && auth) return true;
+  }
+  return false;
+}
+
+/**
+ * Get visible tools for an agent, respecting visibility inheritance.
+ */
+export function getVisibleTools(
+  agent: AgentDefinition,
+  auth: ResolvedAuth | null,
+): typeof agent.tools {
+  const agentVisibility = ((agent as any).visibility ??
+    agent.config?.visibility ??
+    "internal") as Visibility;
+  return agent.tools.filter((t) => canSeeTool(t, auth, agentVisibility));
+}

package/src/call-agent-schema.ts

@@ -168,3 +168,36 @@ export const callAgentInputSchema = zodToJsonSchema(
   callAgentToolInputSchema as any,
   { target: "openAi" }
 );
+
+// ─────────────────────────────────────────────────────────────────────────────
+// list_agents schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const listAgentsToolInputSchema = z.object({
+  query: z
+    .string()
+    .optional()
+    .describe(
+      "Search query. When provided, returns agents ranked by BM25 relevance over paths, names, descriptions, and tool names.",
+    ),
+  limit: z
+    .number()
+    .optional()
+    .describe(
+      "Maximum number of results per page (default: 20)",
+    ),
+  cursor: z
+    .string()
+    .optional()
+    .describe(
+      "Pagination cursor from a previous response's nextCursor field.",
+    ),
+});
+
+export type ListAgentsInput = z.infer<typeof listAgentsToolInputSchema>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const listAgentsInputSchema = zodToJsonSchema(
+  listAgentsToolInputSchema as any,
+  { target: "openAi" }
+);

package/src/consumer.test.ts

@@ -663,6 +663,6 @@ describe("Registry Consumer — API Key Auth", () => {
 
     const agents = await consumer.browse(`http://localhost:${PORT}`);
     expect(agents.length).toBeGreaterThan(0);
-    expect(agents[0].path).toBe("@math");
+    expect(agents.some((a) => a.path === "@math")).toBe(true);
   });
 });

package/src/index.ts

@@ -136,6 +136,8 @@ export {
   detectAuth,
   resolveAuth,
   canSeeAgent,
+  canSeeTool,
+  getVisibleTools,
   hasAdminScope,
 } from "./server.js";
 export type {

package/src/key-manager.test.ts

@@ -118,6 +118,23 @@ describe("KeyManager", () => {
     expect(payload.exp - payload.iat).toBe(60);
   });
 
+  test("respects exp claim instead of default TTL", async () => {
+    const store = createMemoryKeyStore();
+    km = await createKeyManager({
+      store,
+      issuer: "http://test:3000",
+      tokenTtlSeconds: 300,
+      checkIntervalMs: 60_000,
+    });
+
+    const customExp = Math.floor(Date.now() / 1000) + 86400; // 24h from now
+    const token = await km.signJwt({ sub: "custom-exp", exp: customExp });
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString(),
+    );
+    expect(payload.exp).toBe(customExp);
+  });
+
   // ---- Rotation tests ----
 
   test("rotation: creates new key when threshold exceeded", async () => {

package/src/key-manager.ts

@@ -236,12 +236,18 @@ export async function createKeyManager(
 
     async signJwt(claims: Record<string, unknown>): Promise<string> {
       const key = getActiveKey();
-      return new SignJWT({ ...claims } as any)
+      let builder = new SignJWT({ ...claims } as any)
         .setProtectedHeader({ alg: ALG, kid: key.kid })
         .setIssuer(issuer)
-        .setIssuedAt()
-        .setExpirationTime(`${tokenTtlSeconds}s`)
-        .sign(key.privateKey);
+        .setIssuedAt();
+
+      if (claims.exp != null) {
+        builder = builder.setExpirationTime(claims.exp as number);
+      } else {
+        builder = builder.setExpirationTime(`${tokenTtlSeconds}s`);
+      }
+
+      return builder.sign(key.privateKey);
     },
 
     async rotate(): Promise<void> {

package/src/registry-consumer.ts

@@ -505,8 +505,8 @@ export interface RegistryConsumer {
   /** Discover a registry's configuration */
   discover(registryUrl: string): Promise<RegistryConfiguration>;
 
-  /** Browse agents from a specific registry (or all if url omitted) */
-  browse(registryUrl?: string): Promise<AgentListing[]>;
+  /** Browse agents from a specific registry (or all if url omitted), with optional BM25 search */
+  browse(registryUrl?: string, query?: string): Promise<AgentListing[]>;
 
   /** Inspect a specific agent — returns tools, auth requirements, resources */
   inspect(
@@ -573,15 +573,22 @@ export async function createRegistryConsumer(
     return configuration;
   }
 
-  // List agents from a single registry
+  // List agents from a single registry, with optional search query
   async function listFromRegistry(
     registry: ResolvedRegistry,
+    query?: string,
   ): Promise<AgentListing[]> {
     const configuration = await discover(registry.url, registry);
-    const listUrl =
+    let listUrl =
       configuration.agents_endpoint ??
       `${registry.url.replace(/\/$/, "")}/list`;
 
+    // Append search query if provided
+    if (query) {
+      const sep = listUrl.includes("?") ? "&" : "?";
+      listUrl += `${sep}q=${encodeURIComponent(query)}`;
+    }
+
     const headers = buildRegistryAuthHeaders(registry, options.token);
 
     const res = await fetchFn(listUrl, { headers });
@@ -591,7 +598,9 @@ export async function createRegistryConsumer(
       );
     }
 
-    const agents = (await res.json()) as Array<{
+    const body = (await res.json()) as any;
+    // Support both paginated { agents: [...] } and legacy array responses
+    const agents = (Array.isArray(body) ? body : body.agents) as Array<{
       path: string;
       description?: string;
       tools?: Array<{ name: string; description?: string }>;
@@ -700,7 +709,7 @@ export async function createRegistryConsumer(
     async list(): Promise<AgentListing[]> {
       // Collect from standard registries
       const registryResults = await Promise.allSettled(
-        resolvedRegistries.map(listFromRegistry),
+        resolvedRegistries.map((r) => listFromRegistry(r)),
       );
       const listings = registryResults.flatMap((r) =>
         r.status === "fulfilled" ? r.value : [],
@@ -799,14 +808,17 @@ export async function createRegistryConsumer(
       return discover(registryUrl, registry);
     },
 
-    async browse(registryUrl?: string): Promise<AgentListing[]> {
+    async browse(registryUrl?: string, query?: string): Promise<AgentListing[]> {
       // List agents from a specific registry, or all registries if not specified
       const targets = registryUrl
         ? resolvedRegistries.filter(
             (r) => r.url === registryUrl || r.name === registryUrl,
           )
         : resolvedRegistries;
-      const results = await Promise.allSettled(targets.map(listFromRegistry));
+      // Pass query to server for BM25 search
+      const results = await Promise.allSettled(
+        targets.map((t) => listFromRegistry(t, query)),
+      );
       return results.flatMap((r) =>
         r.status === "fulfilled" ? r.value : [],
       );