@slashfi/agents-sdk 0.73.0 → 0.74.0

package/dist/define-config.js

@@ -25,11 +25,18 @@
 // ============================================
 // 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) {
     return {
         ...entry,
-        name: entry.as ?? entry.ref,
+        name: entry.name ?? entry.as ?? entry.ref,
         config: entry.config ?? {},
     };
 }

package/dist/define-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAuJH,+CAA+C;AAC/C,UAAU;AACV,+CAA+C;AAE/C,6CAA6C;AAC7C,MAAM,UAAU,YAAY,CAAC,KAAe;IAC1C,OAAO;QACL,GAAG,KAAK;QACR,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG;QAC3B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,iBAAiB,CAC/B,KAA6B;IAE7B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO;YACL,GAAG,EAAE,KAAK;YACV,IAAI,EAAE,GAAG,CAAC,QAAQ;YAClB,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACrC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACvB,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO;QACL,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;QACpC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC;AAED,mCAAmC;AACnC,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAE5D,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,0CAA0C;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC"}
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAqKH,+CAA+C;AAC/C,UAAU;AACV,+CAA+C;AAE/C;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAe;IAC1C,OAAO;QACL,GAAG,KAAK;QACR,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,GAAG;QACzC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,iBAAiB,CAC/B,KAA6B;IAE7B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO;YACL,GAAG,EAAE,KAAK;YACV,IAAI,EAAE,GAAG,CAAC,QAAQ;YAClB,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACrC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACvB,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO;QACL,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;QACpC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC;AAED,mCAAmC;AACnC,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAE5D,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,0CAA0C;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC"}

package/dist/validate.d.ts

@@ -16,13 +16,13 @@ export declare const SerializedToolSchema: z.ZodObject<{
     inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     outputSchema: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     description: string;
+    name: string;
     inputSchema: Record<string, unknown>;
     outputSchema?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
-    name: string;
     description: string;
+    name: string;
     inputSchema?: Record<string, unknown> | undefined;
     outputSchema?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
@@ -50,13 +50,13 @@ export declare const SerializedAgentDefinitionSchema: z.ZodObject<{
         inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         outputSchema: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
     }, "strip", z.ZodTypeAny, {
-        name: string;
         description: string;
+        name: string;
         inputSchema: Record<string, unknown>;
         outputSchema?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
-        name: string;
         description: string;
+        name: string;
         inputSchema?: Record<string, unknown> | undefined;
         outputSchema?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }>, "many">;
@@ -86,13 +86,13 @@ export declare const SerializedAgentDefinitionSchema: z.ZodObject<{
         inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         outputSchema: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
     }, "strip", z.ZodTypeAny, {
-        name: string;
         description: string;
+        name: string;
         inputSchema: Record<string, unknown>;
         outputSchema?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
-        name: string;
         description: string;
+        name: string;
         inputSchema?: Record<string, unknown> | undefined;
         outputSchema?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }>, "many">;
@@ -122,13 +122,13 @@ export declare const SerializedAgentDefinitionSchema: z.ZodObject<{
         inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         outputSchema: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
     }, "strip", z.ZodTypeAny, {
-        name: string;
         description: string;
+        name: string;
         inputSchema: Record<string, unknown>;
         outputSchema?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
-        name: string;
         description: string;
+        name: string;
         inputSchema?: Record<string, unknown> | undefined;
         outputSchema?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
     }>, "many">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slashfi/agents-sdk",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "author": "Slash Financial",
   "repository": {
     "type": "git",

package/src/adk-tools.ts

@@ -17,10 +17,10 @@
  * ```
  */
 
-import { defineTool } from "./define.js";
-import type { ToolDefinition, ToolContext } from "./types.js";
 import type { Adk } from "./config-store.js";
 import type { RefEntry, RegistryEntry } from "./define-config.js";
+import { defineTool } from "./define.js";
+import type { ToolContext, ToolDefinition } from "./types.js";
 
 export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
   /**
@@ -33,7 +33,9 @@ export interface AdkToolsHooks<TCtx extends ToolContext = ToolContext> {
    * getAuthStateContext: async (ctx) => ({ tid: ctx.tenantId, uid: ctx.userId })
    * ```
    */
-  getAuthStateContext?: (ctx: TCtx) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  getAuthStateContext?: (
+    ctx: TCtx,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
 
 export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
@@ -48,72 +50,184 @@ export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
   hooks?: AdkToolsHooks<TCtx>;
 }
 
-export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: CreateAdkToolsOptions<TCtx>): ToolDefinition<TCtx>[] {
+export function createAdkTools<TCtx extends ToolContext = ToolContext>(
+  opts: CreateAdkToolsOptions<TCtx>,
+): ToolDefinition<TCtx>[] {
   const { resolveScope, scopes } = opts;
 
   const scopeSchema = scopes
-    ? { type: "string" as const, enum: scopes, description: "Config scope to operate on" }
+    ? {
+        type: "string" as const,
+        enum: scopes,
+        description: "Config scope to operate on",
+      }
     : { type: "string" as const, description: "Config scope (optional)" };
 
   const refTool = defineTool({
     name: "ref",
     description:
-      "Manage agent refs. Operations: add, remove, list, update, inspect, call, auth, auth-status, refresh-token, resources, read.",
+      "Manage agent refs. Operations: add, remove, list, update, inspect, call, auth, auth-status, refresh-token, resources, read. For `add`, supply `ref` (canonical agent path, e.g. 'notion') and optionally `name` for a local alias; either one uniquely identifies the ref. For every other operation, pass `name` (the local identifier you used on add — defaults to `ref` when you didn't set it explicitly).",
     inputSchema: {
       type: "object" as const,
       properties: {
         operation: {
           type: "string",
-          enum: ["add", "remove", "list", "update", "inspect", "call", "auth", "auth-status", "refresh-token", "resources", "read"],
+          enum: [
+            "add",
+            "remove",
+            "list",
+            "update",
+            "inspect",
+            "call",
+            "auth",
+            "auth-status",
+            "refresh-token",
+            "resources",
+            "read",
+          ],
         },
         scope: scopeSchema,
-        ref: { type: "string" },
-        name: { type: "string" },
-        scheme: { type: "string" },
-        url: { type: "string" },
-        as: { type: "string" },
-        sourceRegistry: { type: "object", properties: { url: { type: "string" }, agentPath: { type: "string" } } },
-        config: { type: "object" },
-        tool: { type: "string" },
-        params: { type: "object" },
-        full: { type: "boolean" },
-        uris: { type: "array", items: { type: "string" } },
-        apiKey: { type: "string" },
-        credentials: { type: "object", description: "Key-value map of credential fields (keys match field names from auth challenge)" },
+        ref: {
+          type: "string",
+          description:
+            "Canonical agent path on the remote registry (e.g. 'notion', 'linear', 'github'). Used by `add` to identify which agent definition to connect to. Other operations use `name` instead. If you call `add` with only `name` and no `ref`, `ref` defaults to `name`.",
+        },
+        name: {
+          type: "string",
+          description:
+            "Local identifier for this ref, used by all operations except `add` to look up the entry. On `add`, `name` is optional — it only needs to differ from `ref` when you want multiple local instances of the same agent (e.g. `{ ref: 'notion', name: 'work-notion' }`). Omit it and the ref is identified by its canonical path.",
+        },
+        scheme: {
+          type: "string",
+          description:
+            "Connection scheme: 'mcp' (direct MCP server), 'https' (REST proxy), or 'registry' (discovered via a registry). Auto-inferred from `url` or `sourceRegistry` when omitted.",
+        },
+        url: {
+          type: "string",
+          description:
+            "Direct URL to the agent (e.g. https://mcp.notion.com/mcp). Required for 'mcp' and 'https' schemes.",
+        },
+        sourceRegistry: {
+          type: "object",
+          properties: {
+            url: { type: "string" },
+            agentPath: { type: "string" },
+          },
+          description:
+            "When scheme is 'registry', the registry + agent path to resolve through.",
+        },
+        config: {
+          type: "object",
+          description:
+            "Per-instance config passed to the agent (headers, credentials, etc.). Supports `{{secret-uri}}` templates.",
+        },
+        tool: {
+          type: "string",
+          description:
+            "For `call` operation: the tool name on the ref to invoke.",
+        },
+        params: {
+          type: "object",
+          description: "For `call` operation: arguments to pass to the tool.",
+        },
+        full: {
+          type: "boolean",
+          description:
+            "For `inspect` operation: include full agent definition.",
+        },
+        uris: {
+          type: "array",
+          items: { type: "string" },
+          description: "For `read` operation: the resource URIs to read.",
+        },
+        apiKey: {
+          type: "string",
+          description: "For `auth` operation: pre-provisioned API key.",
+        },
+        credentials: {
+          type: "object",
+          description:
+            "For `auth` operation: key-value map of credential fields (keys match field names from the auth challenge).",
+        },
       },
       required: ["operation"],
     },
     execute: async (input: Record<string, unknown>, ctx) => {
-      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const adk = await resolveScope(
+        input.scope as string | undefined,
+        ctx as TCtx,
+      );
       const op = input.operation as string;
 
       switch (op) {
         case "add": {
-          const entry: Record<string, unknown> = { ref: input.ref };
+          // Accept `ref` or `name` (or both). If only one is given, the
+          // other defaults to it. This matches the "Add a ref called X"
+          // natural-language phrasing — LLMs that pick `name` get the
+          // same behavior as ones that pick `ref`, eliminating
+          // non-determinism on the identifier field. Throws when both
+          // are missing, so misuse is loud instead of silently storing
+          // `{ ref: undefined }`.
+          const refValue = (input.ref ?? input.name) as string | undefined;
+          if (!refValue) {
+            throw new Error(
+              "ref.add: must supply either 'ref' (canonical agent path) or 'name' (local identifier); both may be the same string for the common single-instance case.",
+            );
+          }
+          const entry: Record<string, unknown> = { ref: refValue };
           if (input.scheme) entry.scheme = input.scheme;
           if (input.url) entry.url = input.url;
-          if (input.as) entry.as = input.as;
+          // Only store `name` when it's meaningfully different from
+          // `ref` (the multi-instance aliasing case). Avoids a
+          // redundant `{ name: 'notion', ref: 'notion' }` stored shape.
+          const nameValue = input.name as string | undefined;
+          if (nameValue && nameValue !== refValue) {
+            entry.name = nameValue;
+          }
           if (input.sourceRegistry) entry.sourceRegistry = input.sourceRegistry;
           if (input.config) entry.config = input.config;
           const { security } = await adk.ref.add(entry as unknown as RefEntry);
-          return { added: true, ref: input.ref, name: (input.as ?? input.ref) as string, security };
+          return {
+            added: true,
+            ref: refValue,
+            name: (entry.name ?? refValue) as string,
+            security,
+          };
         }
         case "remove":
           return { removed: await adk.ref.remove(input.name as string) };
         case "list":
           return { refs: await adk.ref.list() };
         case "update":
-          return { updated: await adk.ref.update(input.name as string, input as unknown as Partial<RefEntry>) };
+          return {
+            updated: await adk.ref.update(
+              input.name as string,
+              input as unknown as Partial<RefEntry>,
+            ),
+          };
         case "inspect":
-          return await adk.ref.inspect(input.name as string, { full: input.full as boolean });
+          return await adk.ref.inspect(input.name as string, {
+            full: input.full as boolean,
+          });
         case "call":
-          return await adk.ref.call(input.name as string, input.tool as string, input.params as Record<string, unknown>);
+          return await adk.ref.call(
+            input.name as string,
+            input.tool as string,
+            input.params as Record<string, unknown>,
+          );
         case "auth": {
-          const authOpts: { apiKey?: string; credentials?: Record<string, string>; stateContext?: Record<string, unknown> } = {};
+          const authOpts: {
+            apiKey?: string;
+            credentials?: Record<string, string>;
+            stateContext?: Record<string, unknown>;
+          } = {};
           if (input.apiKey) authOpts.apiKey = input.apiKey as string;
-          if (input.credentials) authOpts.credentials = input.credentials as Record<string, string>;
+          if (input.credentials)
+            authOpts.credentials = input.credentials as Record<string, string>;
           if (opts.hooks?.getAuthStateContext) {
-            authOpts.stateContext = await opts.hooks.getAuthStateContext(ctx as TCtx);
+            authOpts.stateContext = await opts.hooks.getAuthStateContext(
+              ctx as TCtx,
+            );
           }
           return await adk.ref.auth(input.name as string, authOpts);
         }
@@ -124,7 +238,10 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
         case "resources":
           return await adk.ref.resources(input.name as string);
         case "read":
-          return await adk.ref.read(input.name as string, input.uris as string[]);
+          return await adk.ref.read(
+            input.name as string,
+            input.uris as string[],
+          );
         default:
           throw new Error(`Unknown ref operation: ${op}`);
       }
@@ -140,7 +257,15 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
       properties: {
         operation: {
           type: "string",
-          enum: ["add", "remove", "list", "update", "browse", "inspect", "test"],
+          enum: [
+            "add",
+            "remove",
+            "list",
+            "update",
+            "browse",
+            "inspect",
+            "test",
+          ],
         },
         scope: scopeSchema,
         url: { type: "string" },
@@ -152,12 +277,18 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
       required: ["operation"],
     },
     execute: async (input: Record<string, unknown>, ctx) => {
-      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const adk = await resolveScope(
+        input.scope as string | undefined,
+        ctx as TCtx,
+      );
       const op = input.operation as string;
 
       switch (op) {
         case "add": {
-          const entry: Record<string, unknown> = { url: input.url, name: input.name };
+          const entry: Record<string, unknown> = {
+            url: input.url,
+            name: input.name,
+          };
           if (input.auth) entry.auth = input.auth;
           if (input.headers) entry.headers = input.headers;
           await adk.registry.add(entry as unknown as RegistryEntry);
@@ -173,10 +304,20 @@ export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: Cre
           if (input.name !== undefined) updates.name = input.name;
           if (input.auth) updates.auth = input.auth;
           if (input.headers) updates.headers = input.headers;
-          return { updated: await adk.registry.update(input.name as string, updates as unknown as Partial<RegistryEntry>) };
+          return {
+            updated: await adk.registry.update(
+              input.name as string,
+              updates as unknown as Partial<RegistryEntry>,
+            ),
+          };
         }
         case "browse":
-          return { agents: await adk.registry.browse(input.name as string, input.query as string) };
+          return {
+            agents: await adk.registry.browse(
+              input.name as string,
+              input.query as string,
+            ),
+          };
         case "inspect":
           return await adk.registry.inspect(input.name as string);
         case "test":

package/src/config-store.ts

@@ -976,7 +976,15 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         found = true;
         const updated = { ...r };
         if (updates.url) updated.url = updates.url;
-        if (updates.as) updated.as = updates.as;
+        // 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) {
+          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 };
         if (updates.sourceRegistry) updated.sourceRegistry = updates.sourceRegistry;

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 ?? {},
   };
 }