npm - @slashfi/agents-sdk - Versions diffs - 0.77.2 → 0.78.0 - Mend

@slashfi/agents-sdk 0.77.2 → 0.78.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/dist/adk-tools.d.ts.map +1 -1
package/dist/adk-tools.js +104 -253
package/dist/adk-tools.js.map +1 -1
package/dist/call-agent-schema.d.ts +12 -12
package/dist/cjs/adk-tools.js +104 -253
package/dist/cjs/adk-tools.js.map +1 -1
package/dist/cjs/config-store.js +333 -94
package/dist/cjs/config-store.js.map +1 -1
package/dist/cjs/define-config.js.map +1 -1
package/dist/cjs/index.js.map +1 -1
package/dist/cjs/registry.js +2 -33
package/dist/cjs/registry.js.map +1 -1
package/dist/cjs/types.js.map +1 -1
package/dist/config-store.d.ts +34 -4
package/dist/config-store.d.ts.map +1 -1
package/dist/config-store.js +333 -94
package/dist/config-store.js.map +1 -1
package/dist/define-config.d.ts +28 -4
package/dist/define-config.d.ts.map +1 -1
package/dist/define-config.js.map +1 -1
package/dist/index.d.ts +5 -5
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2 -2
package/dist/index.js.map +1 -1
package/dist/registry.d.ts.map +1 -1
package/dist/registry.js +2 -33
package/dist/registry.js.map +1 -1
package/dist/types.d.ts +3 -5
package/dist/types.d.ts.map +1 -1
package/dist/types.js.map +1 -1
package/package.json +1 -1
package/src/adk-tools.ts +113 -282
package/src/config-store.test.ts +345 -28
package/src/config-store.ts +829 -274
package/src/define-config.ts +47 -21
package/src/index.ts +16 -13
package/src/ref-naming.test.ts +1 -49
package/src/registry.ts +2 -40
package/src/types.ts +6 -21

package/dist/config-store.js CHANGED Viewed

@@ -16,12 +16,13 @@
  * await adk.ref.call('notion', 'notion-search', { query: 'hello' });
  * ```
  */
+import { AdkError } from "./adk-error.js";
+import { decryptSecret, encryptSecret } from "./crypto.js";
 import { normalizeRef } from "./define-config.js";
+import { buildOAuthAuthorizeUrl, discoverOAuthMetadata, dynamicClientRegistration, exchangeCodeForTokens, probeRegistryAuth, refreshAccessToken, } from "./mcp-client.js";
 import { createRegistryConsumer } from "./registry-consumer.js";
-import { decryptSecret, encryptSecret } from "./crypto.js";
-import { AdkError } from "./adk-error.js";
-import { discoverOAuthMetadata, dynamicClientRegistration, buildOAuthAuthorizeUrl, exchangeCodeForTokens, probeRegistryAuth, refreshAccessToken, } from "./mcp-client.js";
 const CONFIG_PATH = "consumer-config.json";
+const REGISTRY_CACHE_PATH = "registry-cache.json";
 const SECRET_PREFIX = "secret:";
 // ============================================
 // Internal helpers
@@ -74,7 +75,9 @@ async function decryptConfigSecrets(obj, encryptionKey) {
         if (typeof value === "string" && value.startsWith(SECRET_PREFIX)) {
             result[key] = await decryptSecret(value.slice(SECRET_PREFIX.length), encryptionKey);
         }
-        else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        else if (value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
             result[key] = await decryptConfigSecrets(value, encryptionKey);
         }
         else {
@@ -92,7 +95,7 @@ async function decryptConfigSecrets(obj, encryptionKey) {
  * Fallback: _httpStatus from tool result body
  */
 function isUnauthorized(result) {
-    if (!result || typeof result !== 'object')
+    if (!result || typeof result !== "object")
         return false;
     const r = result;
     // Primary: HTTP status forwarded by the registry and set by callRegistry
@@ -107,17 +110,21 @@ function isUnauthorized(result) {
 // ============================================
 // Local auth form HTML
 // ============================================
-const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const esc = (s) => s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
 function renderCredentialForm(name, fields, error) {
-    const fieldHtml = fields.map((f) => `
+    const fieldHtml = fields
+        .map((f) => `
       <div class="field">
         <label for="${esc(f.name)}">${esc(f.label)}</label>
         ${f.description ? `<p class="desc">${esc(f.description)}</p>` : ""}
         <input id="${esc(f.name)}" name="${esc(f.name)}" type="${f.secret ? "password" : "text"}" required autocomplete="off" spellcheck="false" />
-      </div>`).join("");
-    const errorHtml = error
-        ? `<div class="error">${esc(error)}</div>`
-        : "";
+      </div>`)
+        .join("");
+    const errorHtml = error ? `<div class="error">${esc(error)}</div>` : "";
     return `<!DOCTYPE html>
 <html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
 <title>Authenticate \u2014 ${esc(name)}</title>
@@ -180,6 +187,95 @@ export function createAdk(fs, options = {}) {
     async function writeConfig(config) {
         await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2));
     }
+    // -------------------------------------------------------------------------
+    // Registry cache helpers
+    //
+    // The cache is purely an internal optimization for the adk's read paths
+    // (`ref.list()`, `ref.get()`). Writes happen as side-effects of methods
+    // that already call the registry (`ref.add()`, `ref.inspect()`); the
+    // public surface never grows new methods. Cache failures (missing file,
+    // malformed JSON, fs errors during write) are swallowed so the registry
+    // cache can never break a registry operation.
+    // -------------------------------------------------------------------------
+    async function readRegistryCache() {
+        try {
+            const content = await fs.readFile(REGISTRY_CACHE_PATH);
+            if (!content)
+                return { refs: {} };
+            const parsed = JSON.parse(content);
+            return { refs: parsed.refs ?? {} };
+        }
+        catch {
+            return { refs: {} };
+        }
+    }
+    async function writeRegistryCache(cache) {
+        try {
+            await fs.writeFile(REGISTRY_CACHE_PATH, JSON.stringify(cache, null, 2));
+        }
+        catch {
+            // Best-effort. A failed cache write should never break the operation
+            // that triggered it.
+        }
+    }
+    /**
+     * Project an inspect/list response into the slim shape we cache. Drops
+     * `inputSchema` (too large) and `fullTokens` (registry-internal). Returns
+     * undefined if the response carries nothing worth caching.
+     */
+    function buildCacheEntry(ref, info) {
+        if (!info)
+            return undefined;
+        const toolSource = info.tools ?? info.toolSummaries;
+        const tools = toolSource?.map((t) => {
+            const slim = { name: t.name };
+            if (t.description !== undefined)
+                slim.description = t.description;
+            return slim;
+        });
+        if (info.description === undefined && (!tools || tools.length === 0)) {
+            return undefined;
+        }
+        const entry = {
+            ref,
+            fetchedAt: new Date().toISOString(),
+        };
+        if (info.description !== undefined)
+            entry.description = info.description;
+        if (tools && tools.length > 0)
+            entry.tools = tools;
+        return entry;
+    }
+    async function upsertRegistryCacheEntry(name, entry) {
+        if (!entry)
+            return;
+        const cache = await readRegistryCache();
+        cache.refs[name] = entry;
+        await writeRegistryCache(cache);
+    }
+    async function removeRegistryCacheEntry(name) {
+        const cache = await readRegistryCache();
+        if (!(name in cache.refs))
+            return;
+        delete cache.refs[name];
+        await writeRegistryCache(cache);
+    }
+    /**
+     * Hydrate a `ResolvedRef` with cached registry metadata when available.
+     * Pure: never mutates input. Leaves `description` / `tools` undefined when
+     * the cache has no entry, so callers can apply their own UX fallback.
+     */
+    function hydrateFromCache(ref, cache) {
+        const cached = cache.refs[ref.name];
+        if (!cached)
+            return ref;
+        const next = { ...ref };
+        if (cached.description !== undefined)
+            next.description = cached.description;
+        if (cached.tools !== undefined)
+            next.tools = cached.tools;
+        return next;
+    }
     /**
      * Store a secret value in a ref's config, encrypted if encryptionKey is set.
      * The value is stored inline as "secret:<encrypted>" in consumer-config.json.
@@ -208,6 +304,47 @@ export function createAdk(fs, options = {}) {
         }
         return value;
     }
+    /**
+     * Build a `tryResolve(field, oauthMetadata?)` function bound to a
+     * specific ref + entry + security context. Wraps the host-injected
+     * `resolveCredentials` callback (e.g. atlas's env/static/tenant chain
+     * for first-party agents). Errors propagate to the caller.
+     */
+    function makeTryResolve(ctx) {
+        return async (field, oauthMetadata) => {
+            const resolve = options.resolveCredentials;
+            if (!resolve)
+                return null;
+            return resolve({
+                ref: ctx.name,
+                field,
+                entry: ctx.entry,
+                security: ctx.security,
+                oauthMetadata,
+            });
+        };
+    }
+    /**
+     * Resolve OAuth client credentials (client_id + client_secret) for a
+     * ref. Walks: `resolveCredentials` callback → per-ref VCS storage.
+     * Used by both `auth` (initial OAuth flow) and `refreshToken` (token
+     * refresh) — must be a single function so the two paths can never
+     * disagree about where credentials live.
+     *
+     * Returns null when no client_id is available anywhere; caller decides
+     * whether to attempt dynamic registration (`auth`) or bail (`refresh`).
+     */
+    async function resolveOAuthClient(ctx) {
+        const tryResolve = makeTryResolve(ctx);
+        const clientId = (await tryResolve("client_id", ctx.metadata)) ??
+            (await readRefSecret(ctx.name, "client_id"));
+        if (!clientId)
+            return null;
+        const clientSecret = (await tryResolve("client_secret", ctx.metadata)) ??
+            (await readRefSecret(ctx.name, "client_secret")) ??
+            undefined;
+        return { clientId, ...(clientSecret && { clientSecret }) };
+    }
     const PENDING_OAUTH_PATH = "pending-oauth.json";
     async function readPendingOAuth() {
         const content = await fs.readFile(PENDING_OAUTH_PATH);
@@ -249,7 +386,10 @@ export function createAdk(fs, options = {}) {
         let reqId = 0;
         let sessionId;
         async function rpc(method, rpcParams) {
-            const reqHeaders = { ...headers, ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}) };
+            const reqHeaders = {
+                ...headers,
+                ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}),
+            };
             const res = await globalThis.fetch(url, {
                 method: "POST",
                 headers: reqHeaders,
@@ -290,7 +430,7 @@ export function createAdk(fs, options = {}) {
                 }
                 return undefined;
             }
-            const json = await res.json();
+            const json = (await res.json());
             if (json.error)
                 throw new Error(`MCP RPC error: ${json.error.message}`);
             return json.result;
@@ -302,20 +442,32 @@ export function createAdk(fs, options = {}) {
                 clientInfo: { name: "adk", version: "1.0.0" },
             });
             await rpc("notifications/initialized").catch(() => { });
-            const result = await rpc("tools/call", { name: toolName, arguments: params });
+            const result = (await rpc("tools/call", {
+                name: toolName,
+                arguments: params,
+            }));
             const textContent = result?.content?.find((c) => c.type === "text");
             if (textContent?.text) {
                 try {
-                    return { success: true, result: JSON.parse(textContent.text) };
+                    return {
+                        success: true,
+                        result: JSON.parse(textContent.text),
+                    };
                 }
                 catch {
-                    return { success: true, result: textContent.text };
+                    return {
+                        success: true,
+                        result: textContent.text,
+                    };
                 }
             }
             return { success: true, result };
         }
         catch (err) {
-            return { success: false, error: err instanceof Error ? err.message : String(err) };
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
         }
     }
     function callbackUrl() {
@@ -328,7 +480,7 @@ export function createAdk(fs, options = {}) {
             const res = await globalThis.fetch(url);
             if (!res.ok)
                 return null;
-            const data = await res.json();
+            const data = (await res.json());
             if (data.authorization_endpoint && data.token_endpoint) {
                 return data;
             }
@@ -698,7 +850,9 @@ export function createAdk(fs, options = {}) {
                                 ...final,
                                 proxy: {
                                     mode: discovered.proxy.mode,
-                                    ...(discovered.proxy.agent && { agent: discovered.proxy.agent }),
+                                    ...(discovered.proxy.agent && {
+                                        agent: discovered.proxy.agent,
+                                    }),
                                 },
                             };
                         }
@@ -825,7 +979,12 @@ export function createAdk(fs, options = {}) {
             }));
             return results.map((r) => r.status === "fulfilled"
                 ? r.value
-                : { name: "unknown", url: "unknown", status: "error", error: "unknown" });
+                : {
+                    name: "unknown",
+                    url: "unknown",
+                    status: "error",
+                    error: "unknown",
+                });
         },
         async auth(nameOrUrl, credential) {
             // Encrypt the secret value up-front so the write path is uniform;
@@ -1105,7 +1264,10 @@ export function createAdk(fs, options = {}) {
                     entry = { ...entry, scheme: "registry" };
                 }
                 else if (entry.url) {
-                    entry = { ...entry, scheme: entry.url.startsWith("http") ? "https" : "mcp" };
+                    entry = {
+                        ...entry,
+                        scheme: entry.url.startsWith("http") ? "https" : "mcp",
+                    };
                 }
                 else {
                     throw new AdkError({
@@ -1133,6 +1295,7 @@ export function createAdk(fs, options = {}) {
                     details: { ref: entry.ref, scheme: entry.scheme },
                 });
             }
+            let cacheEntry;
             if (hasRegistries || entry.sourceRegistry?.url) {
                 try {
                     const consumer = await buildConsumerForRef(entry);
@@ -1140,9 +1303,10 @@ export function createAdk(fs, options = {}) {
                     const info = await consumer.inspect(agentToInspect);
                     const requiresValidation = !!entry.sourceRegistry;
                     if (requiresValidation) {
-                        const hasContent = info && (info.description ||
-                            (info.tools && info.tools.length > 0) ||
-                            (info.toolSummaries && info.toolSummaries.length > 0));
+                        const hasContent = info &&
+                            (info.description ||
+                                (info.tools && info.tools.length > 0) ||
+                                (info.toolSummaries && info.toolSummaries.length > 0));
                         if (!hasContent) {
                             // Inspect returned empty — fall back to browse to check if agent exists
                             const registryUrl = entry.sourceRegistry?.url;
@@ -1164,7 +1328,11 @@ export function createAdk(fs, options = {}) {
                                     code: "REF_NOT_FOUND",
                                     message: `Agent "${entry.ref}" not found on ${registryHint}`,
                                     hint: "Check available agents with: adk registry browse",
-                                    details: { ref: entry.ref, sourceRegistry: entry.sourceRegistry, scheme: entry.scheme },
+                                    details: {
+                                        ref: entry.ref,
+                                        sourceRegistry: entry.sourceRegistry,
+                                        scheme: entry.scheme,
+                                    },
                                 });
                             }
                         }
@@ -1174,10 +1342,11 @@ export function createAdk(fs, options = {}) {
                     const agentMode = info?.mode;
                     if (agentMode)
                         entry.mode = agentMode;
-                    if (info?.upstream && !entry.url && agentMode !== 'api') {
+                    if (info?.upstream && !entry.url && agentMode !== "api") {
                         entry.url = info.upstream;
                         entry.scheme = entry.scheme ?? "mcp";
                     }
+                    cacheEntry = buildCacheEntry(entry.ref, info);
                 }
                 catch (err) {
                     if (err instanceof AdkError)
@@ -1186,13 +1355,17 @@ export function createAdk(fs, options = {}) {
                         code: "REGISTRY_UNREACHABLE",
                         message: `Could not reach registry to validate "${entry.ref}"`,
                         hint: "Check your registry connection with: adk registry test",
-                        details: { ref: entry.ref, error: err instanceof Error ? err.message : String(err) },
+                        details: {
+                            ref: entry.ref,
+                            error: err instanceof Error ? err.message : String(err),
+                        },
                         cause: err,
                     });
                 }
             }
             const refs = [...(config.refs ?? []), entry];
             await writeConfig({ ...config, refs });
+            await upsertRegistryCacheEntry(name, cacheEntry);
             return { security };
         },
         async remove(name) {
@@ -1204,15 +1377,27 @@ export function createAdk(fs, options = {}) {
             if (refs.length === before)
                 return false;
             await writeConfig({ ...config, refs });
+            await removeRegistryCacheEntry(name);
             return true;
         },
         async list() {
-            const config = await readConfig();
-            return (config.refs ?? []).map(normalizeRef);
+            const [config, cache] = await Promise.all([
+                readConfig(),
+                readRegistryCache(),
+            ]);
+            return (config.refs ?? [])
+                .map(normalizeRef)
+                .map((r) => hydrateFromCache(r, cache));
         },
         async get(name) {
-            const config = await readConfig();
-            return findRef(config.refs ?? [], name) ?? null;
+            const [config, cache] = await Promise.all([
+                readConfig(),
+                readRegistryCache(),
+            ]);
+            const found = findRef(config.refs ?? [], name);
+            if (!found)
+                return null;
+            return hydrateFromCache(found, cache);
         },
         async update(name, updates) {
             const config = await readConfig();
@@ -1258,27 +1443,35 @@ export function createAdk(fs, options = {}) {
             if (!entry)
                 throw new Error(`Ref "${name}" not found`);
             const consumer = await buildConsumerForRef(entry);
-            return consumer.inspect(entry.sourceRegistry?.agentPath ?? entry.ref, entry.sourceRegistry?.url, opts);
+            const result = await consumer.inspect(entry.sourceRegistry?.agentPath ?? entry.ref, entry.sourceRegistry?.url, opts);
+            // Side-effect: refresh the registry cache so subsequent ref.list()
+            // / ref.get() calls see the latest description and tool summaries
+            // without another network round-trip. Strips inputSchema (caller's
+            // `result` is unaffected — it still carries the full data).
+            await upsertRegistryCacheEntry(name, buildCacheEntry(entry.ref, result));
+            return result;
         },
         async call(name, tool, params) {
             const config = await readConfig();
             const entry = findRef(config.refs ?? [], name);
             if (!entry)
                 throw new Error(`Ref "${name}" not found`);
-            let accessToken = await readRefSecret(name, "access_token")
-                ?? await readRefSecret(name, "api_key")
-                ?? await readRefSecret(name, "token");
+            const accessToken = (await readRefSecret(name, "access_token")) ??
+                (await readRefSecret(name, "api_key")) ??
+                (await readRefSecret(name, "token"));
             // Resolve custom headers from config (e.g. { "X-API-Key": "secret:..." })
             const refConfig = (entry.config ?? {});
             const rawHeaders = refConfig.headers;
             let resolvedHeaders;
-            if (rawHeaders && typeof rawHeaders === 'object') {
+            if (rawHeaders && typeof rawHeaders === "object") {
                 resolvedHeaders = {};
                 for (const [k, v] of Object.entries(rawHeaders)) {
-                    if (typeof v === 'string' && v.startsWith(SECRET_PREFIX) && options.encryptionKey) {
+                    if (typeof v === "string" &&
+                        v.startsWith(SECRET_PREFIX) &&
+                        options.encryptionKey) {
                         resolvedHeaders[k] = await decryptSecret(v.slice(SECRET_PREFIX.length), options.encryptionKey);
                     }
-                    else if (typeof v === 'string') {
+                    else if (typeof v === "string") {
                         resolvedHeaders[k] = v;
                     }
                 }
@@ -1286,8 +1479,8 @@ export function createAdk(fs, options = {}) {
             const doCall = async (token) => {
                 // Direct MCP only for redirect/proxy agents with an MCP upstream.
                 // API-mode agents must go through the registry (it does REST translation).
-                const agentMode = entry.mode ?? 'redirect';
-                if (token && entry.url && agentMode !== 'api') {
+                const agentMode = entry.mode ?? "redirect";
+                if (token && entry.url && agentMode !== "api") {
                     return callMcpDirect(entry.url, tool, params ?? {}, token, resolvedHeaders);
                 }
                 const consumer = await buildConsumerForRef(entry);
@@ -1363,12 +1556,9 @@ export function createAdk(fs, options = {}) {
                 return { name, security, complete: true, fields: {} };
             }
             const configKeys = Object.keys(entry.config ?? {});
-            const resolve = options.resolveCredentials;
+            const tryResolveField = makeTryResolve({ name, entry, security });
             async function canResolve(field, oauthMetadata) {
-                if (!resolve || !entry)
-                    return false;
-                const val = await resolve({ ref: name, field, entry, security, oauthMetadata });
-                return val !== null;
+                return (await tryResolveField(field, oauthMetadata)) !== null;
             }
             const fields = {};
             if (security.type === "oauth2") {
@@ -1406,10 +1596,15 @@ export function createAdk(fs, options = {}) {
             }
             else if (security.type === "apiKey") {
                 const apiKeySec = security;
-                const toStorageKey = (headerName) => headerName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+                const toStorageKey = (headerName) => headerName
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, "_")
+                    .replace(/^_|_$/g, "");
                 // config.headers: { "Header-Name": "value" } — check by header name (case-insensitive)
                 const configHeaders = entry?.config?.headers;
-                const configHeaderKeys = configHeaders ? Object.keys(configHeaders) : [];
+                const configHeaderKeys = configHeaders
+                    ? Object.keys(configHeaders)
+                    : [];
                 const hasConfigHeader = (name) => configHeaderKeys.some((k) => k.toLowerCase() === name.toLowerCase());
                 // Collect all declared header names from the security scheme
                 const declaredHeaders = apiKeySec.headers
@@ -1458,7 +1653,9 @@ export function createAdk(fs, options = {}) {
             // agent. The registry owns the client_id/secret and returns an authorize
             // URL pointing at the registry's OAuth callback domain, so the user
             // completes the flow against the registry instead of localhost.
-            const proxy = await resolveProxyForRef(entry, { preferLocal: opts?.preferLocal });
+            const proxy = await resolveProxyForRef(entry, {
+                preferLocal: opts?.preferLocal,
+            });
             if (proxy) {
                 const params = { name };
                 if (opts?.apiKey !== undefined)
@@ -1473,23 +1670,24 @@ export function createAdk(fs, options = {}) {
             }
             const status = await ref.authStatus(name);
             const security = status.security;
-            const resolve = options.resolveCredentials;
-            async function tryResolve(field, oauthMetadata) {
-                if (!resolve)
-                    return null;
-                return resolve({ ref: name, field, entry: entry, security, oauthMetadata });
-            }
+            const tryResolve = makeTryResolve({ name, entry, security });
             if (!security || security.type === "none") {
                 return { type: "none", complete: true };
             }
             if (security.type === "apiKey") {
                 const apiKeySec = security;
-                const toStorageKey = (headerName) => headerName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+                const toStorageKey = (headerName) => headerName
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, "_")
+                    .replace(/^_|_$/g, "");
                 // Check existing config.headers
                 const existingHeaders = (entry.config ?? {}).headers;
                 // Collect declared headers: from security.headers or security.name
                 const declaredHeaders = apiKeySec.headers
-                    ? Object.entries(apiKeySec.headers).map(([h, meta]) => ({ headerName: h, description: meta.description }))
+                    ? Object.entries(apiKeySec.headers).map(([h, meta]) => ({
+                        headerName: h,
+                        description: meta.description,
+                    }))
                     : apiKeySec.name
                         ? [{ headerName: apiKeySec.name }]
                         : [];
@@ -1499,12 +1697,13 @@ export function createAdk(fs, options = {}) {
                     for (const { headerName, description } of declaredHeaders) {
                         const storageKey = toStorageKey(headerName);
                         // Check: credentials param → existing config.headers → legacy config key → resolve callback
-                        const value = opts?.credentials?.[storageKey]
-                            ?? opts?.credentials?.[headerName]
-                            ?? (existingHeaders && Object.entries(existingHeaders).find(([k]) => k.toLowerCase() === headerName.toLowerCase())?.[1])
-                            ?? opts?.apiKey
-                            ?? await readRefSecret(name, storageKey)
-                            ?? await tryResolve(storageKey);
+                        const value = opts?.credentials?.[storageKey] ??
+                            opts?.credentials?.[headerName] ??
+                            (existingHeaders &&
+                                Object.entries(existingHeaders).find(([k]) => k.toLowerCase() === headerName.toLowerCase())?.[1]) ??
+                            opts?.apiKey ??
+                            (await readRefSecret(name, storageKey)) ??
+                            (await tryResolve(storageKey));
                         if (value) {
                             resolvedHeaders[headerName] = value;
                         }
@@ -1524,22 +1723,28 @@ export function createAdk(fs, options = {}) {
                     const encKey = options.encryptionKey;
                     const headersToStore = {};
                     for (const [h, v] of Object.entries(resolvedHeaders)) {
-                        headersToStore[h] = encKey ? `${SECRET_PREFIX}${await encryptSecret(v, encKey)}` : v;
+                        headersToStore[h] = encKey
+                            ? `${SECRET_PREFIX}${await encryptSecret(v, encKey)}`
+                            : v;
                     }
                     await ref.update(name, { config: { headers: headersToStore } });
                     return { type: "apiKey", complete: true };
                 }
                 // Fallback: no headers declared → generic api_key
-                const key = opts?.credentials?.["api_key"] ?? opts?.apiKey ?? await tryResolve("api_key");
+                const key = opts?.credentials?.["api_key"] ??
+                    opts?.apiKey ??
+                    (await tryResolve("api_key"));
                 if (!key) {
                     return {
                         type: "apiKey",
                         complete: false,
-                        fields: [{
+                        fields: [
+                            {
                                 name: "api_key",
                                 label: "API Key",
                                 secret: true,
-                            }],
+                            },
+                        ],
                     };
                 }
                 await storeRefSecret(name, "api_key", key);
@@ -1549,14 +1754,22 @@ export function createAdk(fs, options = {}) {
                 const httpSec = security;
                 const isBasic = httpSec.scheme === "basic";
                 if (isBasic) {
-                    const username = opts?.credentials?.["username"] ?? await tryResolve("username");
-                    const password = opts?.credentials?.["password"] ?? await tryResolve("password");
+                    const username = opts?.credentials?.["username"] ?? (await tryResolve("username"));
+                    const password = opts?.credentials?.["password"] ?? (await tryResolve("password"));
                     if (!username || !password) {
                         const missingFields = [];
                         if (!username)
-                            missingFields.push({ name: "username", label: "Username", secret: false });
+                            missingFields.push({
+                                name: "username",
+                                label: "Username",
+                                secret: false,
+                            });
                         if (!password)
-                            missingFields.push({ name: "password", label: "Password", secret: true });
+                            missingFields.push({
+                                name: "password",
+                                label: "Password",
+                                secret: true,
+                            });
                         return { type: "http", complete: false, fields: missingFields };
                     }
                     // Store as base64 encoded basic auth token
@@ -1565,7 +1778,9 @@ export function createAdk(fs, options = {}) {
                     return { type: "http", complete: true };
                 }
                 // Bearer token
-                const token = opts?.credentials?.["token"] ?? opts?.apiKey ?? await tryResolve("token");
+                const token = opts?.credentials?.["token"] ??
+                    opts?.apiKey ??
+                    (await tryResolve("token"));
                 if (!token) {
                     return {
                         type: "http",
@@ -1610,17 +1825,21 @@ export function createAdk(fs, options = {}) {
                 }
                 const redirectUri = callbackUrl();
                 // Resolve client credentials: callback → stored → dynamic registration
-                let clientId = await tryResolve("client_id", metadata)
-                    ?? await readRefSecret(name, "client_id");
-                let clientSecret = await tryResolve("client_secret", metadata)
-                    ?? await readRefSecret(name, "client_secret")
-                    ?? undefined;
+                const fromHelper = await resolveOAuthClient({
+                    name,
+                    entry,
+                    security,
+                    metadata,
+                });
+                let clientId = fromHelper?.clientId;
+                let clientSecret = fromHelper?.clientSecret;
                 if (!clientId && metadata.registration_endpoint) {
                     const supportedAuthMethods = metadata.token_endpoint_auth_methods_supported ?? ["none"];
                     const preferredMethod = supportedAuthMethods.includes("none")
                         ? "none"
-                        : supportedAuthMethods[0] ?? "client_secret_post";
-                    const securityClientName = security.clientName;
+                        : (supportedAuthMethods[0] ?? "client_secret_post");
+                    const securityClientName = security
+                        .clientName;
                     const reg = await dynamicClientRegistration(metadata.registration_endpoint, {
                         clientName: securityClientName ?? options.oauthClientName ?? "adk",
                         redirectUris: [redirectUri],
@@ -1638,10 +1857,18 @@ export function createAdk(fs, options = {}) {
                     // Return fields telling the caller what OAuth credentials to provide
                     const missingFields = [];
                     if (!clientId) {
-                        missingFields.push({ name: "client_id", label: "Client ID", secret: false });
+                        missingFields.push({
+                            name: "client_id",
+                            label: "Client ID",
+                            secret: false,
+                        });
                     }
                     // Always ask for client_secret alongside client_id — most providers need it
-                    missingFields.push({ name: "client_secret", label: "Client Secret", secret: true });
+                    missingFields.push({
+                        name: "client_secret",
+                        label: "Client Secret",
+                        secret: true,
+                    });
                     return { type: "oauth2", complete: false, fields: missingFields };
                 }
                 // State ties the callback back to this ref. Encode as base64 JSON
@@ -1663,7 +1890,9 @@ export function createAdk(fs, options = {}) {
                 const scopes = agentScopes.length > 0
                     ? [
                         ...agentScopes,
-                        ...(metadata.scopes_supported?.includes('openid') ? ['openid'] : []),
+                        ...(metadata.scopes_supported?.includes("openid")
+                            ? ["openid"]
+                            : []),
                     ]
                     : metadata.scopes_supported;
                 // Read provider-specific authorization params from the agent's security section
@@ -1712,7 +1941,9 @@ export function createAdk(fs, options = {}) {
             // owns the credential store, so the user needs to submit via
             // whatever UI the registry exposes. Supporting this through the
             // proxy would need a remote form endpoint — out of scope here.
-            if (result.fields && result.fields.length > 0 && result.type !== "oauth2") {
+            if (result.fields &&
+                result.fields.length > 0 &&
+                result.type !== "oauth2") {
                 if (proxy) {
                     throw new Error(`Ref "${name}" is sourced from a proxied registry; submit credentials through ${proxy.agent} instead of a local form.`);
                 }
@@ -1834,22 +2065,28 @@ export function createAdk(fs, options = {}) {
             const refreshToken = await readRefSecret(name, "refresh_token");
             if (!refreshToken)
                 return null;
-            // Read client credentials
-            const clientId = await readRefSecret(name, "client_id");
-            if (!clientId)
-                return null;
-            const clientSecret = await readRefSecret(name, "client_secret");
-            // Get the agent's token endpoint from its security metadata
+            // Resolve token endpoint + OAuth client via the host's
+            // `resolveCredentials` chain. Same chain `auth` uses (see
+            // `resolveOAuthClient`) — kept symmetric so refresh works on every
+            // ref `auth` works on, including first-party registry-hosted
+            // clients whose creds live in env / tenant scope, not the user's
+            // per-ref config.
             const entry = await ref.get(name);
             if (!entry)
                 return null;
-            const info = await ref.inspect(name);
-            const security = info?.security;
-            const flows = security?.flows;
+            const status = await ref.authStatus(name);
+            const security = status.security;
+            const flows = security && "flows" in security
+                ? security.flows
+                : undefined;
             const authCodeFlow = flows?.authorizationCode;
-            const tokenUrl = (authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl);
+            const tokenUrl = authCodeFlow?.refreshUrl ?? authCodeFlow?.tokenUrl;
             if (!tokenUrl)
                 return null;
+            const oauthClient = await resolveOAuthClient({ name, entry, security });
+            if (!oauthClient)
+                return null;
+            const { clientId, clientSecret } = oauthClient;
             // POST to the token endpoint with grant_type=refresh_token
             const body = new URLSearchParams({
                 grant_type: "refresh_token",
@@ -1866,7 +2103,7 @@ export function createAdk(fs, options = {}) {
             });
             if (!res.ok)
                 return null;
-            const data = await res.json();
+            const data = (await res.json());
             const newAccessToken = data.access_token;
             if (!newAccessToken)
                 return null;
@@ -1901,7 +2138,9 @@ export function createAdk(fs, options = {}) {
         try {
             stateContext = JSON.parse(atob(params.state));
         }
-        catch { /* state wasn't base64 JSON — legacy format */ }
+        catch {
+            /* state wasn't base64 JSON — legacy format */
+        }
         return { refName: pending.refName, complete: true, stateContext };
     }
     return { registry, ref, readConfig, writeConfig, handleCallback };