@slashfi/agents-sdk 0.76.0 → 0.77.1

package/src/adk.ts

@@ -60,7 +60,8 @@ const HELP_SECTIONS: Record<string, string> = {
   adk registry list
   adk registry browse <name> [--query <q>]
   adk registry inspect <name>
-  adk registry test [name]`,
+  adk registry test [name]
+  adk registry auth <name> [--token <t>] [--api-key <k>] [--header <h>]`,
   ref: `Ref operations:
   adk ref add <name>                     Install from default (public) registry
   adk ref add <name> --registry <reg>    Install from a specific registry
@@ -106,9 +107,10 @@ Registry operations:
   adk registry browse <name> [--query <q>]
   adk registry inspect <name>
   adk registry test [name]
+  adk registry auth <name> [--token <t>] [--api-key <k>] [--header <h>]
 
 Ref operations:
-  adk ref add <ref> [--registry <name>] [--as <alias>] [--url <url>] [--scheme mcp|https|registry]
+  adk ref add <ref> [--name <name>] [--registry <name>] [--url <url>] [--scheme mcp|https|registry]
   adk ref remove <name>
   adk ref list
   adk ref inspect <name> [--full]
@@ -156,6 +158,7 @@ async function runRegistry() {
   const op = args[1];
   const adk = getAdk();
 
+  try {
   switch (op) {
     case "add": {
       const url = args[2];
@@ -187,7 +190,7 @@ async function runRegistry() {
           }
         : undefined;
       const displayName = name ?? new URL(url).hostname;
-      await adk.registry.add({
+      const addResult = await adk.registry.add({
         url,
         name: displayName,
         ...(auth && { auth }),
@@ -202,6 +205,17 @@ async function runRegistry() {
       console.log(
         `Added registry: ${displayName}${effectiveProxy ? ` (proxy: ${effectiveProxy.mode} → ${effectiveProxy.agent ?? "@config"}${source})` : ""}`,
       );
+      if (addResult.authRequirement) {
+        const req = addResult.authRequirement;
+        console.log(`\n  \x1b[33m!\x1b[0m Auth required: ${req.scheme ?? "Bearer"}${req.realm ? ` (realm: ${req.realm})` : ""}`);
+        if (req.authorizationServers?.length) {
+          console.log(`    authorization servers: ${req.authorizationServers.join(", ")}`);
+        }
+        if (req.scopes?.length) {
+          console.log(`    scopes: ${req.scopes.join(" ")}`);
+        }
+        console.log(`\n    Run: adk registry auth ${displayName} --token <token>`);
+      }
       break;
     }
     case "remove": {
@@ -264,10 +278,64 @@ async function runRegistry() {
       }
       break;
     }
+    case "auth": {
+      const name = args[2];
+      if (!name) { console.error("Usage: adk registry auth <name> [--token <t>] [--api-key <k>] [--header <h>]"); process.exit(1); }
+      const token = getArg("--token");
+      const apiKey = getArg("--api-key");
+      const header = getArg("--header");
+
+      // Explicit credential mode — user supplied a token/key directly.
+      if (token || apiKey) {
+        const credential = token
+          ? { token }
+          : { apiKey: apiKey!, ...(header && { header }) };
+        const updated = await adk.registry.auth(name, credential);
+        if (!updated) {
+          console.error(`Registry not found: ${name}`);
+          process.exit(1);
+        }
+        console.log(`\x1b[32m✓\x1b[0m Auth saved for ${name}`);
+        break;
+      }
+
+      // Auto-resolve: OAuth (when registry advertised an AS) or local
+      // credential form otherwise. Mirrors `adk ref auth` UX. Always force
+      // a fresh flow — invoking the command implies the existing creds
+      // aren't trusted, so skip the "already looks valid" short-circuit.
+      try {
+        const result = await adk.registry.authLocal(name, {
+          force: true,
+          onAuthorizeUrl: (url) => {
+            console.log(`\nOpen this URL to authenticate:\n\n  ${url}\n`);
+            const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+            import("node:child_process").then(({ exec }) => exec(`${opener} "${url}"`)).catch(() => {});
+            console.log("Waiting ...");
+          },
+        });
+        if (result.complete) {
+          console.log(`\x1b[32m✓\x1b[0m Auth complete for ${name}`);
+        }
+      } catch (err) {
+        if (err instanceof AdkError) throw err;
+        console.error(`Auth failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+      break;
+    }
     default:
       console.error(`Unknown registry operation: ${op}`);
-      console.error("Operations: add, remove, list, browse, inspect, test");
+      console.error("Operations: add, remove, list, browse, inspect, test, auth");
+      process.exit(1);
+  }
+  } catch (err) {
+    if (err instanceof AdkError) {
+      console.error(`\n\x1b[31m✗\x1b[0m ${err.message}`);
+      console.error(`  ${err.hint}`);
+      console.error(`  Error ID: ${err.errorId}`);
       process.exit(1);
+    }
+    throw err;
   }
 }
 
@@ -283,15 +351,14 @@ async function runRef() {
   switch (op) {
     case "add": {
       const refArg = args[2];
-      if (!refArg) { console.error("Usage: adk ref add <ref> [--registry <name>] [--as <alias>]"); process.exit(1); }
-      const entry: Record<string, unknown> = { ref: refArg };
-      const alias = getArg("--as");
+      if (!refArg) { console.error("Usage: adk ref add <ref> [--name <name>] [--registry <name>]"); process.exit(1); }
+      const name = getArg("--name") ?? refArg;
+      const entry: Record<string, unknown> = { ref: refArg, name };
       const url = getArg("--url");
       const registryName = getArg("--registry");
       // Auto-detect: if no --registry and no --url, try default registry
       const effectiveRegistry = registryName ?? (url ? undefined : "public");
       const scheme = getArg("--scheme") ?? (effectiveRegistry ? "registry" : undefined);
-      if (alias) entry.as = alias;
       if (url) entry.url = url;
       if (scheme) entry.scheme = scheme;
       if (effectiveRegistry) {
@@ -302,15 +369,15 @@ async function runRef() {
       }
       try {
         const { security } = await adk.ref.add(entry as import("./define-config.js").RefEntry);
-        console.log(`Added ref: ${alias ?? refArg}`);
+        console.log(`Added ref: ${name}`);
         if (security && security.type !== "none") {
           console.log(`\n  Auth required: ${security.type}`);
-          console.log(`  Run: adk ref auth ${alias ?? refArg}`);
+          console.log(`  Run: adk ref auth ${name}`);
         }
 
         // Materialize local docs
         const configDir = process.env.ADK_CONFIG_DIR ?? join(homedir(), ".adk");
-        const refDisplayName = alias ?? refArg;
+        const refDisplayName = name;
         try {
           const result = await materializeRef(adk, refDisplayName, configDir);
           if (result.toolCount > 0) {

package/src/agent-definitions/config.ts

@@ -108,9 +108,9 @@ export function createConfigAgent(
           type: "string",
           description: 'Agent ref name (e.g. "notion", "linear")',
         },
-        as: {
+        name: {
           type: "string",
-          description: "Local alias (for multi-instance refs)",
+          description: "Local ref name. Defaults to ref when omitted.",
         },
         url: {
           type: "string",
@@ -132,7 +132,7 @@ export function createConfigAgent(
     execute: async (
       input: {
         ref: string;
-        as?: string;
+        name?: string;
         url?: string;
         config?: Record<string, string>;
         registry?: string;
@@ -141,28 +141,27 @@ export function createConfigAgent(
     ) => {
       const fs = getStore(ctx);
       const currentConfig = await readConfig(fs);
+      const name = input.name ?? input.ref;
 
-      const entry: RefEntry = {
+      const entry = {
         ref: input.ref,
-        ...(input.as && { as: input.as }),
+        name,
         ...(input.url && { url: input.url }),
         ...(input.config && { config: input.config }),
         ...(input.registry && { registry: input.registry }),
-      };
+      } as RefEntry;
 
-      // Upsert: find existing ref by name/alias, replace or append
-      const name = input.as ?? input.ref;
       const refs = currentConfig.refs ?? [];
-      const existingIdx = refs.findIndex((r) => {
+      const altName = name.startsWith("@") ? name.slice(1) : `@${name}`;
+      const duplicate = refs.some((r) => {
         const normalized = normalizeRef(r);
-        return normalized.name === name;
+        return normalized.name === name || normalized.name === altName;
       });
 
-      if (existingIdx >= 0) {
-        refs[existingIdx] = entry;
-      } else {
-        refs.push(entry);
+      if (duplicate) {
+        throw new Error(`Cannot add ref "${input.ref}" as "${name}": a ref with that name already exists`);
       }
+      refs.push(entry);
 
       currentConfig.refs = refs;
       await writeConfig(fs, currentConfig);
@@ -178,13 +177,13 @@ export function createConfigAgent(
   // ---- remove_ref ----
   const removeRefTool = defineTool({
     name: "remove_ref",
-    description: "Remove an agent ref from the consumer config by name or alias.",
+    description: "Remove an agent ref from the consumer config by name.",
     inputSchema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "Ref name or alias to remove",
+          description: "Ref name to remove",
         },
       },
       required: ["name"],

package/src/config-store.test.ts

@@ -626,3 +626,215 @@ describe("ADK registry proxy routing", () => {
     expect((result as { authorizeUrl?: string }).authorizeUrl).toBeUndefined();
   });
 });
+
+// ─── Registry auth lifecycle ─────────────────────────────────────
+
+describe("ADK registry auth lifecycle", () => {
+  const PORT = 19930;
+  const MCP_URL = `http://localhost:${PORT}/mcp`;
+  const AS_URL = `http://localhost:${PORT}`;
+
+  let mcpServer: ReturnType<typeof Bun.serve>;
+  let activeAccessToken = "access-token-v1";
+  let tokenExchangeCount = 0;
+  let tokenRefreshCount = 0;
+
+  beforeAll(() => {
+    // Fake registry that speaks MCP when authenticated, emits an RFC 6750
+    // challenge pointing at RFC 9728 metadata when not, and doubles as the
+    // OAuth authorization server (registration + authorize + token) so the
+    // whole adk registry.auth flow can run end-to-end in-process.
+    mcpServer = Bun.serve({
+      port: PORT,
+      async fetch(req) {
+        const url = new URL(req.url);
+        const path = url.pathname;
+
+        // RFC 9728 protected-resource metadata
+        if (path === "/.well-known/oauth-protected-resource") {
+          return Response.json({
+            resource: MCP_URL,
+            authorization_servers: [AS_URL],
+            scopes_supported: ["mcp:full"],
+            bearer_methods_supported: ["header"],
+          });
+        }
+
+        // RFC 8414 authorization-server metadata
+        if (path === "/.well-known/oauth-authorization-server") {
+          return Response.json({
+            issuer: AS_URL,
+            authorization_endpoint: `${AS_URL}/oauth/authorize`,
+            token_endpoint: `${AS_URL}/oauth/token`,
+            registration_endpoint: `${AS_URL}/oauth/register`,
+          });
+        }
+
+        // Dynamic client registration (RFC 7591)
+        if (path === "/oauth/register" && req.method === "POST") {
+          return Response.json({
+            client_id: "test-client-id",
+            client_secret: "test-client-secret",
+          });
+        }
+
+        // Token endpoint — supports authorization_code + refresh_token grants
+        if (path === "/oauth/token" && req.method === "POST") {
+          const body = new URLSearchParams(await req.text());
+          const grant = body.get("grant_type");
+          if (grant === "authorization_code") {
+            tokenExchangeCount++;
+            return Response.json({
+              access_token: activeAccessToken,
+              refresh_token: "refresh-token-v1",
+              token_type: "Bearer",
+              expires_in: 3600,
+            });
+          }
+          if (grant === "refresh_token") {
+            tokenRefreshCount++;
+            if (body.get("refresh_token") !== "refresh-token-v1") {
+              return new Response(
+                JSON.stringify({ error: "invalid_grant" }),
+                { status: 400 },
+              );
+            }
+            // Rotate to a new access token so the test can tell refresh ran.
+            activeAccessToken = "access-token-v2";
+            return Response.json({
+              access_token: activeAccessToken,
+              token_type: "Bearer",
+              expires_in: 3600,
+            });
+          }
+          return new Response("unsupported_grant_type", { status: 400 });
+        }
+
+        // MCP endpoint
+        if (path === "/mcp" && req.method === "POST") {
+          const auth = req.headers.get("authorization") ?? "";
+          const expected = `Bearer ${activeAccessToken}`;
+          if (auth !== expected) {
+            return new Response(
+              JSON.stringify({ error: { code: "UNAUTHORIZED", message: "No token" } }),
+              {
+                status: 401,
+                headers: {
+                  "Content-Type": "application/json",
+                  "WWW-Authenticate": `Bearer realm="test", resource_metadata="${AS_URL}/.well-known/oauth-protected-resource"`,
+                },
+              },
+            );
+          }
+          const rpc = (await req.json()) as { id: number; method: string };
+          if (rpc.method === "initialize") {
+            return Response.json({
+              jsonrpc: "2.0",
+              id: rpc.id,
+              result: { serverInfo: { name: "test-mcp" }, capabilities: {} },
+            });
+          }
+          if (rpc.method === "tools/call") {
+            return Response.json({
+              jsonrpc: "2.0",
+              id: rpc.id,
+              result: {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify({
+                      agents: [
+                        { path: "@test-agent", description: "An agent", toolCount: 1 },
+                      ],
+                    }),
+                  },
+                ],
+              },
+            });
+          }
+          return new Response("method not found", { status: 404 });
+        }
+
+        return new Response("not found", { status: 404 });
+      },
+    });
+  });
+
+  afterAll(() => {
+    mcpServer.stop();
+  });
+
+  test("registry.add records auth challenge; browse refuses; auth() unlocks", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs, { encryptionKey: "test-key-32-chars-long-enough!!" });
+
+    const addResult = await adk.registry.add({ name: "test", url: MCP_URL });
+
+    expect(addResult.authRequirement).toBeDefined();
+    expect(addResult.authRequirement?.scheme).toBe("Bearer");
+    expect(addResult.authRequirement?.authorizationServers).toEqual([AS_URL]);
+    expect(addResult.authRequirement?.scopes).toEqual(["mcp:full"]);
+
+    await expect(adk.registry.browse("test")).rejects.toMatchObject({
+      code: "registry_auth_required",
+    });
+
+    await adk.registry.auth("test", { token: activeAccessToken });
+
+    // Stored token is encrypted (secret: prefix) — buildConsumer decrypts
+    // it transparently so browse should now land the MCP call.
+    const stored = await adk.registry.get("test");
+    expect(stored?.auth?.type).toBe("bearer");
+    expect((stored?.auth as { token: string }).token).toMatch(/^secret:/);
+    expect(stored?.authRequirement).toBeUndefined();
+
+    const agents = await adk.registry.browse("test");
+    expect(agents).toHaveLength(1);
+    expect(agents[0]?.path).toBe("@test-agent");
+  });
+
+  test("browse 401 triggers refresh via stored refresh_token and retries", async () => {
+    const fs = createMemoryFs();
+    const adk = createAdk(fs, { encryptionKey: "test-key-32-chars-long-enough!!" });
+
+    // Reset server-side token so the next refresh rotates predictably.
+    activeAccessToken = "access-token-v1";
+    tokenRefreshCount = 0;
+
+    await adk.registry.add({ name: "test", url: MCP_URL });
+    await adk.registry.auth("test", { token: activeAccessToken });
+
+    // Seed the entry with OAuth state as if `authLocal` had completed.
+    // Refresh token / endpoint / clientId are written directly so the
+    // test isn't dependent on the full browser-redirect flow.
+    const config = await adk.readConfig();
+    await adk.writeConfig({
+      ...config,
+      registries: config.registries?.map((r: any) => {
+        if (typeof r !== "string" && r.name === "test") {
+          return {
+            ...r,
+            oauth: {
+              tokenEndpoint: `${AS_URL}/oauth/token`,
+              clientId: "test-client-id",
+              refreshToken: "refresh-token-v1",
+            },
+          };
+        }
+        return r;
+      }),
+    });
+
+    // Rotate the server token — the client's stored token is now stale.
+    activeAccessToken = "access-token-v2";
+
+    const agents = await adk.registry.browse("test");
+
+    // Refresh was called exactly once; the browse call succeeded on retry.
+    expect(tokenRefreshCount).toBe(1);
+    expect(agents).toHaveLength(1);
+
+    const stored = await adk.registry.get("test");
+    expect((stored?.auth as { token: string }).token).toMatch(/^secret:/);
+  });
+});