@slashfi/agents-sdk 0.77.0 → 0.77.2

package/src/config-store.ts

@@ -20,6 +20,7 @@
 import type { FsStore } from "./agent-definitions/config.js";
 import type {
   ConsumerConfig,
+  RefAddInput,
   RefEntry,
   RegistryEntry,
   ResolvedRef,
@@ -248,10 +249,10 @@ type AdkRefCallFn = keyof AdkAgentRegistry extends never
     <A extends AgentPath, T extends ToolsOf<A>>(name: A, tool: T, params: ParamsOf<A, T>) => Promise<CallAgentResponse>;
 
 export interface AdkRefApi {
-  add(entry: RefEntry): Promise<{ security: SecuritySchemeSummary | null }>;
+  add(entry: RefAddInput): Promise<{ security: SecuritySchemeSummary | null }>;
   remove(name: string): Promise<boolean>;
   list(): Promise<ResolvedRef[]>;
-  get(name: string): Promise<RefEntry | null>;
+  get(name: string): Promise<ResolvedRef | null>;
   update(name: string, updates: Partial<RefEntry>): Promise<boolean>;
   inspect(name: string, options?: { full?: boolean }): Promise<AgentInspection | null>;
   call: AdkRefCallFn;
@@ -332,11 +333,12 @@ function refName(entry: RefEntry): string {
  * Refs may be stored as `@foo` or `foo` depending on how they were added;
  * this ensures lookups work regardless of which form the caller uses.
  */
-function findRef(refs: RefEntry[], name: string): RefEntry | undefined {
+function findRef(refs: RefEntry[], name: string): ResolvedRef | undefined {
   const match = refs.find((r) => refName(r) === name);
-  if (match) return match;
+  if (match) return normalizeRef(match);
   const alt = name.startsWith("@") ? name.slice(1) : `@${name}`;
-  return refs.find((r) => refName(r) === alt);
+  const altMatch = refs.find((r) => refName(r) === alt);
+  return altMatch ? normalizeRef(altMatch) : undefined;
 }
 
 /**
@@ -502,7 +504,8 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     const config = await readConfig();
     const refs = (config.refs ?? []).map((r): RefEntry => {
       if (refName(r) !== name) return r;
-      return { ...r, config: { ...r.config, [key]: stored } };
+      const normalized = normalizeRef(r);
+      return { ...normalized, config: { ...normalized.config, [key]: stored } };
     });
     await writeConfig({ ...config, refs });
   }
@@ -815,7 +818,11 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     operation: string,
     params: Record<string, unknown>,
   ): Promise<T> {
-    const consumer = await buildConsumerForRef({ ref: "", sourceRegistry: { url: reg.url, agentPath: agent } } as RefEntry);
+    const consumer = await buildConsumerForRef({
+      ref: "",
+      name: "",
+      sourceRegistry: { url: reg.url, agentPath: agent },
+    });
     const resolved = consumer.registries().find((r) => r.url === reg.url);
     if (!resolved) throw new Error(`Registry ${reg.url} not resolvable for proxy forwarding`);
 
@@ -1498,11 +1505,22 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
   // ==========================================
 
   const ref: AdkRefApi = {
-    async add(entry: RefEntry): Promise<{ security: SecuritySchemeSummary | null }> {
+    async add(entryInput: RefAddInput): Promise<{ security: SecuritySchemeSummary | null }> {
       let security: SecuritySchemeSummary | null = null;
 
       const config = await readConfig();
       const hasRegistries = (config.registries ?? []).length > 0;
+      const name = entryInput.name ?? entryInput.ref;
+      let entry: RefEntry = { ...entryInput, name };
+
+      if ((config.refs ?? []).some((r) => refNameMatches(r, name))) {
+        throw new AdkError({
+          code: "REF_INVALID",
+          message: `Cannot add ref "${entry.ref}" as "${name}": a ref with that name already exists`,
+          hint: "Choose a different name, or remove/update the existing ref first.",
+          details: { ref: entry.ref, name },
+        });
+      }
 
       // Auto-infer scheme from context
       if (!entry.scheme) {
@@ -1599,9 +1617,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         }
       }
 
-      const name = refName(entry);
-      const refs = (config.refs ?? []).filter((r) => refName(r) !== name);
-      refs.push(entry);
+      const refs = [...(config.refs ?? []), entry];
       await writeConfig({ ...config, refs });
 
       return { security };
@@ -1622,7 +1638,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       return (config.refs ?? []).map(normalizeRef);
     },
 
-    async get(name: string): Promise<RefEntry | null> {
+    async get(name: string): Promise<ResolvedRef | null> {
       const config = await readConfig();
       return findRef(config.refs ?? [], name) ?? null;
     },
@@ -1636,14 +1652,21 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         found = true;
         const updated = { ...r };
         if (updates.url) updated.url = updates.url;
-        // Rename: prefer `name`, fall back to legacy `as`. When the
-        // caller passes `name`, clear the legacy `as` so the stored
-        // entry has one source of truth.
         if (updates.name !== undefined) {
+          const duplicate = config.refs?.some(
+            (candidate) =>
+              !refNameMatches(candidate, name) &&
+              refNameMatches(candidate, updates.name as string),
+          );
+          if (duplicate) {
+            throw new AdkError({
+              code: "REF_INVALID",
+              message: `Cannot rename ref "${name}" to "${updates.name}": a ref with that name already exists`,
+              hint: "Choose a different name, or remove/update the existing ref first.",
+              details: { name, newName: updates.name },
+            });
+          }
           updated.name = updates.name;
-          if (updated.as !== undefined) updated.as = undefined;
-        } else if (updates.as !== undefined) {
-          updated.as = updates.as;
         }
         if (updates.scheme) updated.scheme = updates.scheme;
         if (updates.config) updated.config = { ...updated.config, ...updates.config };
@@ -2120,7 +2143,8 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         // so callers can include extra context (tenant/user IDs).
         const statePayload = {
           ...opts?.stateContext,
-          ref: name,
+          ref: entry.ref,
+          name,
           ts: Date.now(),
         };
         const state = btoa(JSON.stringify(statePayload));

package/src/consumer.test.ts

@@ -111,7 +111,7 @@ describe("Registry Consumer E2E", () => {
       registries: [`http://localhost:${PORT}`],
       refs: [
         { ref: "@math" },
-        { ref: "@echo", as: "my-echo", config: { greeting: "hello" } },
+        { ref: "@echo", name: "my-echo", config: { greeting: "hello" } },
       ],
     };
 
@@ -151,12 +151,12 @@ describe("Registry Consumer E2E", () => {
     );
   });
 
-  test("multi-instance refs with as: alias", async () => {
+  test("multi-instance refs with name aliases", async () => {
     const config = {
       registries: [`http://localhost:${PORT}`],
       refs: [
-        { ref: "@echo", as: "echo-1", config: { prefix: "first" } },
-        { ref: "@echo", as: "echo-2", config: { prefix: "second" } },
+        { ref: "@echo", name: "echo-1", config: { prefix: "first" } },
+        { ref: "@echo", name: "echo-2", config: { prefix: "second" } },
       ],
     };
 
@@ -240,10 +240,10 @@ describe("normalizeRef", () => {
     });
   });
 
-  test("object ref with alias", () => {
+  test("object ref with name", () => {
     const result = normalizeRef({
       ref: "postgres",
-      as: "prod-db",
+      name: "prod-db",
       config: { url: "https://twin.slash.com/secrets/db" },
     });
     expect(result.ref).toBe("postgres");
@@ -253,7 +253,7 @@ describe("normalizeRef", () => {
     });
   });
 
-  test("object ref without alias uses ref as name", () => {
+  test("object ref without name uses ref as name", () => {
     const result = normalizeRef({ ref: "github" });
     expect(result.name).toBe("github");
   });

package/src/define-config.ts

@@ -16,8 +16,8 @@
  *   ],
  *   refs: [
  *     'notion',
- *     { ref: 'postgres', as: 'prod-db', config: { url: 'https://twin.slash.com/secrets/crdb-url' } },
- *     { ref: 'postgres', as: 'staging', config: { url: 'https://twin.slash.com/secrets/staging-url' } },
+ *     { ref: 'postgres', name: 'prod-db', config: { url: 'https://twin.slash.com/secrets/crdb-url' } },
+ *     { ref: 'postgres', name: 'staging', config: { url: 'https://twin.slash.com/secrets/staging-url' } },
  *   ],
  * });
  * ```
@@ -158,14 +158,10 @@ export type RefEntry = {
 
       /**
        * 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' }`).
+       * (call/remove/auth/update/…) to look up the entry. Add paths
+       * default this to `ref` when omitted.
        */
-      name?: string;
+      name: string;
 
       /** Connection scheme */
       scheme?: 'mcp' | 'https' | 'registry';
@@ -173,12 +169,6 @@ export type RefEntry = {
       /** Direct URL to the agent (e.g. https://mcp.notion.com/mcp) */
       url?: string;
 
-      /**
-       * @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) */
       config?: RefConfig;
 
@@ -189,6 +179,9 @@ export type RefEntry = {
       status?: 'active' | 'inactive' | 'error';
     };
 
+/** Input accepted by add paths. `name` defaults to `ref` when omitted. */
+export type RefAddInput = Omit<RefEntry, "name"> & { name?: string };
+
 // ============================================
 // Consumer Config
 // ============================================
@@ -259,15 +252,13 @@ export interface ResolvedConfig {
 /**
  * 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.
+ * Add paths default `name` to `ref` before writing. `normalizeRef` keeps the
+ * same invariant for in-memory/test configs that omit `name`.
  */
 export function normalizeRef(entry: RefEntry): ResolvedRef {
   return {
     ...entry,
-    name: entry.name ?? entry.as ?? entry.ref,
+    name: entry.name ?? entry.ref,
     config: entry.config ?? {},
   };
 }

package/src/index.ts

@@ -307,6 +307,7 @@ export type {
   RegistryAuth,
   RegistryEntry,
   RefConfig,
+  RefAddInput,
   RefEntry,
   ConsumerConfig,
   ResolvedRegistry,

package/src/materialize.ts

@@ -326,7 +326,7 @@ export async function syncAllRefs(
   for (const refEntry of refs) {
     const name = typeof refEntry === "string"
       ? refEntry
-      : (refEntry as any).as ?? (refEntry as any).ref ?? (refEntry as any).name;
+      : (refEntry as any).name ?? (refEntry as any).ref;
     if (!name) continue;
     if (opts?.filter && name !== opts.filter) continue;
     names.push(name);

package/src/ref-naming.test.ts

@@ -1,21 +1,16 @@
 /**
  * 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.
+ *   - `name` is the local identifier for every stored ref entry.
+ *   - Add paths default `name` to `ref` when omitted.
+ *   - `as` is not part of the stored or public ref shape.
+ *   - Adding a duplicate `name` is a loud error, not a replace.
  */
 
 import { describe, expect, test } from "bun:test";
 import { createAdkTools } from "./adk-tools";
 import type { FsStore } from "./agent-definitions/config";
-import { createAdk } from "./index";
+import { createAdk, createAgentRegistry, defineAgent } from "./index";
 import type { ToolContext } from "./types";
 
 function createMemoryFs(): FsStore {
@@ -42,7 +37,7 @@ async function readJson<T = unknown>(fs: FsStore, path: string): Promise<T> {
 // ─── RefEntry: name field on write ───────────────────────────────────
 
 describe("ref.add — identifier field", () => {
-  test("single-instance case stores only `ref` (no `name`/`as`)", async () => {
+  test("single-instance case stores explicit `name` equal to `ref`", async () => {
     const fs = createMemoryFs();
     const adk = createAdk(fs);
 
@@ -58,8 +53,7 @@ describe("ref.add — identifier field", () => {
     );
     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();
+    expect(parsed.refs[0].name).toBe("test-ref");
   });
 
   test("aliasing case stores both `ref` and `name`", async () => {
@@ -79,14 +73,40 @@ describe("ref.add — identifier field", () => {
     );
     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();
+  });
+
+  test("adding a duplicate name rejects instead of replacing", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+
+    await adk.ref.add({
+      ref: "notion",
+      name: "work",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
+    await expect(
+      adk.ref.add({
+        ref: "linear",
+        name: "work",
+        scheme: "mcp",
+        url: "http://localhost:12346",
+      }),
+    ).rejects.toThrow(/already exists/);
+
+    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
+      fs,
+      "consumer-config.json",
+    );
+    expect(parsed.refs).toHaveLength(1);
+    expect(parsed.refs[0].ref).toBe("notion");
   });
 });
 
 // ─── Lookup compatibility: new `name` field works end-to-end ─────────
 
-describe("ref lookup — name/as/ref resolution", () => {
+describe("ref lookup — name/ref resolution", () => {
   test("entries written with `name` are findable by `name`", async () => {
     const fs = createMemoryFs();
     const adk = createAdk(fs);
@@ -119,9 +139,7 @@ describe("ref lookup — name/as/ref resolution", () => {
     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.
+  test("entries without `name` normalize to `ref`", async () => {
     const fs = createMemoryFs();
     await fs.writeFile(
       "consumer-config.json",
@@ -129,7 +147,6 @@ describe("ref lookup — name/as/ref resolution", () => {
         refs: [
           {
             ref: "notion",
-            as: "work-notion",
             scheme: "mcp",
             url: "http://localhost:12345",
           },
@@ -138,56 +155,26 @@ describe("ref lookup — name/as/ref resolution", () => {
     );
     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");
+    const refs = await adk.ref.list();
+    expect(refs[0]?.name).toBe("notion");
+    expect(await adk.ref.get("notion")).not.toBeNull();
   });
 });
 
-// ─── ref.update: renaming clears the legacy `as` field ───────────────
+// ─── ref.update: name is the only rename field ───────────────────────
 
-describe("ref.update — name/as handling", () => {
-  test("passing `name` in updates sets name and clears legacy `as`", async () => {
+describe("ref.update — name handling", () => {
+  test("passing `name` in updates sets name", 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);
 
+    await adk.ref.add({
+      ref: "notion",
+      name: "old-alias",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+
     const ok = await adk.ref.update("old-alias", { name: "new-alias" });
     expect(ok).toBe(true);
 
@@ -196,35 +183,29 @@ describe("ref.update — name/as handling", () => {
       "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 () => {
+  test("renaming to an existing name rejects", 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);
+    await adk.ref.add({
+      ref: "notion",
+      name: "first",
+      scheme: "mcp",
+      url: "http://localhost:12345",
+    });
+    await adk.ref.add({
+      ref: "linear",
+      name: "second",
+      scheme: "mcp",
+      url: "http://localhost:12346",
+    });
 
-    const parsed = await readJson<{ refs: Array<Record<string, unknown>> }>(
-      fs,
-      "consumer-config.json",
+    await expect(adk.ref.update("first", { name: "second" })).rejects.toThrow(
+      /already exists/,
     );
-    expect(parsed.refs[0].as).toBe("second");
   });
 });
 
@@ -232,10 +213,8 @@ describe("ref.update — name/as handling", () => {
 //
 // 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.
+// depending on sampling. The `add` handler defaults the missing field so
+// both paths converge on the same stored `{ ref: 'X', name: 'X' }` entry.
 
 describe("ref tool — add operation defaults ref to name", () => {
   function makeRefTool(adk: ReturnType<typeof createAdk>) {
@@ -267,8 +246,7 @@ describe("ref tool — add operation defaults ref to name", () => {
     );
     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();
+    expect(parsed.refs[0].name).toBe("test-identity-ref");
 
     const entry = await adk.ref.get("test-identity-ref");
     expect(entry).not.toBeNull();
@@ -295,7 +273,7 @@ describe("ref tool — add operation defaults ref to name", () => {
       "consumer-config.json",
     );
     expect(parsed.refs[0].ref).toBe("test-identity-ref");
-    expect(parsed.refs[0].name).toBeUndefined();
+    expect(parsed.refs[0].name).toBe("test-identity-ref");
   });
 
   test("LLM sends `ref` + different `name` → stored as canonical + alias", async () => {
@@ -348,4 +326,99 @@ describe("ref tool — add operation defaults ref to name", () => {
     const raw = await fs.readFile("consumer-config.json");
     expect(raw).toBeNull();
   });
+
+  test("invalid add input returns schema details through registry call", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs);
+    const refTool = makeRefTool(adk);
+    const registry = createAgentRegistry();
+    registry.register(
+      defineAgent({
+        path: "@config",
+        entrypoint: "Config agent",
+        tools: [refTool],
+        visibility: "public",
+      }),
+    );
+
+    const response = await registry.call({
+      action: "execute_tool",
+      path: "@config",
+      tool: "ref",
+      params: {
+        operation: "add",
+        ref: "google-calendar",
+      },
+    });
+
+    expect(response.success).toBe(false);
+    if (response.success) throw new Error("expected invalid input error");
+    expect(response.code).toBe("TOOL_INPUT_INVALID");
+    expect(response.error).toContain("Invalid ref.add input");
+    expect(response.details?.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          path: "sourceRegistry",
+        }),
+      ]),
+    );
+    expect(response.details?.schema).toMatchObject({
+      anyOf: expect.any(Array),
+    });
+    expect(response.details?.operationSchema).toMatchObject({
+      type: "object",
+    });
+    expect(response.hint).toContain("details.schema");
+    expect(response.details).not.toHaveProperty("examples");
+    expect(JSON.stringify(response.details?.operationSchema)).toContain(
+      "sourceRegistry",
+    );
+  });
+});
+
+describe("ref tool — auth state hook", () => {
+  test("passes tool input to getAuthStateContext", async () => {
+    const authCalls: Array<{
+      name: string;
+      opts: { stateContext?: Record<string, unknown> };
+    }> = [];
+    const adk = {
+      ref: {
+        auth: async (
+          name: string,
+          opts: { stateContext?: Record<string, unknown> },
+        ) => {
+          authCalls.push({ name, opts });
+          return { complete: true };
+        },
+      },
+    } as unknown as ReturnType<typeof createAdk>;
+    const tools = createAdkTools({
+      resolveScope: () => adk,
+      hooks: {
+        getAuthStateContext: async (input) => ({
+          name: input.name,
+          ref: input.ref,
+        }),
+      },
+    });
+    const refTool = tools.find((t) => t.name === "ref");
+    if (!refTool) throw new Error("ref tool not found");
+
+    await refTool.execute(
+      {
+        operation: "auth",
+        ref: "google-gmail",
+        name: "work2",
+      },
+      {} as ToolContext,
+    );
+
+    expect(authCalls).toHaveLength(1);
+    expect(authCalls[0]?.name).toBe("work2");
+    expect(authCalls[0]?.opts.stateContext).toEqual({
+      ref: "google-gmail",
+      name: "work2",
+    });
+  });
 });

package/src/registry-consumer.ts

@@ -12,7 +12,7 @@
  *
  * const config = defineConfig({
  *   registries: ['https://registry.slash.com'],
- *   refs: ['notion', { ref: 'postgres', as: 'prod-db', config: { url: '...' } }],
+ *   refs: ['notion', { ref: 'postgres', name: 'prod-db', config: { url: '...' } }],
  * });
  *
  * const consumer = await createRegistryConsumer(config);