@slashfi/agents-sdk 0.40.1 → 0.41.1

package/src/config-store.ts

@@ -20,6 +20,7 @@
 import type { FsStore } from "./agent-definitions/config.js";
 import type {
   ConsumerConfig,
+  ProxyEntry,
   RefEntry,
   RegistryEntry,
   ResolvedRef,
@@ -33,6 +34,7 @@ import type {
 } from "./registry-consumer.js";
 import type { CallAgentResponse, SecuritySchemeSummary } from "./types.js";
 import { decryptSecret, encryptSecret } from "./crypto.js";
+import { AdkError } from "./adk-error.js";
 import {
   discoverOAuthMetadata,
   dynamicClientRegistration,
@@ -47,6 +49,29 @@ const SECRET_PREFIX = "secret:";
 // Types
 // ============================================
 
+/** Context passed to the resolveCredentials callback */
+export interface ResolveCredentialsContext {
+  /** Ref name */
+  ref: string;
+  /** Credential field being resolved (e.g. "client_id", "client_secret", "api_key") */
+  field: string;
+  /** The full ref entry from config */
+  entry: RefEntry;
+  /** Security scheme from the registry */
+  security: SecuritySchemeSummary | null;
+  /** OAuth metadata if available (from discovery) */
+  oauthMetadata?: import("./mcp-client.js").OAuthServerMetadata | null;
+}
+
+/**
+ * Resolve a credential field for a ref.
+ * Called during auth() when the adk needs a credential it can't auto-obtain.
+ * Return the value, or null to indicate it's not available.
+ */
+export type ResolveCredentials = (
+  ctx: ResolveCredentialsContext,
+) => Promise<string | null>;
+
 export interface AdkOptions {
   /** Passphrase for encrypting/decrypting secret: values */
   encryptionKey?: string;
@@ -60,8 +85,14 @@ export interface AdkOptions {
   oauthCallbackUrl?: string;
   /** Port for local OAuth callback server (default 8919) */
   oauthCallbackPort?: number;
-  /** Client name for OAuth dynamic client registration (default: "Claude Code") */
+  /** Client name for OAuth dynamic client registration (default: "adk") */
   oauthClientName?: string;
+  /**
+   * Resolve preconfigured credentials for a ref.
+   * Used by atlas to inject platform-level or tenant-level credentials
+   * (e.g. client_id/client_secret) before the user auth flow runs.
+   */
+  resolveCredentials?: ResolveCredentials;
 }
 
 export interface RegistryTestResult {
@@ -83,16 +114,25 @@ export interface AdkRegistryApi {
   test(name?: string): Promise<RegistryTestResult[]>;
 }
 
+/** Describes a single credential field requirement */
+export interface CredentialField {
+  required: boolean;
+  /** Can be obtained automatically (dynamic registration, OAuth flow) */
+  automated: boolean;
+  /** Already present in the ref's config */
+  present: boolean;
+  /** Available via resolveCredentials callback */
+  resolvable: boolean;
+}
+
 /** Describes what auth a ref needs and what's already provided */
 export interface RefAuthStatus {
   name: string;
   security: SecuritySchemeSummary | null;
-  /** All required secret fields are present (may be untested) */
+  /** All required fields are either present, resolvable, or automated */
   complete: boolean;
-  /** Fields that still need to be provided */
-  missing: string[];
-  /** Fields already stored */
-  present: string[];
+  /** Per-field breakdown */
+  fields: Record<string, CredentialField>;
 }
 
 export interface OAuthResult {
@@ -143,7 +183,14 @@ export interface AdkRefApi {
   }): Promise<{ complete: boolean }>;
 }
 
+export interface AdkProxyApi {
+  add(entry: ProxyEntry): Promise<void>;
+  remove(name: string): Promise<boolean>;
+  list(): Promise<ProxyEntry[]>;
+}
+
 export interface Adk {
+  proxy: AdkProxyApi;
   registry: AdkRegistryApi;
   ref: AdkRefApi;
   readConfig(): Promise<ConsumerConfig>;
@@ -547,21 +594,48 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
   const ref: AdkRefApi = {
     async add(entry: RefEntry): Promise<{ security: SecuritySchemeSummary | null }> {
+      let security: SecuritySchemeSummary | null = null;
+
       const config = await readConfig();
+      const hasRegistries = (config.registries ?? []).length > 0;
+
+      if (hasRegistries) {
+        try {
+          const consumer = await buildConsumer();
+          const info = await consumer.inspect(entry.ref);
+
+          const agentExists = info && (info.description || info.tools?.length || info.toolSummaries?.length);
+          if (!agentExists && entry.sourceRegistry) {
+            throw new AdkError({
+              code: "REF_NOT_FOUND",
+              message: `Agent "${entry.ref}" not found on registry ${entry.sourceRegistry.url}`,
+              hint: `Check available agents with: adk registry browse ${entry.sourceRegistry.url}`,
+              details: { ref: entry.ref, sourceRegistry: entry.sourceRegistry },
+            });
+          }
+
+          if (info?.security) security = info.security;
+          if (info?.upstream && !entry.url) {
+            entry.url = info.upstream as string;
+            entry.scheme = entry.scheme ?? "mcp";
+          }
+        } catch (err) {
+          if (err instanceof AdkError) throw err;
+          throw new AdkError({
+            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) },
+            cause: err,
+          });
+        }
+      }
+
       const name = refName(entry);
       const refs = (config.refs ?? []).filter((r) => refName(r) !== name);
       refs.push(entry);
       await writeConfig({ ...config, refs });
 
-      // Check security requirements
-      let security: SecuritySchemeSummary | null = null;
-      try {
-        const consumer = await buildConsumer();
-        const info = await consumer.inspect(entry.ref);
-        if (info?.security) security = info.security;
-      } catch {
-        // Non-fatal — registry might be unreachable
-      }
       return { security };
     },
 
@@ -623,18 +697,8 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
       // If we have a direct access_token from OAuth, call the agent's MCP server
       // directly instead of going through the registry
-      if (accessToken) {
-        const info = await ref.inspect(name);
-        // Use upstream URL from registry if available, fall back to deriving from OAuth URL
-        const upstream = (info as { upstream?: string } | null)?.upstream;
-        const security = info?.security as { type: string; flows?: { authorizationCode?: { authorizationUrl?: string } } } | undefined;
-        const mcpUrl = upstream
-          ?? (security?.flows?.authorizationCode?.authorizationUrl
-            ? `${new URL(security.flows.authorizationCode.authorizationUrl).origin}/mcp`
-            : null);
-        if (mcpUrl) {
-          return callMcpDirect(mcpUrl, tool, params ?? {}, accessToken);
-        }
+      if (accessToken && entry.url) {
+        return callMcpDirect(entry.url, tool, params ?? {}, accessToken);
       }
 
       const consumer = await buildConsumer();
@@ -694,46 +758,112 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         // Can't reach registry
       }
 
+      if (!security || security.type === "none") {
+        return { name, security, complete: true, fields: {} };
+      }
+
       const configKeys = Object.keys(entry.config ?? {});
+      const resolve = options.resolveCredentials;
 
-      if (!security || security.type === "none") {
-        return { name, security, complete: true, missing: [], present: configKeys };
+      async function canResolve(field: string, oauthMetadata?: import("./mcp-client.js").OAuthServerMetadata | null): Promise<boolean> {
+        if (!resolve || !entry) return false;
+        const val = await resolve({ ref: name, field, entry, security, oauthMetadata });
+        return val !== null;
       }
 
-      const requiredFields = (() => {
-        switch (security.type) {
-          case "oauth2": return ["access_token"];
-          case "apiKey": return ["api_key"];
-          case "http": return ["token"];
-          default: return [];
+      const fields: Record<string, CredentialField> = {};
+
+      if (security.type === "oauth2") {
+        const securityExt = security as {
+          dynamicRegistration?: boolean;
+          discoveryUrl?: string;
+        };
+        const hasRegistration = !!securityExt.dynamicRegistration;
+
+        let oauthMetadata: import("./mcp-client.js").OAuthServerMetadata | null = null;
+        let needsSecret = false;
+        if (securityExt.discoveryUrl) {
+          oauthMetadata = await tryFetchOAuthMetadata(securityExt.discoveryUrl);
+          if (oauthMetadata) {
+            const authMethods = oauthMetadata.token_endpoint_auth_methods_supported ?? [];
+            needsSecret = !authMethods.includes("none");
+          }
         }
-      })();
 
-      const missing = requiredFields.filter((f) => !configKeys.includes(f));
-      const present = requiredFields.filter((f) => configKeys.includes(f));
+        fields.client_id = {
+          required: true,
+          automated: hasRegistration,
+          present: configKeys.includes("client_id"),
+          resolvable: await canResolve("client_id", oauthMetadata),
+        };
+        if (needsSecret) {
+          fields.client_secret = {
+            required: true,
+            automated: hasRegistration,
+            present: configKeys.includes("client_secret"),
+            resolvable: await canResolve("client_secret", oauthMetadata),
+          };
+        }
+        fields.access_token = {
+          required: true,
+          automated: true,
+          present: configKeys.includes("access_token"),
+          resolvable: false,
+        };
+      } else if (security.type === "apiKey") {
+        fields.api_key = {
+          required: true,
+          automated: false,
+          present: configKeys.includes("api_key"),
+          resolvable: await canResolve("api_key"),
+        };
+      } else if (security.type === "http") {
+        fields.token = {
+          required: true,
+          automated: false,
+          present: configKeys.includes("token"),
+          resolvable: await canResolve("token"),
+        };
+      }
 
-      return { name, security, complete: missing.length === 0, missing, present };
+      const complete = Object.values(fields).every(
+        (f) => !f.required || f.present || f.resolvable || f.automated,
+      );
+
+      return { name, security, complete, fields };
     },
 
     async auth(name: string, opts?: {
       apiKey?: string;
     }): Promise<AuthStartResult> {
+      const config = await readConfig();
+      const entry = (config.refs ?? []).find((r) => refName(r) === name);
+      if (!entry) throw new Error(`Ref "${name}" not found`);
+
       const status = await ref.authStatus(name);
       const security = status.security;
+      const resolve = options.resolveCredentials;
+
+      async function tryResolve(field: string, oauthMetadata?: import("./mcp-client.js").OAuthServerMetadata | null): Promise<string | null> {
+        if (!resolve) return null;
+        return resolve({ ref: name, field, entry: entry!, security, oauthMetadata });
+      }
 
       if (!security || security.type === "none") {
         return { type: "none", complete: true };
       }
 
       if (security.type === "apiKey") {
-        if (!opts?.apiKey) return { type: "apiKey", complete: false };
-        await storeRefSecret(name, "api_key", opts.apiKey);
+        const key = opts?.apiKey ?? await tryResolve("api_key");
+        if (!key) return { type: "apiKey", complete: false };
+        await storeRefSecret(name, "api_key", key);
         return { type: "apiKey", complete: true };
       }
 
       if (security.type === "http") {
-        if (!opts?.apiKey) return { type: "http", complete: false };
-        await storeRefSecret(name, "token", opts.apiKey);
+        const token = opts?.apiKey ?? await tryResolve("token");
+        if (!token) return { type: "http", complete: false };
+        await storeRefSecret(name, "token", token);
         return { type: "http", complete: true };
       }
 
@@ -744,11 +874,9 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           return { type: "oauth2", complete: false };
         }
 
-        // The authorizationUrl might be the discovery URL itself or a base URL
         const authUrl = authCodeFlow.authorizationUrl;
         let metadata = await tryFetchOAuthMetadata(authUrl);
         if (!metadata) {
-          // Try base origin
           const origin = new URL(authUrl).origin;
           metadata = await discoverOAuthMetadata(origin);
         }
@@ -758,10 +886,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
         const redirectUri = callbackUrl();
 
-        // Dynamic client registration if supported
-        let clientId: string;
-        let clientSecret: string | undefined;
-        if (metadata.registration_endpoint) {
+        // 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;
+
+        if (!clientId && metadata.registration_endpoint) {
           const supportedAuthMethods = metadata.token_endpoint_auth_methods_supported ?? ["none"];
           const preferredMethod = supportedAuthMethods.includes("none")
             ? "none"
@@ -780,15 +912,12 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           if (clientSecret) {
             await storeRefSecret(name, "client_secret", clientSecret);
           }
-        } else {
-          const stored = await readRefSecret(name, "client_id");
-          if (!stored) {
-            throw new Error(
-              "OAuth server doesn't support dynamic client registration. " +
-              "Store a client_id first.",
-            );
-          }
-          clientId = stored;
+        }
+
+        if (!clientId) {
+          throw new Error(
+            "Could not obtain client_id. Provide via resolveCredentials callback or store manually.",
+          );
         }
 
         // State ties the callback back to this ref
@@ -906,5 +1035,33 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
     return { refName: pending.refName, complete: true };
   }
 
-  return { registry, ref, readConfig, writeConfig, handleCallback };
+  // ==========================================
+  // Proxy API
+  // ==========================================
+
+  const proxy: AdkProxyApi = {
+    async add(entry: ProxyEntry): Promise<void> {
+      const config = await readConfig();
+      const proxies = (config.proxies ?? []).filter((p) => p.name !== entry.name);
+      proxies.push(entry);
+      await writeConfig({ ...config, proxies });
+    },
+
+    async remove(name: string): Promise<boolean> {
+      const config = await readConfig();
+      if (!config.proxies?.length) return false;
+      const before = config.proxies.length;
+      const proxies = config.proxies.filter((p) => p.name !== name);
+      if (proxies.length === before) return false;
+      await writeConfig({ ...config, proxies });
+      return true;
+    },
+
+    async list(): Promise<ProxyEntry[]> {
+      const config = await readConfig();
+      return config.proxies ?? [];
+    },
+  };
+
+  return { proxy, registry, ref, readConfig, writeConfig, handleCallback };
 }

package/src/define-config.ts

@@ -86,12 +86,35 @@ export type RefEntry = {
       status?: 'active' | 'inactive' | 'error';
     };
 
+// ============================================
+// Proxy Config
+// ============================================
+
+/** A proxy target — remote adk server that handles ref/registry operations */
+export interface ProxyEntry {
+  /** Human-readable name */
+  name: string;
+  /** URL of the remote server */
+  url: string;
+  /** Connection type: 'mcp' (direct MCP server) or 'registry' (agent on a registry) */
+  type: 'mcp' | 'registry';
+  /** For type 'registry': the agent path that implements adk tools (e.g. '@config') */
+  agent?: string;
+  /** Auth for connecting to the proxy */
+  auth?: RegistryAuth;
+  /** Whether this is the default proxy when no local refs/registries exist */
+  default?: boolean;
+}
+
 // ============================================
 // Consumer Config
 // ============================================
 
 /** The full consumer configuration */
 export interface ConsumerConfig {
+  /** Remote adk proxies — forward operations to a remote server */
+  proxies?: ProxyEntry[];
+
   /** Registries to connect to, in resolution order */
   registries?: (string | RegistryEntry)[];
 

package/src/index.ts

@@ -292,6 +292,7 @@ export {
 export type {
   RegistryAuth,
   RegistryEntry,
+  ProxyEntry,
   RefConfig,
   RefEntry,
   ConsumerConfig,
@@ -453,11 +454,18 @@ export { createAdk } from "./config-store.js";
 export type {
   Adk,
   AdkOptions,
+  AdkProxyApi,
   AdkRegistryApi,
   AdkRefApi,
   RefAuthStatus,
+  CredentialField,
   AuthStartResult,
   OAuthResult,
+  ResolveCredentials,
+  ResolveCredentialsContext,
   RegistryTestResult,
 } from "./config-store.js";
 export { createLocalFsStore, getLocalEncryptionKey } from "./local-fs.js";
+export { AdkError, getError, getRecentErrors } from "./adk-error.js";
+export { createAdkTools } from "./adk-tools.js";
+export type { CreateAdkToolsOptions } from "./adk-tools.js";

package/src/registry-consumer.ts

@@ -224,6 +224,8 @@ export interface AgentListing {
   }>;
   /** Context hint from describe_tools (e.g., "Use full: true for complete schemas") */
   context?: string;
+  /** Upstream MCP/API URL for direct connections */
+  upstream?: string;
   /** Integration config if applicable */
   integration?: {
     provider: string;
@@ -928,6 +930,7 @@ export async function createRegistryConsumer(
             security?: SecuritySchemeSummary;
             resources?: Array<{ uri: string; name?: string; mimeType?: string }>;
             context?: string;
+            upstream?: string;
           } | null;
           if (!data) return null;
           return {
@@ -939,6 +942,7 @@ export async function createRegistryConsumer(
             security: data.security,
             resources: data.resources,
             context: data.context,
+            ...(data.upstream && { upstream: data.upstream }),
           } as AgentListing;
         }),
       );