@slashfi/agents-sdk 0.76.0 → 0.77.1

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' } },
  *   ],
  * });
  * ```
@@ -58,6 +58,49 @@ export interface RegistryProxy {
   agent?: string;
 }
 
+/**
+ * OAuth state captured after `adk registry auth` completes a dynamic-client
+ * registration + authorization-code flow against a registry. Stored alongside
+ * `auth.token` so the access token can be refreshed without re-prompting the
+ * user. The `auth.token` slot holds the current access token; everything
+ * needed to refresh it lives here.
+ */
+export interface RegistryOAuthState {
+  /** Token endpoint used for code exchange / refresh. */
+  tokenEndpoint: string;
+  /** Client ID issued by dynamic client registration (RFC 7591). */
+  clientId: string;
+  /** Client secret from dynamic registration, when the server issued one. */
+  clientSecret?: string;
+  /** Refresh token returned by the token endpoint, if any. */
+  refreshToken?: string;
+  /** Absolute expiry (ISO 8601) derived from `expires_in` at exchange time. */
+  expiresAt?: string;
+  /** Scopes the access token was granted for. */
+  scopes?: string[];
+}
+
+/**
+ * Captured auth challenge from a registry that rejected an unauthenticated
+ * probe (RFC 6750 `WWW-Authenticate` + RFC 9728 protected-resource metadata).
+ * When present on a `RegistryEntry`, the registry has been seen to require
+ * credentials and ref ops will fail until `adk registry auth` is run.
+ */
+export interface RegistryAuthRequirement {
+  /** Auth scheme advertised in `WWW-Authenticate` (e.g. `Bearer`). */
+  scheme?: string;
+  /** Realm advertised in `WWW-Authenticate`. */
+  realm?: string;
+  /** RFC 9728 `resource_metadata` URL parsed from the challenge. */
+  resourceMetadataUrl?: string;
+  /** Authorization servers from the protected-resource metadata. */
+  authorizationServers?: string[];
+  /** Scopes supported by the resource. */
+  scopes?: string[];
+  /** Bearer-methods advertised by the resource (`header`, `body`, `query`). */
+  bearerMethodsSupported?: string[];
+}
+
 /** A registry endpoint the consumer connects to */
 export interface RegistryEntry {
   /** Registry URL (e.g., 'https://registry.slash.com') */
@@ -84,6 +127,21 @@ export interface RegistryEntry {
    * running locally. See {@link RegistryProxy}.
    */
   proxy?: RegistryProxy;
+
+  /**
+   * Populated by `adk registry add` when the probe returned 401. Cleared
+   * by `adk registry auth`. Registry ops refuse to run while this is set
+   * and no usable auth credentials are configured.
+   */
+  authRequirement?: RegistryAuthRequirement;
+
+  /**
+   * OAuth lifecycle state — refresh token, client credentials from dynamic
+   * registration, token endpoint, expiry. Populated by `adk registry auth`
+   * when the flow went through OAuth; absent for manually-supplied bearer
+   * tokens.
+   */
+  oauth?: RegistryOAuthState;
 }
 
 // ============================================
@@ -100,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';
@@ -115,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;
 
@@ -131,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
 // ============================================
@@ -201,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/mcp-client.ts

@@ -14,6 +14,8 @@
  */
 
 import { generatePkcePair } from "./pkce.js";
+import type { RegistryAuthRequirement } from "./define-config.js";
+import type { FetchFn } from "./fetch-types.js";
 
 // ============================================
 // Types
@@ -239,3 +241,122 @@ export async function refreshAccessToken(
     expiresIn: data.expires_in as number | undefined,
   };
 }
+
+// ============================================
+// Registry Auth Probe (RFC 6750 + RFC 9728)
+// ============================================
+
+/**
+ * Parse a `WWW-Authenticate` header of the form
+ *   `Bearer realm="x", resource_metadata="https://..."`
+ * Returns the scheme and any `key="value"` params. Tolerant of
+ * single-value headers and missing params.
+ */
+export function parseWwwAuthenticate(
+  header: string,
+): { scheme: string; params: Record<string, string> } {
+  const spaceIdx = header.indexOf(" ");
+  const scheme = (spaceIdx === -1 ? header : header.slice(0, spaceIdx)).trim();
+  const rest = spaceIdx === -1 ? "" : header.slice(spaceIdx + 1);
+  const params: Record<string, string> = {};
+  for (const match of rest.matchAll(/([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g)) {
+    params[match[1]!.toLowerCase()] = match[2]!;
+  }
+  return { scheme, params };
+}
+
+/** RFC 9728 protected-resource metadata. */
+export interface ProtectedResourceMetadata {
+  resource: string;
+  authorization_servers?: string[];
+  bearer_methods_supported?: string[];
+  scopes_supported?: string[];
+  resource_documentation?: string;
+}
+
+/** Fetch RFC 9728 metadata. Returns null on any failure. */
+export async function discoverProtectedResourceMetadata(
+  metadataUrl: string,
+  fetchFn: FetchFn = globalThis.fetch,
+): Promise<ProtectedResourceMetadata | null> {
+  try {
+    const res = await fetchFn(metadataUrl);
+    if (!res.ok) return null;
+    return (await res.json()) as ProtectedResourceMetadata;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Probe an MCP URL to see whether it requires authentication.
+ *
+ * Sends a minimal `initialize` request. On 200 the server accepts anonymous
+ * connections; on 401 we parse the `WWW-Authenticate` header and, if it
+ * points at RFC 9728 resource metadata, fetch it so the caller can record
+ * the authorization servers and scopes.
+ *
+ * Returns `{ ok: true }` when no auth is required, or
+ * `{ ok: false, requirement }` when the server challenged the request.
+ * Other failures (DNS, TLS, unexpected status) surface as `{ ok: null }`
+ * — the caller should treat those as probe-inconclusive rather than
+ * asserting auth is required.
+ */
+export async function probeRegistryAuth(
+  registryUrl: string,
+  fetchFn: FetchFn = globalThis.fetch,
+): Promise<
+  | { ok: true }
+  | { ok: false; requirement: RegistryAuthRequirement }
+  | { ok: null }
+> {
+  const url = registryUrl.replace(/\/$/, "");
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "agents-sdk-probe", version: "1.0.0" },
+        },
+      }),
+    });
+  } catch {
+    return { ok: null };
+  }
+
+  if (res.status !== 401) {
+    return res.ok ? { ok: true } : { ok: null };
+  }
+
+  const wwwAuth = res.headers.get("www-authenticate") ?? "";
+  const { scheme, params } = parseWwwAuthenticate(wwwAuth);
+  const requirement: RegistryAuthRequirement = {};
+  if (scheme) requirement.scheme = scheme;
+  if (params.realm) requirement.realm = params.realm;
+
+  const metadataUrl = params.resource_metadata;
+  if (metadataUrl) {
+    requirement.resourceMetadataUrl = metadataUrl;
+    const metadata = await discoverProtectedResourceMetadata(metadataUrl, fetchFn);
+    if (metadata) {
+      if (metadata.authorization_servers?.length) {
+        requirement.authorizationServers = metadata.authorization_servers;
+      }
+      if (metadata.scopes_supported?.length) {
+        requirement.scopes = metadata.scopes_supported;
+      }
+      if (metadata.bearer_methods_supported?.length) {
+        requirement.bearerMethodsSupported = metadata.bearer_methods_supported;
+      }
+    }
+  }
+
+  return { ok: false, requirement };
+}

package/src/ref-naming.test.ts

@@ -1,15 +1,10 @@
 /**
  * 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";
@@ -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 () => {
@@ -349,3 +327,50 @@ describe("ref tool — add operation defaults ref to name", () => {
     expect(raw).toBeNull();
   });
 });
+
+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",
+    });
+  });
+});