@slashfi/agents-sdk 0.76.0 → 0.77.1

package/dist/config-store.js

@@ -20,7 +20,7 @@ import { normalizeRef } from "./define-config.js";
 import { createRegistryConsumer } from "./registry-consumer.js";
 import { decryptSecret, encryptSecret } from "./crypto.js";
 import { AdkError } from "./adk-error.js";
-import { discoverOAuthMetadata, dynamicClientRegistration, buildOAuthAuthorizeUrl, exchangeCodeForTokens, } from "./mcp-client.js";
+import { discoverOAuthMetadata, dynamicClientRegistration, buildOAuthAuthorizeUrl, exchangeCodeForTokens, probeRegistryAuth, refreshAccessToken, } from "./mcp-client.js";
 const CONFIG_PATH = "consumer-config.json";
 const SECRET_PREFIX = "secret:";
 // ============================================
@@ -37,9 +37,10 @@ function refName(entry) {
 function findRef(refs, name) {
     const match = refs.find((r) => refName(r) === name);
     if (match)
-        return 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;
 }
 /**
  * Match a ref name with @ normalization (for filter/map operations).
@@ -191,7 +192,8 @@ export function createAdk(fs, options = {}) {
         const refs = (config.refs ?? []).map((r) => {
             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 });
     }
@@ -453,7 +455,11 @@ export function createAdk(fs, options = {}) {
      * throw on error so callers get a result that matches the local signature.
      */
     async function forwardRefOpToProxy(reg, agent, operation, params) {
-        const consumer = await buildConsumerForRef({ ref: "", sourceRegistry: { url: reg.url, agentPath: agent } });
+        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`);
@@ -473,16 +479,215 @@ export function createAdk(fs, options = {}) {
     // ==========================================
     // Registry API
     // ==========================================
+    /**
+     * Encrypt with `secret:` prefix when an encryption key is configured, so the
+     * value is readable by the existing `decryptConfigSecrets` path on the read
+     * side. Plaintext fallback preserves the "no key = dev mode" contract.
+     */
+    async function protectSecret(value) {
+        if (!options.encryptionKey)
+            return value;
+        return `${SECRET_PREFIX}${await encryptSecret(value, options.encryptionKey)}`;
+    }
+    /**
+     * Re-probe a registry with the current stored credentials to see whether it
+     * advertises `capabilities.registry.proxy` in its MCP `initialize` response,
+     * and persist the proxy config when it does. Safe to call after a successful
+     * `auth()` / `authLocal()` — on the add path we skip the proxy probe when
+     * auth is required, so this is the second chance to back-fill it.
+     *
+     * Respects explicit user config: if `proxy` is already set, we leave it
+     * alone. Any discovery failure is swallowed — proxy is an optimization,
+     * not a correctness requirement.
+     */
+    async function discoverProxyAfterAuth(nameOrUrl) {
+        const config = await readConfig();
+        const target = findRegistry(config.registries ?? [], nameOrUrl);
+        if (!target || typeof target === "string")
+            return;
+        if (target.proxy)
+            return;
+        try {
+            const consumer = await buildConsumer(nameOrUrl);
+            const discovered = await consumer.discover(target.url);
+            if (!discovered.proxy?.mode)
+                return;
+            await updateRegistryEntry(nameOrUrl, (existing) => {
+                if (existing.proxy)
+                    return;
+                existing.proxy = {
+                    mode: discovered.proxy.mode,
+                    ...(discovered.proxy.agent && { agent: discovered.proxy.agent }),
+                };
+            });
+        }
+        catch {
+            // Proxy probe is best-effort — auth itself already succeeded.
+        }
+    }
+    /**
+     * Atomic read-modify-write on a registry entry by name or URL. Used by
+     * `authLocal` to persist both `auth` and `oauth` together, which `auth()`
+     * alone can't express. Returns true when the entry was found and written.
+     */
+    async function updateRegistryEntry(nameOrUrl, mutate) {
+        const config = await readConfig();
+        if (!config.registries?.length)
+            return false;
+        let found = false;
+        const registries = config.registries.map((r) => {
+            const rName = registryDisplayName(r);
+            if (rName !== nameOrUrl && registryUrl(r) !== nameOrUrl)
+                return r;
+            found = true;
+            const existing = typeof r === "string" ? { url: r } : { ...r };
+            mutate(existing);
+            return existing;
+        });
+        if (!found)
+            return false;
+        await writeConfig({ ...config, registries });
+        return true;
+    }
+    /**
+     * Decrypt a `secret:`-prefixed value if we hold the encryption key. Plaintext
+     * values pass through unchanged so dev configs keep working.
+     */
+    async function revealSecret(value) {
+        if (!value)
+            return value;
+        if (!value.startsWith(SECRET_PREFIX))
+            return value;
+        if (!options.encryptionKey)
+            return undefined;
+        return decryptSecret(value.slice(SECRET_PREFIX.length), options.encryptionKey);
+    }
+    /**
+     * Refresh a registry's OAuth access token using the stored refresh token.
+     * Persists the new access token (encrypted) and updates `expiresAt`. If the
+     * provider rotates the refresh token, that's encrypted and stored too.
+     * Returns `true` when the refresh succeeded. Callers should catch and fall
+     * back to full re-auth on failure.
+     */
+    async function refreshRegistryToken(nameOrUrl) {
+        const config = await readConfig();
+        const target = findRegistry(config.registries ?? [], nameOrUrl);
+        if (!target || typeof target === "string")
+            return false;
+        const oauth = target.oauth;
+        if (!oauth?.refreshToken || !oauth.tokenEndpoint || !oauth.clientId)
+            return false;
+        const refreshToken = await revealSecret(oauth.refreshToken);
+        const clientSecret = await revealSecret(oauth.clientSecret);
+        if (!refreshToken)
+            return false;
+        const refreshed = await refreshAccessToken(oauth.tokenEndpoint, {
+            refreshToken,
+            clientId: oauth.clientId,
+            ...(clientSecret && { clientSecret }),
+        });
+        const expiresAt = refreshed.expiresIn
+            ? new Date(Date.now() + refreshed.expiresIn * 1000).toISOString()
+            : undefined;
+        const encAccess = await protectSecret(refreshed.accessToken);
+        const encRefresh = refreshed.refreshToken
+            ? await protectSecret(refreshed.refreshToken)
+            : undefined;
+        await updateRegistryEntry(nameOrUrl, (existing) => {
+            existing.auth = { type: "bearer", token: encAccess };
+            if (!existing.oauth)
+                return;
+            if (encRefresh)
+                existing.oauth.refreshToken = encRefresh;
+            if (expiresAt)
+                existing.oauth.expiresAt = expiresAt;
+            else
+                delete existing.oauth.expiresAt;
+        });
+        return true;
+    }
+    /**
+     * Run a registry op once; on 401 (`registry_auth_required`), try to refresh
+     * via the stored refresh token and retry exactly once. Any other AdkError
+     * propagates as-is.
+     */
+    async function callWithRefresh(nameOrUrl, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!(err instanceof AdkError) || err.code !== "registry_auth_required")
+                throw err;
+            let refreshed = false;
+            try {
+                refreshed = await refreshRegistryToken(nameOrUrl);
+            }
+            catch {
+                // Refresh failed — surface the original 401 below.
+            }
+            if (!refreshed)
+                throw err;
+            return fn();
+        }
+    }
+    /**
+     * Throw a typed error if the registry has a recorded auth challenge and
+     * no usable credentials on the entry. Callers should invoke this before
+     * running any op that talks to the registry.
+     */
+    function assertRegistryAuthorized(entry) {
+        if (!entry.authRequirement)
+            return;
+        const hasUsableAuth = entry.auth && entry.auth.type !== "none"
+            ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+                (entry.auth.type === "api-key" && !!entry.auth.key)
+            : false;
+        if (hasUsableAuth)
+            return;
+        const name = entry.name ?? entry.url;
+        const scope = entry.authRequirement.scopes?.join(" ");
+        throw new AdkError({
+            code: "registry_auth_required",
+            message: `Registry "${name}" requires authentication.`,
+            hint: `Run: adk registry auth ${name} --token <token>${scope ? ` (scopes: ${scope})` : ""}`,
+            details: {
+                url: entry.url,
+                scheme: entry.authRequirement.scheme,
+                realm: entry.authRequirement.realm,
+                authorizationServers: entry.authRequirement.authorizationServers,
+                scopes: entry.authRequirement.scopes,
+                resourceMetadataUrl: entry.authRequirement.resourceMetadataUrl,
+            },
+        });
+    }
     const registry = {
         async add(entry) {
             const config = await readConfig();
             const alias = entry.name ?? entry.url;
             const registries = (config.registries ?? []).filter((r) => registryDisplayName(r) !== alias);
-            // Probe the registry's MCP initialize response so we can auto-populate
-            // `proxy` when the server advertises it. Users who pass an explicit
-            // `proxy` on the entry always win — discovery only fills in blanks.
+            // Probe the registry before saving. Two things fall out of the probe:
+            //   1. Auth challenge — 401 + WWW-Authenticate points at RFC 9728
+            //      resource metadata; we persist it on `authRequirement` so
+            //      subsequent ops can refuse early with a friendly message.
+            //   2. Proxy capability — the MCP `initialize` response may advertise
+            //      `capabilities.registry.proxy`, which auto-populates `proxy`.
+            // Users who set `proxy` or `auth` explicitly on the entry always win:
+            // discovery only fills in blanks.
             let final = entry;
-            if (!entry.proxy) {
+            let authRequirement;
+            const hasUsableAuth = entry.auth && entry.auth.type !== "none"
+                ? (entry.auth.type === "bearer" && !!entry.auth.token) ||
+                    (entry.auth.type === "api-key" && !!entry.auth.key)
+                : false;
+            if (!hasUsableAuth) {
+                const fetchFn = options.fetch ?? globalThis.fetch;
+                const probe = await probeRegistryAuth(entry.url, fetchFn);
+                if (probe.ok === false) {
+                    authRequirement = probe.requirement;
+                    final = { ...final, authRequirement };
+                }
+            }
+            if (!entry.proxy && !authRequirement) {
                 try {
                     const probeConsumer = await createRegistryConsumer({ registries: [entry], refs: [] }, { token: options.token, fetch: options.fetch });
                     const resolved = probeConsumer.registries()[0];
@@ -490,7 +695,7 @@ export function createAdk(fs, options = {}) {
                         const discovered = await probeConsumer.discover(resolved.url);
                         if (discovered.proxy?.mode) {
                             final = {
-                                ...entry,
+                                ...final,
                                 proxy: {
                                     mode: discovered.proxy.mode,
                                     ...(discovered.proxy.agent && { agent: discovered.proxy.agent }),
@@ -506,6 +711,7 @@ export function createAdk(fs, options = {}) {
             }
             registries.push(final);
             await writeConfig({ ...config, registries });
+            return authRequirement ? { authRequirement } : {};
         },
         async remove(nameOrUrl) {
             const config = await readConfig();
@@ -558,18 +764,26 @@ export function createAdk(fs, options = {}) {
             return true;
         },
         async browse(name, query) {
-            const consumer = await buildConsumer(name);
             const config = await readConfig();
             const target = findRegistry(config.registries ?? [], name);
-            const url = target ? registryUrl(target) : name;
-            return consumer.browse(url, query);
+            if (target && typeof target !== "string")
+                assertRegistryAuthorized(target);
+            return callWithRefresh(name, async () => {
+                const consumer = await buildConsumer(name);
+                const url = target ? registryUrl(target) : name;
+                return consumer.browse(url, query);
+            });
         },
         async inspect(name) {
-            const consumer = await buildConsumer(name);
             const config = await readConfig();
             const target = findRegistry(config.registries ?? [], name);
-            const url = target ? registryUrl(target) : name;
-            return consumer.discover(url);
+            if (target && typeof target !== "string")
+                assertRegistryAuthorized(target);
+            return callWithRefresh(name, async () => {
+                const consumer = await buildConsumer(name);
+                const url = target ? registryUrl(target) : name;
+                return consumer.discover(url);
+            });
         },
         async test(name) {
             const config = await readConfig();
@@ -580,9 +794,28 @@ export function createAdk(fs, options = {}) {
             const results = await Promise.allSettled(targets.map(async (r) => {
                 const url = registryUrl(r);
                 const rName = registryDisplayName(r);
+                if (typeof r !== "string" && r.authRequirement) {
+                    const hasUsableAuth = r.auth && r.auth.type !== "none"
+                        ? (r.auth.type === "bearer" && !!r.auth.token) ||
+                            (r.auth.type === "api-key" && !!r.auth.key)
+                        : false;
+                    if (!hasUsableAuth) {
+                        return {
+                            name: rName,
+                            url,
+                            status: "error",
+                            error: `auth required — run: adk registry auth ${rName} --token <token>`,
+                        };
+                    }
+                }
                 try {
-                    const consumer = await createRegistryConsumer({ registries: [r] }, { token: options.token, fetch: options.fetch });
-                    const disc = await consumer.discover(url);
+                    // Route through buildConsumer so encrypted auth/headers get
+                    // decrypted, then use callWithRefresh so a 401 triggers the
+                    // stored refresh token before giving up.
+                    const disc = await callWithRefresh(rName, async () => {
+                        const consumer = await buildConsumer(rName);
+                        return consumer.discover(url);
+                    });
                     return { name: rName, url, status: "active", issuer: disc.issuer };
                 }
                 catch (err) {
@@ -594,15 +827,278 @@ export function createAdk(fs, options = {}) {
                 ? r.value
                 : { name: "unknown", url: "unknown", status: "error", error: "unknown" });
         },
+        async auth(nameOrUrl, credential) {
+            // Encrypt the secret value up-front so the write path is uniform;
+            // `buildConsumer` decrypts on the read side via `decryptConfigSecrets`.
+            const protectedValue = "token" in credential
+                ? await protectSecret(credential.token)
+                : await protectSecret(credential.apiKey);
+            const updated = await updateRegistryEntry(nameOrUrl, (existing) => {
+                if ("token" in credential) {
+                    existing.auth = {
+                        type: "bearer",
+                        token: protectedValue,
+                        ...(credential.tokenUrl && { tokenUrl: credential.tokenUrl }),
+                    };
+                }
+                else {
+                    existing.auth = {
+                        type: "api-key",
+                        key: protectedValue,
+                        ...(credential.header && { header: credential.header }),
+                    };
+                }
+                delete existing.authRequirement;
+            });
+            if (updated)
+                await discoverProxyAfterAuth(nameOrUrl);
+            return updated;
+        },
+        async authLocal(nameOrUrl, opts) {
+            const config = await readConfig();
+            const target = findRegistry(config.registries ?? [], nameOrUrl);
+            if (!target || typeof target === "string") {
+                throw new AdkError({
+                    code: "registry_not_found",
+                    message: `Registry not found: ${nameOrUrl}`,
+                    hint: "Run `adk registry list` to see configured registries.",
+                    details: { nameOrUrl },
+                });
+            }
+            // When the caller forces re-auth, wipe the existing credentials and
+            // re-probe so we know what scheme the registry wants now. Servers can
+            // rotate auth server metadata between runs.
+            if (opts?.force) {
+                await updateRegistryEntry(nameOrUrl, (existing) => {
+                    delete existing.auth;
+                    delete existing.oauth;
+                });
+                const fetchFn = options.fetch ?? globalThis.fetch;
+                const probe = await probeRegistryAuth(target.url, fetchFn);
+                if (probe.ok === false) {
+                    await updateRegistryEntry(nameOrUrl, (existing) => {
+                        existing.authRequirement = probe.requirement;
+                    });
+                    // Re-read so the flow below sees the fresh requirement.
+                    const refreshed = await readConfig();
+                    const refreshedTarget = findRegistry(refreshed.registries ?? [], nameOrUrl);
+                    if (refreshedTarget && typeof refreshedTarget !== "string") {
+                        Object.assign(target, refreshedTarget);
+                    }
+                }
+                else if (probe.ok === true) {
+                    // Registry no longer requires auth — nothing to do.
+                    await updateRegistryEntry(nameOrUrl, (existing) => {
+                        delete existing.authRequirement;
+                    });
+                    return { complete: true };
+                }
+            }
+            // Already authenticated — nothing to do (unless forced above).
+            const hasUsableAuth = target.auth && target.auth.type !== "none"
+                ? (target.auth.type === "bearer" && !!target.auth.token) ||
+                    (target.auth.type === "api-key" && !!target.auth.key)
+                : false;
+            if (hasUsableAuth && !target.authRequirement) {
+                return { complete: true };
+            }
+            const req = target.authRequirement;
+            const port = options.oauthCallbackPort ?? 8919;
+            const timeout = opts?.timeoutMs ?? 300_000;
+            const displayName = target.name ?? target.url;
+            const { createServer } = await import("node:http");
+            // OAuth path — the registry advertised authorization servers via
+            // RFC 9728 protected-resource metadata. Walk the full flow:
+            // AS metadata → dynamic client registration → PKCE authorize →
+            // local callback → token exchange → persist access token.
+            if (req?.authorizationServers?.length) {
+                const authServer = req.authorizationServers[0];
+                const metadata = (await discoverOAuthMetadata(authServer)) ??
+                    (await tryFetchOAuthMetadata(authServer));
+                if (!metadata) {
+                    throw new AdkError({
+                        code: "registry_oauth_discovery_failed",
+                        message: `Could not discover OAuth metadata at ${authServer}.`,
+                        hint: "The authorization server must expose /.well-known/oauth-authorization-server.",
+                        details: { authServer, registry: displayName },
+                    });
+                }
+                if (!metadata.registration_endpoint) {
+                    throw new AdkError({
+                        code: "registry_oauth_no_registration",
+                        message: `Authorization server ${authServer} does not support dynamic client registration.`,
+                        hint: `Obtain a bearer token manually, then run: adk registry auth ${displayName} --token <token>`,
+                        details: { authServer, registry: displayName },
+                    });
+                }
+                const redirectUri = `http://localhost:${port}/callback`;
+                const registration = await dynamicClientRegistration(metadata.registration_endpoint, {
+                    clientName: options.oauthClientName ?? "adk",
+                    redirectUris: [redirectUri],
+                    grantTypes: ["authorization_code"],
+                });
+                const state = crypto.randomUUID();
+                const { url: authorizeUrl, codeVerifier } = await buildOAuthAuthorizeUrl({
+                    authorizationEndpoint: metadata.authorization_endpoint,
+                    clientId: registration.clientId,
+                    redirectUri,
+                    scopes: req.scopes,
+                    state,
+                });
+                return new Promise((resolve, reject) => {
+                    const server = createServer(async (reqIn, resOut) => {
+                        const reqUrl = new URL(reqIn.url ?? "/", `http://localhost:${port}`);
+                        if (reqUrl.pathname !== "/callback") {
+                            resOut.writeHead(404);
+                            resOut.end();
+                            return;
+                        }
+                        const code = reqUrl.searchParams.get("code");
+                        const returnedState = reqUrl.searchParams.get("state");
+                        if (!code || returnedState !== state) {
+                            const error = reqUrl.searchParams.get("error") ?? "missing code/state";
+                            resOut.writeHead(400, { "Content-Type": "text/html" });
+                            resOut.end(`<h1>Error</h1><p>${esc(error)}</p>`);
+                            server.close();
+                            reject(new AdkError({
+                                code: "registry_oauth_denied",
+                                message: `OAuth callback rejected: ${error}`,
+                                hint: "Retry `adk registry auth` and complete the browser consent.",
+                                details: { registry: displayName, error },
+                            }));
+                            return;
+                        }
+                        try {
+                            const tokens = await exchangeCodeForTokens(metadata.token_endpoint, {
+                                code,
+                                codeVerifier,
+                                clientId: registration.clientId,
+                                clientSecret: registration.clientSecret,
+                                redirectUri,
+                            });
+                            const expiresAt = tokens.expiresIn
+                                ? new Date(Date.now() + tokens.expiresIn * 1000).toISOString()
+                                : undefined;
+                            const encToken = await protectSecret(tokens.accessToken);
+                            const encRefresh = tokens.refreshToken
+                                ? await protectSecret(tokens.refreshToken)
+                                : undefined;
+                            const encClientSecret = registration.clientSecret
+                                ? await protectSecret(registration.clientSecret)
+                                : undefined;
+                            await updateRegistryEntry(displayName, (existing) => {
+                                existing.auth = { type: "bearer", token: encToken };
+                                existing.oauth = {
+                                    tokenEndpoint: metadata.token_endpoint,
+                                    clientId: registration.clientId,
+                                    ...(encClientSecret && { clientSecret: encClientSecret }),
+                                    ...(encRefresh && { refreshToken: encRefresh }),
+                                    ...(expiresAt && { expiresAt }),
+                                    ...(req.scopes?.length && { scopes: req.scopes }),
+                                };
+                                delete existing.authRequirement;
+                            });
+                            await discoverProxyAfterAuth(displayName);
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderAuthSuccess(displayName));
+                            server.close();
+                            resolve({ complete: true });
+                        }
+                        catch (err) {
+                            resOut.writeHead(500, { "Content-Type": "text/html" });
+                            resOut.end(`<h1>Error</h1><p>${esc(err instanceof Error ? err.message : String(err))}</p>`);
+                            server.close();
+                            reject(err);
+                        }
+                    });
+                    server.listen(port, () => {
+                        opts?.onAuthorizeUrl?.(authorizeUrl);
+                    });
+                    const timer = setTimeout(() => {
+                        server.close();
+                        reject(new Error("OAuth callback timed out"));
+                    }, timeout);
+                    server.on("close", () => clearTimeout(timer));
+                });
+            }
+            // No OAuth metadata — serve a local HTTPS form asking for a token.
+            // Used when the registry returned 401 without pointing at an AS, or
+            // when the caller simply wants to paste a pre-issued token.
+            const fields = [
+                {
+                    name: "token",
+                    label: "Bearer token",
+                    description: req?.realm
+                        ? `Token for realm "${req.realm}"`
+                        : "Token sent as `Authorization: Bearer <token>`.",
+                    secret: true,
+                },
+            ];
+            return new Promise((resolve, reject) => {
+                const server = createServer(async (reqIn, resOut) => {
+                    const reqUrl = new URL(reqIn.url ?? "/", `http://localhost:${port}`);
+                    if (reqIn.method === "GET" && reqUrl.pathname === "/auth") {
+                        resOut.writeHead(200, { "Content-Type": "text/html" });
+                        resOut.end(renderCredentialForm(displayName, fields));
+                        return;
+                    }
+                    if (reqIn.method === "POST" && reqUrl.pathname === "/auth") {
+                        const chunks = [];
+                        for await (const chunk of reqIn)
+                            chunks.push(chunk);
+                        const body = Buffer.concat(chunks).toString();
+                        const params = new URLSearchParams(body);
+                        const token = params.get("token");
+                        if (!token) {
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderCredentialForm(displayName, fields, "Token is required."));
+                            return;
+                        }
+                        try {
+                            await registry.auth(displayName, { token });
+                            resOut.writeHead(200, { "Content-Type": "text/html" });
+                            resOut.end(renderAuthSuccess(displayName));
+                            server.close();
+                            resolve({ complete: true });
+                        }
+                        catch (err) {
+                            resOut.writeHead(500, { "Content-Type": "text/html" });
+                            resOut.end(renderCredentialForm(displayName, fields, err instanceof Error ? err.message : String(err)));
+                        }
+                        return;
+                    }
+                    resOut.writeHead(404);
+                    resOut.end();
+                });
+                server.listen(port, () => {
+                    opts?.onAuthorizeUrl?.(`http://localhost:${port}/auth`);
+                });
+                const timer = setTimeout(() => {
+                    server.close();
+                    reject(new Error("Auth timed out"));
+                }, timeout);
+                server.on("close", () => clearTimeout(timer));
+            });
+        },
     };
     // ==========================================
     // Ref API
     // ==========================================
     const ref = {
-        async add(entry) {
+        async add(entryInput) {
             let security = null;
             const config = await readConfig();
             const hasRegistries = (config.registries ?? []).length > 0;
+            const name = entryInput.name ?? entryInput.ref;
+            let entry = { ...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) {
                 if (entry.sourceRegistry?.url) {
@@ -695,9 +1191,7 @@ export function createAdk(fs, options = {}) {
                     });
                 }
             }
-            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 };
         },
@@ -732,16 +1226,18 @@ export function createAdk(fs, options = {}) {
                 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));
+                    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;
@@ -1152,7 +1648,8 @@ export function createAdk(fs, options = {}) {
                 // 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));