@slashfi/agents-sdk 0.67.0 → 0.68.0

package/src/config-store.ts

@@ -143,11 +143,29 @@ export interface OAuthResult {
   clientId: string;
 }
 
+/** A field the caller needs to collect from the user */
+export interface AuthChallengeField {
+  /** Field key (e.g. "api_key", "token") */
+  name: string;
+  /** Human-readable label (e.g. "API Key", "DD-API-KEY") */
+  label: string;
+  /** Whether this is a secret value (should be masked in UI) */
+  secret: boolean;
+  /** Optional description / help text */
+  description?: string;
+}
+
 export interface AuthStartResult {
   type: string;
   complete: boolean;
   /** For OAuth: the URL to open in the browser */
   authorizeUrl?: string;
+  /**
+   * When complete=false and type is "apiKey" or "http",
+   * these are the fields the caller should collect from the user.
+   * The caller can render these as a form (Slack blocks, web modal, CLI prompts).
+   */
+  fields?: AuthChallengeField[];
 }
 
 export interface AdkRefApi {
@@ -168,8 +186,14 @@ export interface AdkRefApi {
    * adk.ref.authLocal() to spin up a local server and block.
    */
   auth(name: string, opts?: {
-    /** For API key / bearer auth: the key/token value */
+    /** For API key / bearer auth: the key/token value (single-key shorthand) */
     apiKey?: string;
+    /**
+     * Credentials map for multi-field auth. Keys match the `name` field
+     * from AuthChallengeField (e.g. { "api_key": "xxx", "app_key": "yyy" }).
+     * For single-key apiKey or http bearer, `apiKey` shorthand also works.
+     */
+    credentials?: Record<string, string>;
     /** Extra context to encode in the OAuth state (e.g., tenant/user IDs for multi-tenant callbacks) */
     stateContext?: Record<string, unknown>;
     /** Additional scopes to request (e.g., optional scopes declared by the agent) */
@@ -290,20 +314,18 @@ async function decryptConfigSecrets(
 // ============================================
 
 /**
- * Heuristic: does a tool call response look like a 401 Unauthorized?
- * Checks both structured error fields and stringified response content.
+ * Check if a tool call response indicates a 401 Unauthorized from the upstream API.
+ * Primary: httpStatus set by consumer from HTTP res.status
+ * Fallback: _httpStatus from tool result body
  */
-function looksLike401(result: unknown): boolean {
+function isUnauthorized(result: unknown): boolean {
   if (!result || typeof result !== 'object') return false;
   const r = result as Record<string, unknown>;
-
-  // Structured: { success: true, result: { success: true, result: { content: [{ text: '{"error":"401 ..."} }] } } }
-  // Or: { error: "401 ..." }
-  const text = JSON.stringify(r).toLowerCase();
-  if (text.includes('"401') && (text.includes('unauthorized') || text.includes('unauthenticated') || text.includes('invalid credentials'))) {
-    return true;
-  }
-
+  // Primary: HTTP status forwarded by the registry and set by callRegistry
+  if (r.httpStatus === 401) return true;
+  // Fallback: _httpStatus in the nested tool result body
+  const inner = r.result as Record<string, unknown> | undefined;
+  if (inner?._httpStatus === 401) return true;
   return false;
 }
 
@@ -894,7 +916,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       const result = await doCall(accessToken);
 
       // Check if the response indicates a 401 — try refreshing the token and retry once
-      if (accessToken && looksLike401(result)) {
+      if (accessToken && isUnauthorized(result)) {
         const refreshed = await ref.refreshToken(name);
         if (refreshed) {
           return doCall(refreshed.accessToken);
@@ -1000,12 +1022,32 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
           resolvable: false,
         };
       } else if (security.type === "apiKey") {
-        fields.api_key = {
-          required: true,
-          automated: false,
-          present: configKeys.includes("api_key"),
-          resolvable: await canResolve("api_key"),
+        const apiKeySec = security as {
+          name?: string; headers?: Record<string, { description?: string }>;
         };
+        const toStorageKey = (headerName: string) =>
+          headerName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+
+        if (apiKeySec.headers && Object.keys(apiKeySec.headers).length > 0) {
+          // Multi-key mode
+          for (const headerName of Object.keys(apiKeySec.headers)) {
+            const storageKey = toStorageKey(headerName);
+            fields[storageKey] = {
+              required: true,
+              automated: false,
+              present: configKeys.includes(storageKey),
+              resolvable: await canResolve(storageKey),
+            };
+          }
+        } else {
+          // Single-key mode (backwards compat)
+          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,
@@ -1024,6 +1066,7 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
 
     async auth(name: string, opts?: {
       apiKey?: string;
+      credentials?: Record<string, string>;
       /** Extra context to encode in the OAuth state (e.g., tenant/user IDs for multi-tenant callbacks) */
       stateContext?: Record<string, unknown>;
       /** Additional scopes to request (e.g., optional scopes declared by the agent) */
@@ -1047,15 +1090,92 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
       }
 
       if (security.type === "apiKey") {
-        const key = opts?.apiKey ?? await tryResolve("api_key");
-        if (!key) return { type: "apiKey", complete: false };
+        const apiKeySec = security as {
+          name?: string; prefix?: string;
+          headers?: Record<string, { description?: string }>;
+        };
+
+        const toStorageKey = (headerName: string) =>
+          headerName.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+
+        if (apiKeySec.headers && Object.keys(apiKeySec.headers).length > 0) {
+          // Multi-key mode: iterate all declared headers
+          const missingFields: AuthChallengeField[] = [];
+          const resolvedKeys: Array<{ storageKey: string; value: string }> = [];
+
+          for (const [headerName, meta] of Object.entries(apiKeySec.headers)) {
+            const storageKey = toStorageKey(headerName);
+            const value = opts?.credentials?.[storageKey] ?? await tryResolve(storageKey);
+
+            if (value) {
+              resolvedKeys.push({ storageKey, value });
+            } else {
+              missingFields.push({
+                name: storageKey,
+                label: headerName,
+                secret: true,
+                description: meta.description,
+              });
+            }
+          }
+
+          if (missingFields.length > 0) {
+            return { type: "apiKey", complete: false, fields: missingFields };
+          }
+          for (const { storageKey, value } of resolvedKeys) {
+            await storeRefSecret(name, storageKey, value);
+          }
+          return { type: "apiKey", complete: true };
+        }
+
+        // Single-key mode (backwards compat)
+        const key = opts?.credentials?.["api_key"] ?? opts?.apiKey ?? await tryResolve("api_key");
+        if (!key) {
+          return {
+            type: "apiKey",
+            complete: false,
+            fields: [{
+              name: "api_key",
+              label: apiKeySec.name ?? "API Key",
+              secret: true,
+              description: apiKeySec.prefix
+                ? `Value sent as "${apiKeySec.prefix} <key>"`
+                : undefined,
+            }],
+          };
+        }
         await storeRefSecret(name, "api_key", key);
         return { type: "apiKey", complete: true };
       }
 
       if (security.type === "http") {
-        const token = opts?.apiKey ?? await tryResolve("token");
-        if (!token) return { type: "http", complete: false };
+        const httpSec = security as { scheme?: string };
+        const isBasic = httpSec.scheme === "basic";
+
+        if (isBasic) {
+          const username = opts?.credentials?.["username"] ?? await tryResolve("username");
+          const password = opts?.credentials?.["password"] ?? await tryResolve("password");
+          if (!username || !password) {
+            const missingFields: AuthChallengeField[] = [];
+            if (!username) missingFields.push({ name: "username", label: "Username", secret: false });
+            if (!password) missingFields.push({ name: "password", label: "Password", secret: true });
+            return { type: "http", complete: false, fields: missingFields };
+          }
+          // Store as base64 encoded basic auth token
+          const token = btoa(`${username}:${password}`);
+          await storeRefSecret(name, "token", token);
+          return { type: "http", complete: true };
+        }
+
+        // Bearer token
+        const token = opts?.credentials?.["token"] ?? opts?.apiKey ?? await tryResolve("token");
+        if (!token) {
+          return {
+            type: "http",
+            complete: false,
+            fields: [{ name: "token", label: "Bearer Token", secret: true }],
+          };
+        }
         await storeRefSecret(name, "token", token);
         return { type: "http", complete: true };
       }
@@ -1064,7 +1184,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         const flows = (security as { flows?: { authorizationCode?: { authorizationUrl?: string; tokenUrl?: string } } }).flows;
         const authCodeFlow = flows?.authorizationCode;
         if (!authCodeFlow?.authorizationUrl) {
-          return { type: "oauth2", complete: false };
+          return {
+            type: "oauth2",
+            complete: false,
+            fields: [
+              { name: "client_id", label: "Client ID", secret: false },
+              { name: "client_secret", label: "Client Secret", secret: true },
+            ],
+          };
         }
 
         const authUrl = authCodeFlow.authorizationUrl;
@@ -1118,9 +1245,14 @@ export function createAdk(fs: FsStore, options: AdkOptions = {}): Adk {
         }
 
         if (!clientId) {
-          throw new Error(
-            "Could not obtain client_id. Provide via resolveCredentials callback or store manually.",
-          );
+          // Return fields telling the caller what OAuth credentials to provide
+          const missingFields: AuthChallengeField[] = [];
+          if (!clientId) {
+            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 });
+          return { type: "oauth2", complete: false, fields: missingFields };
         }
 
         // State ties the callback back to this ref. Encode as base64 JSON

package/src/index.ts

@@ -417,6 +417,7 @@ export type {
   RefAuthStatus,
   CredentialField,
   AuthStartResult,
+  AuthChallengeField,
   OAuthResult,
   ResolveCredentials,
   ResolveCredentialsContext,

package/src/registry-consumer.ts

@@ -727,6 +727,14 @@ export async function createRegistryConsumer(
     });
 
     if (!res.ok) {
+      // Upstream 401 — return structured response so ref.call() can refresh + retry
+      if (res.status === 401) {
+        // Still try to parse the body for context
+        const body = await res.text().catch(() => "");
+        let parsed: Record<string, unknown> = { success: false, error: "unauthorized" };
+        try { parsed = JSON.parse(body); } catch {}
+        return { ...parsed, success: false, httpStatus: 401 } as unknown as CallAgentResponse;
+      }
       const text = await res.text().catch(() => "unknown error");
       throw new Error(
         `Registry call failed (${registry.url}): ${res.status} ${text}`,

package/src/server.ts

@@ -554,6 +554,19 @@ export function createAgentServer(
   async function handleJsonRpc(
     request: JsonRpcRequest,
     auth: ResolvedAuth | null,
+  ): Promise<{ rpc: JsonRpcResponse; httpResponse?: { status: number } }> {
+    const rpc = await handleJsonRpcInner(request, auth);
+    // Extract upstream HTTP status from tool results (set by REST proxy handlers)
+    const httpStatus = (rpc as any)?.result?._httpStatus as number | undefined;
+    return {
+      rpc,
+      ...(httpStatus ? { httpResponse: { status: httpStatus } } : {}),
+    };
+  }
+
+  async function handleJsonRpcInner(
+    request: JsonRpcRequest,
+    auth: ResolvedAuth | null,
   ): Promise<JsonRpcResponse> {
     switch (request.method) {
       case "initialize":
@@ -662,7 +675,11 @@ export function createAgentServer(
         }
 
         const result = await registry.call(req);
-        return mcpResult(result);
+        const mcp = mcpResult(result);
+        // Preserve upstream HTTP status from tool execution (e.g. REST proxy 401)
+        const upstreamStatus = (result as any)?.result?._httpStatus;
+        if (upstreamStatus) (mcp as any)._httpStatus = upstreamStatus;
+        return mcp;
       }
 
       case "list_agents": {
@@ -1109,8 +1126,10 @@ export function createAgentServer(
       // ── POST / → MCP JSON-RPC ──
       if (path === "/" && req.method === "POST") {
         const body = (await req.json()) as JsonRpcRequest;
-        const result = await handleJsonRpc(body, effectiveAuth);
-        return cors ? addCors(jsonResponse(result)) : jsonResponse(result);
+        const { rpc, httpResponse } = await handleJsonRpc(body, effectiveAuth);
+        const status = httpResponse?.status ?? 200;
+        const res = jsonResponse(rpc, status);
+        return cors ? addCors(res) : res;
       }
 
       // ── POST /oauth/token → OAuth2 token exchange ──

package/src/types.ts

@@ -204,17 +204,35 @@ export interface OAuth2SecurityScheme {
 
 /**
  * API key authentication.
- * Used by agents that wrap APIs using a single key
+ * Used by agents that wrap APIs using one or more keys
  * (e.g. OpenAI, Anthropic, Stripe, Datadog).
+ *
+ * @example
+ * // Single key (backwards-compatible)
+ * security: { type: 'apiKey', in: 'header', name: 'Authorization', prefix: 'Bearer' }
+ *
+ * // Multiple keys (e.g. Datadog)
+ * security: {
+ *   type: 'apiKey',
+ *   headers: {
+ *     'DD-API-KEY': { description: 'Your Datadog API key' },
+ *     'DD-APPLICATION-KEY': { description: 'Your Datadog application key' },
+ *   }
+ * }
  */
 export interface ApiKeySecurityScheme {
   type: "apiKey";
-  /** Where the key is sent */
-  in: "header" | "query";
-  /** Header or query parameter name (e.g. "X-API-Key", "Authorization") */
-  name: string;
-  /** Optional prefix (e.g. "Bearer" for Authorization header) */
+  /** Where the key is sent (single-key mode) */
+  in?: "header" | "query";
+  /** Header or query parameter name (single-key mode, e.g. "X-API-Key") */
+  name?: string;
+  /** Optional prefix (single-key mode, e.g. "Bearer") */
   prefix?: string;
+  /**
+   * Named headers the user must provide values for (multi-key mode).
+   * When present, this is the source of truth — `in`/`name`/`prefix` are ignored.
+   */
+  headers?: Record<string, { description?: string }>;
 }
 
 /**