@slashfi/agents-sdk 0.40.0 → 0.41.0

package/src/adk-tools.ts

@@ -0,0 +1,156 @@
+/**
+ * ADK Tools — expose an Adk instance as MCP ToolDefinitions.
+ *
+ * Used by atlas-environments (@config agent) and atlas-runtime
+ * to register adk ref/registry operations as MCP tools.
+ *
+ * @example
+ * ```typescript
+ * // Standalone — no scopes
+ * const tools = createAdkTools({ resolveScope: () => adk });
+ *
+ * // Atlas — user/tenant scopes
+ * const tools = createAdkTools({
+ *   resolveScope: (scope) => scope === 'tenant' ? tenantAdk : userAdk,
+ *   scopes: ['user', 'tenant'],
+ * });
+ * ```
+ */
+
+import { defineTool } from "./define.js";
+import type { ToolDefinition, ToolContext } from "./types.js";
+import type { Adk } from "./config-store.js";
+import type { RefEntry, RegistryEntry } from "./define-config.js";
+
+export interface CreateAdkToolsOptions<TCtx extends ToolContext = ToolContext> {
+  /**
+   * Resolve an Adk instance from the scope string and tool context.
+   * Called per-operation. TCtx is your environment's context type.
+   */
+  resolveScope: (scope: string | undefined, ctx: TCtx) => Adk | Promise<Adk>;
+  /** Allowed scope values. If set, added as enum to the JSON schema. */
+  scopes?: string[];
+}
+
+export function createAdkTools<TCtx extends ToolContext = ToolContext>(opts: CreateAdkToolsOptions<TCtx>): ToolDefinition<TCtx>[] {
+  const { resolveScope, scopes } = opts;
+
+  const scopeSchema = scopes
+    ? { type: "string" as const, enum: scopes, description: "Config scope to operate on" }
+    : { type: "string" as const, description: "Config scope (optional)" };
+
+  const refTool = defineTool({
+    name: "ref",
+    description:
+      "Manage agent refs. Operations: add, remove, list, get, update, inspect, call, auth, auth-status, resources, read.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["add", "remove", "list", "get", "update", "inspect", "call", "auth", "auth-status", "resources", "read"],
+        },
+        scope: scopeSchema,
+        ref: { type: "string" },
+        name: { type: "string" },
+        scheme: { type: "string" },
+        url: { type: "string" },
+        as: { type: "string" },
+        sourceRegistry: { type: "object", properties: { url: { type: "string" }, agentPath: { type: "string" } } },
+        config: { type: "object" },
+        tool: { type: "string" },
+        params: { type: "object" },
+        full: { type: "boolean" },
+        uris: { type: "array", items: { type: "string" } },
+        apiKey: { type: "string" },
+      },
+      required: ["operation"],
+    },
+    execute: async (input: Record<string, unknown>, ctx) => {
+      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const op = input.operation as string;
+
+      switch (op) {
+        case "add": {
+          const entry: Record<string, unknown> = { ref: input.ref };
+          if (input.scheme) entry.scheme = input.scheme;
+          if (input.url) entry.url = input.url;
+          if (input.as) entry.as = input.as;
+          if (input.sourceRegistry) entry.sourceRegistry = input.sourceRegistry;
+          if (input.config) entry.config = input.config;
+          return adk.ref.add(entry as unknown as RefEntry);
+        }
+        case "remove":
+          return { removed: await adk.ref.remove(input.name as string) };
+        case "list":
+          return { refs: await adk.ref.list() };
+        case "get":
+          return await adk.ref.get(input.name as string);
+        case "update":
+          return { updated: await adk.ref.update(input.name as string, input as unknown as Partial<RefEntry>) };
+        case "inspect":
+          return await adk.ref.inspect(input.name as string, { full: input.full as boolean });
+        case "call":
+          return await adk.ref.call(input.name as string, input.tool as string, input.params as Record<string, unknown>);
+        case "auth":
+          return await adk.ref.auth(input.name as string, { apiKey: input.apiKey as string });
+        case "auth-status":
+          return await adk.ref.authStatus(input.name as string);
+        case "resources":
+          return await adk.ref.resources(input.name as string);
+        case "read":
+          return await adk.ref.read(input.name as string, input.uris as string[]);
+        default:
+          throw new Error(`Unknown ref operation: ${op}`);
+      }
+    },
+  }) as ToolDefinition<TCtx>;
+
+  const registryTool = defineTool({
+    name: "registry",
+    description:
+      "Manage registry connections. Operations: add, remove, list, browse, inspect, test.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["add", "remove", "list", "browse", "inspect", "test"],
+        },
+        scope: scopeSchema,
+        url: { type: "string" },
+        name: { type: "string" },
+        query: { type: "string" },
+        auth: { type: "object" },
+      },
+      required: ["operation"],
+    },
+    execute: async (input: Record<string, unknown>, ctx) => {
+      const adk = await resolveScope(input.scope as string | undefined, ctx as TCtx);
+      const op = input.operation as string;
+
+      switch (op) {
+        case "add": {
+          const entry: Record<string, unknown> = { url: input.url, name: input.name };
+          if (input.auth) entry.auth = input.auth;
+          await adk.registry.add(entry as unknown as RegistryEntry);
+          return { added: true, name: input.name, url: input.url };
+        }
+        case "remove":
+          return { removed: await adk.registry.remove(input.name as string) };
+        case "list":
+          return { registries: await adk.registry.list() };
+        case "browse":
+          return { agents: await adk.registry.browse(input.name as string, input.query as string) };
+        case "inspect":
+          return await adk.registry.inspect(input.name as string);
+        case "test":
+          return { results: await adk.registry.test(input.name as string) };
+        default:
+          throw new Error(`Unknown registry operation: ${op}`);
+      }
+    },
+  });
+
+  return [refTool, registryTool as unknown as ToolDefinition<TCtx>];
+}

package/src/adk.ts

@@ -78,6 +78,7 @@ function printUsage() {
 adk — Agent Development Kit
 
 Usage:
+  adk proxy <op> [options]           Manage remote adk proxies
   adk registry <op> [options]        Manage registry connections
   adk ref <op> [options]             Manage agent refs
   adk codegen [options]              Generate agent from MCP server
@@ -87,6 +88,11 @@ Usage:
   adk use <agent> [options]          Execute a tool on a generated agent
   adk list                           List all generated agents
 
+Proxy operations:
+  adk proxy add <url> --name <name> [--type mcp|registry] [--agent @config] [--default]
+  adk proxy remove <name>
+  adk proxy list
+
 Registry operations:
   adk registry add <url> --name <name> [--auth-type bearer|api-key|none]
   adk registry remove <name>
@@ -368,6 +374,59 @@ function runList() {
 // Registry CLI
 // ============================================
 
+// ============================================
+// Proxy CLI
+// ============================================
+
+async function runProxy() {
+  const op = args[1];
+  const adk = getAdk();
+
+  switch (op) {
+    case "add": {
+      const url = args[2];
+      const name = getArg("--name");
+      if (!url || !name) { console.error("Usage: adk proxy add <url> --name <name> [--type mcp|registry] [--agent @config] [--default]"); process.exit(1); }
+      const type = (getArg("--type") ?? (url.startsWith("http") ? "mcp" : "registry")) as "mcp" | "registry";
+      const agent = getArg("--agent");
+      const isDefault = hasFlag("--default");
+      await adk.proxy.add({ name, url, type, ...(agent && { agent }), ...(isDefault && { default: true }) });
+      console.log(`Added proxy: ${name} → ${url}${isDefault ? " (default)" : ""}`);
+      break;
+    }
+    case "remove": {
+      const name = args[2];
+      if (!name) { console.error("Usage: adk proxy remove <name>"); process.exit(1); }
+      const removed = await adk.proxy.remove(name);
+      console.log(removed ? `Removed: ${name}` : `Not found: ${name}`);
+      break;
+    }
+    case "list": {
+      const proxies = await adk.proxy.list();
+      if (proxies.length === 0) {
+        console.log("No proxies configured.");
+        break;
+      }
+      console.log(`\n${proxies.length} proxy(s)\n`);
+      for (const p of proxies) {
+        const def = p.default ? " (default)" : "";
+        console.log(`  ${p.name}${def}`);
+        console.log(`    ${p.url} [${p.type}${p.agent ? ` → ${p.agent}` : ""}]`);
+        console.log();
+      }
+      break;
+    }
+    default:
+      console.error(`Unknown proxy operation: ${op}`);
+      console.error("Operations: add, remove, list");
+      process.exit(1);
+  }
+}
+
+// ============================================
+// Registry CLI
+// ============================================
+
 async function runRegistry() {
   const op = args[1];
   const adk = getAdk();
@@ -561,8 +620,17 @@ async function runRef() {
       console.log(`\n${icon} ${status.name}`);
       console.log(`  auth type: ${status.security?.type ?? "none"}`);
       console.log(`  complete:  ${status.complete}`);
-      if (status.present.length > 0) console.log(`  stored:    ${status.present.join(", ")}`);
-      if (status.missing.length > 0) console.log(`  missing:   ${status.missing.join(", ")}`);
+      for (const [field, info] of Object.entries(status.fields)) {
+        const fieldIcon = info.present ? "\x1b[32m\u2713\x1b[0m"
+          : info.resolvable ? "\x1b[36m\u2192\x1b[0m"
+          : info.automated ? "\x1b[33m~\x1b[0m"
+          : "\x1b[31m\u2717\x1b[0m";
+        const source = info.present ? "stored"
+          : info.resolvable ? "resolvable"
+          : info.automated ? "automated"
+          : "missing";
+        console.log(`  ${fieldIcon} ${field}: ${source}${info.required ? "" : " (optional)"}`);
+      }
       console.log();
       break;
     }
@@ -622,6 +690,9 @@ async function runRef() {
 // ============================================
 
 switch (command) {
+  case "proxy":
+    await runProxy();
+    break;
   case "registry":
     await runRegistry();
     break;

package/src/config-store.ts

@@ -20,6 +20,7 @@
 import type { FsStore } from "./agent-definitions/config.js";
 import type {
   ConsumerConfig,
+  ProxyEntry,
   RefEntry,
   RegistryEntry,
   ResolvedRef,
@@ -47,6 +48,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 +84,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 +113,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 +182,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 +593,26 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
   const ref: AdkRefApi = {
     async add(entry: RefEntry): Promise<{ security: SecuritySchemeSummary | null }> {
-      const config = await readConfig();
-      const name = refName(entry);
-      const refs = (config.refs ?? []).filter((r) => refName(r) !== name);
-      refs.push(entry);
-      await writeConfig({ ...config, refs });
-
-      // Check security requirements
+      // Enrich ref with upstream info from the registry
       let security: SecuritySchemeSummary | null = null;
       try {
         const consumer = await buildConsumer();
         const info = await consumer.inspect(entry.ref);
         if (info?.security) security = info.security;
+        if (info?.upstream && !entry.url) {
+          entry.url = info.upstream as string;
+          entry.scheme = entry.scheme ?? "mcp";
+        }
       } catch {
         // Non-fatal — registry might be unreachable
       }
+
+      const config = await readConfig();
+      const name = refName(entry);
+      const refs = (config.refs ?? []).filter((r) => refName(r) !== name);
+      refs.push(entry);
+      await writeConfig({ ...config, refs });
+
       return { security };
     },
 
@@ -623,15 +674,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);
-        const security = info?.security as { type: string; flows?: { authorizationCode?: { authorizationUrl?: string } } } | undefined;
-        const authUrl = security?.flows?.authorizationCode?.authorizationUrl;
-        if (authUrl) {
-          // MCP endpoint is at /mcp under the OAuth origin
-          const mcpUrl = `${new URL(authUrl).origin}/mcp`;
-          return callMcpDirect(mcpUrl, tool, params ?? {}, accessToken);
-        }
+      if (accessToken && entry.url) {
+        return callMcpDirect(entry.url, tool, params ?? {}, accessToken);
       }
 
       const consumer = await buildConsumer();
@@ -691,46 +735,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");
+          }
+        }
+
+        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"),
+        };
+      }
 
-      const missing = requiredFields.filter((f) => !configKeys.includes(f));
-      const present = requiredFields.filter((f) => configKeys.includes(f));
+      const complete = Object.values(fields).every(
+        (f) => !f.required || f.present || f.resolvable || f.automated,
+      );
 
-      return { name, security, complete: missing.length === 0, missing, present };
+      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 };
       }
 
@@ -741,11 +851,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);
         }
@@ -755,10 +863,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"
@@ -777,15 +889,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
@@ -903,5 +1012,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)[];