@slashfi/agents-sdk 0.73.0 → 0.75.0

package/src/define-config.ts

@@ -64,16 +64,30 @@ export type RefConfig = Record<string, unknown>;
 
 /** A ref entry — describes how to connect to an agent */
 export type RefEntry = {
-      /** Agent definition path (resolved from registries) */
+      /** Canonical agent path on the remote registry (e.g. `notion`, `linear`). */
       ref: string;
 
+      /**
+       * Local identifier for this ref. Used by all operations
+       * (call/remove/auth/update/…) to look up the entry. If omitted,
+       * the canonical `ref` string is used as the identifier — the
+       * common case "one local instance per agent" requires only
+       * `{ ref: 'notion', ... }`. Set `name` to a different value only
+       * when you need multiple local instances of the same remote
+       * agent (e.g. `{ ref: 'notion', name: 'work-notion' }`).
+       */
+      name?: string;
+
       /** Connection scheme */
       scheme?: 'mcp' | 'https' | 'registry';
 
       /** Direct URL to the agent (e.g. https://mcp.notion.com/mcp) */
       url?: string;
 
-      /** Local alias for this instance (required for multi-instance) */
+      /**
+       * @deprecated Use `name` instead. `as` is preserved for reading
+       * old consumer-config.json files; new writes emit `name`.
+       */
       as?: string;
 
       /** Per-instance config (headers, secrets, etc. — values support {{secret-uri}} templates) */
@@ -176,11 +190,18 @@ export interface ResolvedConfig {
 // Helpers
 // ============================================
 
-/** Normalize a ref entry to its full form */
+/**
+ * Normalize a ref entry to its full form.
+ *
+ * Local identifier resolution order: `entry.name` → `entry.as` (legacy)
+ * → `entry.ref` (canonical). This order makes the tool/API surface
+ * consistent with the `ref.add({ ref, name })` contract while still
+ * reading old `{ ref, as }` entries from pre-0.74 consumer-config.json.
+ */
 export function normalizeRef(entry: RefEntry): ResolvedRef {
   return {
     ...entry,
-    name: entry.as ?? entry.ref,
+    name: entry.name ?? entry.as ?? entry.ref,
     config: entry.config ?? {},
   };
 }

package/src/index.ts

@@ -324,6 +324,9 @@ export type {
   RegistryConsumer,
   RegistryConsumerOptions,
   RegistryConfiguration,
+  AgentBase,
+  AgentListEntry,
+  AgentInspection,
   AgentListing,
   SecretResolver,
 } from "./registry-consumer.js";

package/src/init.ts

@@ -185,7 +185,7 @@ export async function runInit(adk: Adk, targets: SkillTarget[]): Promise<void> {
       if (agents.length > 0) {
         console.log(`\n${agents.length} agent(s) available on ${DEFAULT_REGISTRY_URL}:\n`);
         for (const a of agents) {
-          const toolCount = a.tools?.length ?? 0;
+          const toolCount = a.toolCount ?? 0;
           console.log(`  ${a.path} (${toolCount} tools)`);
           if (a.description) console.log(`    ${a.description.slice(0, 120)}`);
           console.log();

package/src/ref-naming.test.ts

@@ -0,0 +1,351 @@
+/**
+ * Tests for the `ref` naming contract introduced in 0.74:
+ *
+ *   - `RefEntry` gains an optional `name?` field for the local identifier.
+ *     The legacy `as?` field still parses for backward compat.
+ *   - `normalizeRef` resolves the identifier as `name ?? as ?? ref`, so
+ *     all lookup paths (get, list, update, remove) accept entries written
+ *     in either shape.
+ *   - `createRefTool` (the adk-tools.ts MCP tool) drops `as` from its
+ *     schema and defaults `ref` to `name` on add, so "Add a ref called X"
+ *     via an LLM that picks either field lands on the same stored
+ *     `{ ref: 'X' }` entry.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createAdkTools } from "./adk-tools";
+import type { FsStore } from "./agent-definitions/config";
+import { createAdk } from "./index";
+import type { ToolContext } from "./types";
+
+function createMemoryFs(): FsStore {
+  const files = new Map<string, string>();
+  return {
+    async readFile(path: string) {
+      return files.get(path) ?? null;
+    },
+    async writeFile(path: string, content: string) {
+      files.set(path, content);
+    },
+  };
+}
+
+/** Read a known-present file and parse it as JSON, with typed assertion. */
+async function readJson<T = unknown>(fs: FsStore, path: string): Promise<T> {
+  const raw = await fs.readFile(path);
+  if (raw === null) {
+    throw new Error(`Expected ${path} to exist`);
+  }
+  return JSON.parse(raw) as T;
+}
+
+// ─── RefEntry: name field on write ───────────────────────────────────
+
+describe("ref.add — identifier field", () => {
+  test("single-instance case stores only `ref` (no `name`/`as`)", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "test-ref",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs).toHaveLength(1);
+    expect(parsed.refs[0].ref).toBe("test-ref");
+    expect(parsed.refs[0].name).toBeUndefined();
+    expect(parsed.refs[0].as).toBeUndefined();
+  });
+
+  test("aliasing case stores both `ref` and `name`", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("notion");
+    expect(parsed.refs[0].name).toBe("work-notion");
+    // Legacy `as` field is never emitted on new writes.
+    expect(parsed.refs[0].as).toBeUndefined();
+  });
+});
+
+// ─── Lookup compatibility: new `name` field works end-to-end ─────────
+
+describe("ref lookup — name/as/ref resolution", () => {
+  test("entries written with `name` are findable by `name`", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const entry = await adk.ref.get("work-notion");
+    expect(entry).not.toBeNull();
+    expect(entry?.ref).toBe("notion");
+  });
+
+  test("entries written with `name` return name field when listed", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work-notion",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    const refs = await adk.ref.list();
+    expect(refs).toHaveLength(1);
+    expect(refs[0]?.name).toBe("work-notion");
+  });
+
+  test("legacy entries written with `as` remain findable by `as`", async () => {
+    // Simulate a consumer-config.json produced by a pre-0.74 client that
+    // still writes the `as` field. The read path must still resolve it.
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "work-notion",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const entry = await adk.ref.get("work-notion");
+    expect(entry).not.toBeNull();
+    expect(entry?.ref).toBe("notion");
+    expect(entry?.as).toBe("work-notion");
+  });
+
+  test("when both `name` and `as` are present, `name` wins", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            name: "new-identifier",
+            as: "legacy-identifier",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const byNew = await adk.ref.get("new-identifier");
+    expect(byNew).not.toBeNull();
+    expect(byNew?.ref).toBe("notion");
+  });
+});
+
+// ─── ref.update: renaming clears the legacy `as` field ───────────────
+
+describe("ref.update — name/as handling", () => {
+  test("passing `name` in updates sets name and clears legacy `as`", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "old-alias",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const ok = await adk.ref.update("old-alias", { name: "new-alias" });
+    expect(ok).toBe(true);
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].name).toBe("new-alias");
+    expect(parsed.refs[0].as).toBeUndefined();
+    expect(parsed.refs[0].ref).toBe("notion");
+  });
+
+  test("passing only `as` updates the legacy field (pre-0.74 callers)", async () => {
+    const fs = createMemoryFs();
+    await fs.writeFile(
+      "consumer-config.json",
+      JSON.stringify({
+        refs: [
+          {
+            ref: "notion",
+            as: "first",
+            scheme: "mcp",
+            url: "http://localhost:12345",
+          },
+        ],
+      }),
+    );
+    const adk = createAdk(fs);
+
+    const ok = await adk.ref.update("first", { as: "second" });
+    expect(ok).toBe(true);
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].as).toBe("second");
+  });
+});
+
+// ─── Tool surface: the LLM non-determinism scenario ──────────────────
+//
+// When an LLM is prompted with "Add a ref called X", its tool-call
+// arguments can land on either `{ ref: 'X', … }` or `{ name: 'X', … }`
+// depending on sampling. Pre-0.74, the former stored `{ ref: 'X' }`
+// and the latter stored `{ ref: undefined }` (broken lookup). The
+// `add` handler now defaults `ref ??= name` so both paths converge on
+// the same stored entry.
+
+describe("ref tool — add operation defaults ref to name", () => {
+  function makeRefTool(adk: ReturnType<typeof createAdk>) {
+    const tools = createAdkTools({ resolveScope: () => adk });
+    const ref = tools.find((t) => t.name === "ref");
+    if (!ref) throw new Error("ref tool not found");
+    return ref;
+  }
+
+  test("LLM sends only `name` → ref defaults to name, entry is findable", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        name: "test-identity-ref",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs).toHaveLength(1);
+    expect(parsed.refs[0].ref).toBe("test-identity-ref");
+    // name was not stored because it equals ref (single-instance case)
+    expect(parsed.refs[0].name).toBeUndefined();
+
+    const entry = await adk.ref.get("test-identity-ref");
+    expect(entry).not.toBeNull();
+  });
+
+  test("LLM sends only `ref` → same resulting entry", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        ref: "test-identity-ref",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("test-identity-ref");
+    expect(parsed.refs[0].name).toBeUndefined();
+  });
+
+  test("LLM sends `ref` + different `name` → stored as canonical + alias", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await refTool.execute(
+      {
+        operation: "add",
+        ref: "notion",
+        name: "work-notion",
+        scheme: "mcp",
+        url: "http://127.0.0.1:33469",
+      },
+      ctx,
+    );
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs[0].ref).toBe("notion");
+    expect(parsed.refs[0].name).toBe("work-notion");
+
+    // The entry is findable by the local identifier (name), not the
+    // canonical ref.
+    expect(await adk.ref.get("work-notion")).not.toBeNull();
+  });
+
+  test("LLM omits both `ref` and `name` → loud error (no silent bad write)", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+
+    const ctx = {} as ToolContext;
+    await expect(
+      refTool.execute(
+        {
+          operation: "add",
+          scheme: "mcp",
+          url: "http://127.0.0.1:33469",
+        },
+        ctx,
+      ),
+    ).rejects.toThrow(/ref|name/);
+
+    // Nothing got written.
+    const raw = await fs.readFile("consumer-config.json");
+    expect(raw).toBeNull();
+  });
+});

package/src/registry-consumer.ts

@@ -209,21 +209,14 @@ export interface RegistryConfiguration {
   supported_grant_types?: string[];
 }
 
-/** An agent definition as listed by a registry */
-export interface AgentListing {
+/** Fields common to every agent reference a registry can return. */
+export interface AgentBase {
   /** Agent path (e.g., '@notion') */
   path: string;
   /** Description */
   description?: string;
   /** Publisher (registry name) */
   publisher: string;
-  /** Tools available */
-  tools?: Array<{
-    name: string;
-    description?: string;
-  }>;
-  /** Whether it requires auth */
-  requiresAuth?: boolean;
   /** Security scheme summary (machine-readable auth type) */
   security?: SecuritySchemeSummary;
   /** Available resources (e.g., AUTH.md) */
@@ -232,7 +225,39 @@ export interface AgentListing {
     name?: string;
     mimeType?: string;
   }>;
-  /** Slim tool summaries (when describe_tools called without full: true) */
+}
+
+/**
+ * Lightweight agent entry returned by `list_agents` / `consumer.list()` /
+ * `consumer.browse()` / `consumer.available()`. Registries emit a `toolCount`
+ * instead of the full `tools` array to keep listings small; call `inspect()`
+ * to get the per-tool details.
+ */
+export interface AgentListEntry extends AgentBase {
+  /** Number of tools this agent exposes */
+  toolCount?: number;
+  /** Whether the agent requires auth (populated only for direct MCP/HTTPS refs) */
+  requiresAuth?: boolean;
+  /** Integration config if applicable */
+  integration?: {
+    provider: string;
+    displayName: string;
+    category?: string;
+  };
+}
+
+/**
+ * Full agent detail returned by `describe_tools` / `consumer.inspect()`.
+ * Carries the actual tool definitions (or slim summaries) and extra context
+ * the listing endpoint omits.
+ */
+export interface AgentInspection extends AgentBase {
+  /** Full tool details (returned when `full: true`) */
+  tools?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  /** Slim tool summaries (returned when `full` is not set) */
   toolSummaries?: Array<{
     name: string;
     description: string;
@@ -242,16 +267,16 @@ export interface AgentListing {
   context?: string;
   /** Upstream MCP/API URL for direct connections */
   upstream?: string;
-  /** Integration config if applicable */
-  integration?: {
-    provider: string;
-    displayName: string;
-    category?: string;
-  };
+  /** Agent mode (redirect | proxy | api) */
+  mode?: string;
 }
 
+/** @deprecated Prefer `AgentListEntry` (for listings) or `AgentInspection` (for inspect results). */
+export type AgentListing = AgentListEntry | AgentInspection;
+
 /** Raw agent entry returned by the list_agents MCP tool (before normalization). */
-type ListAgentsEntry = Omit<AgentListing, "publisher" | "tools"> & {
+type ListAgentsEntry = Omit<AgentListEntry, "publisher"> & {
+  /** Legacy field — older registries emitted `tools` instead of `toolCount`. */
   tools?: Array<{ name: string; description?: string } | string>;
 };
 
@@ -333,7 +358,7 @@ async function listFromMcpServer(
   url: string,
   auth: { token?: string; headers?: Record<string, string> },
   fetchFn: FetchFn,
-): Promise<AgentListing[]> {
+): Promise<AgentListEntry[]> {
   const serverUrl = url.replace(/\/$/, "");
 
   const headers: Record<string, string> = {
@@ -383,12 +408,13 @@ async function listFromMcpServer(
 
   const serverName = initResult?.serverInfo?.name ?? new URL(serverUrl).hostname;
 
-  // Return as a single agent listing with all tools
+  // Return as a single agent listing — toolCount keeps listings lightweight;
+  // callers that need per-tool detail should use `inspect()`.
   return [{
     path: serverName,
     description: `MCP server at ${serverUrl}`,
     publisher: serverName,
-    tools: toolsResult?.tools ?? [],
+    toolCount: toolsResult?.tools?.length ?? 0,
     requiresAuth: false,
   }];
 }
@@ -517,16 +543,14 @@ async function callMcpTool(
  * Returns a single generic 'call' tool since we can't auto-discover REST endpoints
  * without an OpenAPI spec.
  */
-function listFromHttpsApi(url: string): AgentListing[] {
+function listFromHttpsApi(url: string): AgentListEntry[] {
   const hostname = new URL(url).hostname;
   return [{
     path: hostname,
     description: `REST API at ${url}`,
     publisher: hostname,
-    tools: [{
-      name: "call",
-      description: "Make an HTTP request to the API. Params: method, path, body, headers.",
-    }],
+    // Single generic `call` tool — callers can use `inspect()` for details.
+    toolCount: 1,
     requiresAuth: false,
   }];
 }
@@ -598,7 +622,7 @@ export interface RegistryConsumerOptions {
 
 export interface RegistryConsumer {
   /** List all available agents across all connected registries */
-  list(): Promise<AgentListing[]>;
+  list(): Promise<AgentListEntry[]>;
 
   /** List configured refs (from the consumer's config) */
   refs(): ResolvedRef[];
@@ -617,14 +641,14 @@ export interface RegistryConsumer {
   discover(registryUrl: string): Promise<RegistryConfiguration>;
 
   /** Browse agents from a specific registry (or all if url omitted), with optional BM25 search */
-  browse(registryUrl?: string, query?: string): Promise<AgentListing[]>;
+  browse(registryUrl?: string, query?: string): Promise<AgentListEntry[]>;
 
   /** Inspect a specific agent — returns tools, auth requirements, resources */
   inspect(
     agentPath: string,
     registryUrl?: string,
     options?: { full?: boolean },
-  ): Promise<AgentListing | null>;
+  ): Promise<AgentInspection | null>;
 
   /** Resolve a secret URL to its value */
   resolveSecret(url: string): Promise<string>;
@@ -644,7 +668,7 @@ export interface RegistryConsumer {
   index(): ResolvedConfig;
 
   /** Diff: what's available vs what's configured */
-  available(): Promise<AgentListing[]>;
+  available(): Promise<AgentListEntry[]>;
 }
 
 /**
@@ -693,7 +717,7 @@ export async function createRegistryConsumer(
   async function listFromRegistry(
     registry: ResolvedRegistry,
     query?: string,
-  ): Promise<AgentListing[]> {
+  ): Promise<AgentListEntry[]> {
     const mcpUrl = registry.url.replace(/\/$/, "");
 
     const response = await callMcpTool(
@@ -715,15 +739,15 @@ export async function createRegistryConsumer(
     ) as ListAgentsResponse;
     const agents = data.agents ?? [];
 
-    return agents.map((agent) => ({
-      ...agent,
-      ...agent,
-      // Normalize tools: strings become { name } objects
-      tools: agent.tools?.map((t) =>
-        typeof t === "string" ? { name: t } : t,
-      ),
-      publisher: registry.publisher,
-    }));
+    return agents.map((agent) => {
+      // Legacy registries may still emit `tools` instead of `toolCount`; back-fill.
+      const { tools, toolCount, ...rest } = agent;
+      return {
+        ...rest,
+        publisher: registry.publisher,
+        toolCount: toolCount ?? tools?.length,
+      };
+    });
   }
 
   // Send any call_agent request through a registry's MCP endpoint
@@ -821,7 +845,7 @@ export async function createRegistryConsumer(
 
   // Build the consumer
   const consumer: RegistryConsumer = {
-    async list(): Promise<AgentListing[]> {
+    async list(): Promise<AgentListEntry[]> {
       // Collect from standard registries
       const registryResults = await Promise.allSettled(
         resolvedRegistries.map((r) => listFromRegistry(r)),
@@ -925,7 +949,7 @@ export async function createRegistryConsumer(
       return discover(registryUrl, registry);
     },
 
-    async browse(registryUrl?: string, query?: string): Promise<AgentListing[]> {
+    async browse(registryUrl?: string, query?: string): Promise<AgentListEntry[]> {
       // List agents from a specific registry, or all registries if not specified
       const targets = registryUrl
         ? resolvedRegistries.filter(
@@ -945,7 +969,7 @@ export async function createRegistryConsumer(
       agentPath: string,
       registryUrl?: string,
       options?: { full?: boolean },
-    ): Promise<AgentListing | null> {
+    ): Promise<AgentInspection | null> {
       const targetRegistries = registryUrl
         ? resolvedRegistries.filter((r) => r.url === registryUrl || r.name === registryUrl)
         : resolvedRegistries;
@@ -988,7 +1012,7 @@ export async function createRegistryConsumer(
             context: data.context,
             ...(data.upstream && { upstream: data.upstream }),
             ...(data.mode && { mode: data.mode }),
-          } as AgentListing;
+          } as AgentInspection;
         }),
       );
 
@@ -1018,7 +1042,7 @@ export async function createRegistryConsumer(
       };
     },
 
-    async available(): Promise<AgentListing[]> {
+    async available(): Promise<AgentListEntry[]> {
       const all = await consumer.list();
       const configuredRefs = new Set(resolvedRefs.map((r) => r.ref));
       return all.filter((a) => !configuredRefs.has(a.path));