@adcp/sdk 12.1.0 → 13.0.0-rc.0

package/dist/lib/protocols/a2a.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/protocols/a2a.ts"],"sourcesContent":["import { fileURLToPath as __adcpFileURLToPath } from 'node:url';\nimport { dirname as __adcpDirname } from 'node:path';\nimport { createRequire as __adcpCreateRequire } from 'node:module';\nconst __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));\nconst require = __adcpCreateRequire(import.meta.url);\n// Official A2A client implementation - NO FALLBACKS\nimport { A2AClient as A2AClientImpl } from '@a2a-js/sdk/client';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { createHmac, randomUUID } from 'node:crypto';\nimport type { PushNotificationConfig } from '../types/tools.generated';\nimport type { DebugLogEntry } from '../types/adcp';\nimport { AuthenticationRequiredError, is401Error } from '../errors';\nimport { discoverOAuthMetadata } from '../auth/oauth/discovery';\nimport { probeAuthChallenge } from '../auth/oauth/authorization-required';\nimport { withSpan, injectTraceHeaders } from '../observability/tracing';\nimport { isAgentCardPath, buildCardUrls } from '../utils/a2a-discovery';\nimport { buildAgentSigningFetch, signingContextStorage, type AgentSigningContext } from '../signing/client';\nimport { toSignerKey, isInlineSigningConfig, isProviderSigningConfig } from '../signing/agent-fetch';\nimport { createSigningFetch, type FetchLike } from '../signing/fetch';\nimport { createSigningFetchAsync } from '../signing/fetch-async';\nimport type { AgentConfig } from '../types/adcp';\nimport { redactIdempotencyKeyInArgs } from '../utils/idempotency';\nimport { wrapFetchWithCapture } from './rawResponseCapture';\nimport { wrapFetchWithSizeLimit } from './responseSizeLimit';\nimport { wrapFetchWithTransportDiagnostics } from './transportDiagnostics';\nimport { DEFAULT_REQUEST_TIMEOUT_MS, resolveRequestTimeoutMs, withAbortSignal } from './abort';\nimport { getLatestA2ADataPartFromResponse } from '../utils/a2a-artifacts';\n\n// The A2A SDK client is used untyped: request/response shapes are validated at\n// runtime against the AdCP wire contract, not against the SDK's exported\n// types. Preserves the prior behaviour of the CommonJS `require` form.\nconst A2AClient: any = A2AClientImpl;\n\nif (!A2AClient) {\n  throw new Error('A2A SDK client is required. Please install @a2a-js/sdk');\n}\n\n/**\n * Per-call state flowed through AsyncLocalStorage so concurrent callers\n * that share a cached A2AClient don't clobber each other's debugLogs,\n * customHeaders, or 401 flag.\n */\ninterface A2ACallContext {\n  customHeaders?: Record<string, string>;\n  debugLogs: DebugLogEntry[];\n  got401Ref: { value: boolean };\n  signal?: AbortSignal;\n  requestTimeoutMs?: number;\n}\n\nconst callContextStorage = new AsyncLocalStorage<A2ACallContext>();\n\n/**\n * Cached A2AClient keyed by (agentUrl, authToken hash). Avoids re-fetching\n * /.well-known/agent.json on every tool call. The cached client's fetchImpl\n * reads per-call state from callContextStorage, so concurrent calls to the\n * same cache entry are safe.\n *\n * Process-global singleton — not suitable for multi-tenant servers that\n * want per-tenant isolation (use separate processes or explicit cache keys).\n */\nconst a2aClientCache = new Map<string, InstanceType<typeof A2AClient>>();\nconst pendingA2AClients = new Map<string, Promise<InstanceType<typeof A2AClient>>>();\n\n/**\n * Build the A2A connection-cache key. Mirrors the rationale in\n * `src/lib/protocols/mcp.ts:connectionCacheKey`: when the caller is using a\n * non-bearer scheme (RFC 7617 Basic from the CLI's `--auth-scheme basic`\n * shape, or any future caller-injected `Authorization` header), `authToken`\n * is undefined and the credential rides on the customHeaders bag. Hashing\n * only `authToken` would let two callers with different `user:pass`\n * credentials share a single cached A2AClient — single-CLI-process safe,\n * multi-tenant SDK consumer not safe.\n *\n * `customHeaders` also feed the key so tenant/routing headers cannot reuse\n * a card/client discovered for another caller.\n */\nfunction a2aCacheKey(\n  agentUrl: string,\n  authToken?: string,\n  signingCacheKey?: string,\n  customHeaders?: Record<string, string>\n): string {\n  // 64-bit Map-key disambiguator — NOT a password hash. The cached client\n  // closes over the full credential, so a hypothetical hash collision still\n  // sends the original credential on the wire, just possibly cache-miss\n  // and reconnect. Routed via `cacheDisambiguator` (HMAC-SHA256 with empty\n  // key) instead of bare `createHash` so CodeQL's\n  // `js/insufficient-password-hash` heuristic doesn't misclassify the\n  // dataflow — see the helper docstring for the full rationale.\n  const fingerprint = authToken ?? extractA2AAuthHeader(customHeaders);\n  const tokenSuffix = fingerprint ? `::${cacheDisambiguator(fingerprint)}` : '';\n  const headersKey = headersCacheDisambiguator(customHeaders);\n  const headersSuffix = headersKey ? `::headers:${headersKey}` : '';\n  const signingSuffix = signingCacheKey ? `::${signingCacheKey}` : '';\n  return `${agentUrl}${tokenSuffix}${headersSuffix}${signingSuffix}`;\n}\n\n/**\n * Produce a stable 64-bit Map-key disambiguator from credential material.\n * Mirrors the helper in `src/lib/protocols/mcp.ts` — the two protocol\n * modules intentionally don't share runtime imports, so each carries its\n * own copy. See the MCP-side docstring for the full rationale.\n */\nfunction cacheDisambiguator(value: string): string {\n  return createHmac('sha256', '').update(value).digest('hex').slice(0, 16);\n}\n\n/**\n * Case-insensitive lookup of `Authorization` on a header bag. Mirrors the\n * MCP-side helper; A2A keeps its own copy because the two protocol modules\n * intentionally don't share runtime imports.\n */\nfunction extractA2AAuthHeader(headers: Record<string, string> | undefined): string | undefined {\n  if (!headers) return undefined;\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase() === 'authorization' && value) return value;\n  }\n  return undefined;\n}\n\nfunction headersCacheDisambiguator(headers?: Record<string, string>): string | undefined {\n  const entries = Object.entries(headers ?? {})\n    .filter(([key]) => {\n      const lower = key.toLowerCase();\n      return lower !== 'traceparent' && lower !== 'tracestate' && lower !== 'baggage';\n    })\n    .map(([key, value]) => [key.toLowerCase(), value] as const)\n    .sort(([a], [b]) => a.localeCompare(b));\n  return entries.length > 0 ? cacheDisambiguator(JSON.stringify(entries)) : undefined;\n}\n\nfunction redactHeadersForDebug(headers: Record<string, string>): Record<string, string> {\n  return Object.fromEntries(Object.keys(headers).map(key => [key, '***']));\n}\n\nfunction redactPushNotificationConfigForDebug(\n  config: PushNotificationConfig | undefined\n): PushNotificationConfig | undefined {\n  if (!config) return undefined;\n  return {\n    ...config,\n    ...(config.token && { token: '***' }),\n    ...(config.authentication && {\n      authentication: {\n        ...config.authentication,\n        ...(config.authentication.credentials && { credentials: '***' }),\n      },\n    }),\n  };\n}\n\n/**\n * Clear all cached A2A clients. Called by closeConnections('a2a').\n * A2A clients hold no persistent network resources (unlike MCP), so this\n * is just cache eviction.\n */\nexport function closeA2AConnections(): void {\n  a2aClientCache.clear();\n  pendingA2AClients.clear();\n}\n\n/**\n * Wall-clock cap on a fire-and-forget cancel. A2A sellers that accept the\n * TCP connect but never respond would otherwise pin the event loop past the\n * buyer's abort, which defeats the whole point of fire-and-forget.\n */\nconst CANCEL_TIMEOUT_MS = 5000;\n\n/**\n * Fire-and-forget A2A tasks/cancel for an in-flight task (A2A 0.3.0 §7.4).\n *\n * Sends a raw JSON-RPC 2.0 POST directly to the agent endpoint with the same\n * auth header shape as `callA2AToolImpl` (Bearer + x-adcp-auth). Does NOT\n * enter `callContextStorage` — debug-log capture and 401-cache-eviction are\n * intentionally skipped for best-effort cancellation.\n *\n * **Auth-code OAuth gap:** `authToken` is resolved by `getAuthToken(agent)`,\n * which returns `undefined` for authorization-code-flow sellers (those tokens\n * are managed by the OAuth provider path in `ProtocolClient.callTool`, not\n * accessible here). Cancel calls to those sellers go out unauthenticated and\n * will likely 401 non-fatally.\n *\n * **Phase 2 (adcp-client#1617 follow-up):** when `agent.request_signing` is\n * configured, the cancel POST is signed with the agent's signer key. The\n * `signingContextStorage` ALS scope around `callA2AToolImpl` does NOT extend\n * into `pollTaskCompletion` (sibling promise trees), so we can't replay the\n * captured ALS context — instead we rebuild a one-shot signer fetch from\n * `agent.request_signing` directly and use it for this single POST. Inline\n * keys go through `createSigningFetch` (sync); provider-backed configs use\n * `createSigningFetchAsync`. A `signed-requests` seller that requires\n * signing on `tasks/cancel` (or applies a uniform \"all mutating POSTs must\n * be signed\" policy) now accepts the cancel; one without signing config on\n * the agent gets the Phase 1 unsigned path.\n *\n * The caller is responsible for swallowing errors: cancel failure\n * (TaskNotCancelable, network error, auth rejection, network timeout) is\n * non-fatal because the buyer is already abandoning the task.\n *\n * @param agent     The agent config (used for URL, auth token, signing).\n * @param taskId    The server-assigned A2A Task.id to cancel.\n */\nexport async function cancelA2ATask(agent: AgentConfig, taskId: string): Promise<void> {\n  // Defense-in-depth (ad-tech-protocol-expert review of #1640): the cancel\n  // POST is JSON-RPC at the bare A2A endpoint. Calling this on an MCP agent\n  // would POST `tasks/cancel` JSON-RPC at an MCP endpoint and 404. The\n  // single call site (`pollTaskCompletion`) already gates on\n  // `agent.protocol === 'a2a'`; this assertion catches future call sites\n  // that forget the gate.\n  if (agent.protocol !== 'a2a') {\n    return;\n  }\n  const agentUrl = agent.agent_uri;\n  const authToken = agent.auth_token;\n\n  const headers: Record<string, string> = {\n    'content-type': 'application/json',\n    accept: 'application/json',\n  };\n  if (authToken) {\n    headers['Authorization'] = `Bearer ${authToken}`;\n    headers['x-adcp-auth'] = authToken;\n  }\n  // JSON-RPC 2.0 §4.1.3: `id: null` flags the request as a *notification*,\n  // and the server MUST NOT respond. A2A 0.3.0 §7.4 defines `tasks/cancel`\n  // as a request/response method (returns the canceled `Task` or\n  // `TaskNotCancelableError`), so a strict A2A server can legitimately\n  // reject `id: null` as a protocol violation. Use a real id and just drop\n  // the response on the floor — fire-and-forget is the caller's discipline,\n  // not a wire-protocol claim.\n  const body = JSON.stringify({\n    jsonrpc: '2.0',\n    id: randomUUID(),\n    method: 'tasks/cancel',\n    params: { id: taskId },\n  });\n  // Bound the cancel: a hung fetch would orphan-pin the event loop past the\n  // buyer's abort, defeating fire-and-forget. AbortSignal.timeout() is the\n  // standard primitive; the caller's `.catch()` swallows the AbortError.\n  const init: RequestInit = {\n    method: 'POST',\n    headers,\n    body,\n    signal: AbortSignal.timeout(CANCEL_TIMEOUT_MS),\n  };\n\n  // adcp-client#1617 Phase 2: sign the cancel POST when the agent has a\n  // signer configured. We bypass the `buildAgentSigningFetch` capability-\n  // gate path because `tasks/cancel` is an A2A protocol method, not an\n  // AdCP tool — the seller's `request_signing.supported_for` typically\n  // lists AdCP tool names, not protocol-level methods. The right model\n  // here: if the agent claims signing AT ALL, sign every mutating POST\n  // we send to it on the cancel path. Sellers with uniform \"must be\n  // signed\" policies accept this; sellers that only check signing on\n  // specific AdCP tools simply ignore the extra signature.\n  //\n  // TODO(adcp#4318, adcp-client#1617): when the AdCP spec adds explicit\n  // verifier coverage for A2A protocol methods (likely in 3.1 as a new\n  // `protocol_methods_supported_for` / `protocol_methods_required_for`\n  // field on `request_signing`), narrow this default by reading the\n  // seller's advertised coverage from `getCapability()` and gating on\n  // the `tasks/cancel` membership. The over-sign default stays as the\n  // fallback for spec-silent sellers (3.0.x and earlier).\n  if (agent.request_signing) {\n    const upstream: FetchLike = (input, ini) => fetch(input as RequestInfo, ini);\n    if (isInlineSigningConfig(agent.request_signing)) {\n      const signed = createSigningFetch(upstream, toSignerKey(agent.request_signing));\n      await signed(agentUrl, init);\n      return;\n    }\n    if (isProviderSigningConfig(agent.request_signing)) {\n      const signed = createSigningFetchAsync(upstream, agent.request_signing.provider);\n      await signed(agentUrl, init);\n      return;\n    }\n  }\n\n  await fetch(agentUrl, init);\n}\n\nasync function getOrCreateA2AClient(\n  agentUrl: string,\n  authToken: string | undefined,\n  customHeaders?: Record<string, string>,\n  bypassCache = false\n): Promise<InstanceType<typeof A2AClient>> {\n  const signingContext = signingContextStorage.getStore();\n  const cacheKey = a2aCacheKey(agentUrl, authToken, signingContext?.cacheKey, customHeaders);\n  if (bypassCache) {\n    return createA2AClient(agentUrl, authToken);\n  }\n  const cached = a2aClientCache.get(cacheKey);\n  if (cached) return cached;\n\n  const pending = pendingA2AClients.get(cacheKey);\n  if (pending) return pending;\n\n  const promise = createA2AClient(agentUrl, authToken)\n    .then(client => {\n      a2aClientCache.set(cacheKey, client);\n      return client;\n    })\n    .finally(() => {\n      pendingA2AClients.delete(cacheKey);\n    });\n\n  pendingA2AClients.set(cacheKey, promise);\n  return promise;\n}\n\nasync function createA2AClient(\n  agentUrl: string,\n  authToken: string | undefined\n): Promise<InstanceType<typeof A2AClient>> {\n  const fetchImpl = buildFetchImpl(authToken);\n  const cardUrls = buildCardUrls(agentUrl);\n\n  const context = callContextStorage.getStore();\n  context?.debugLogs.push({\n    type: 'info',\n    message: `A2A: Discovering agent card at ${cardUrls.join(', ')}`,\n    timestamp: new Date().toISOString(),\n  });\n\n  let client: InstanceType<typeof A2AClient> | undefined;\n  let lastError: Error = new Error(`A2A agent card not found at ${cardUrls.join(', ')}`);\n  for (const cardUrl of cardUrls) {\n    try {\n      client = await A2AClient.fromCardUrl(cardUrl, { fetchImpl });\n      break;\n    } catch (err: unknown) {\n      lastError = err as Error;\n      if (context?.got401Ref.value) break;\n    }\n  }\n  if (!client) throw lastError;\n\n  return client;\n}\n\nfunction buildFetchImpl(authToken: string | undefined) {\n  // The A2A client is cached per (url, authToken, signingCacheKey). We capture\n  // the signing context at client-creation time so all subsequent calls that\n  // share this cached client use the same signing identity — changing identity\n  // requires a different cache entry, built on a separate call that enters ALS\n  // with a different context.\n  const signingContext = signingContextStorage.getStore();\n\n  // Innermost wrapper: enforce response body size cap from the active\n  // `responseSizeLimitStorage` slot. Pass-through when no slot is set.\n  const networkFetch = wrapFetchWithTransportDiagnostics(\n    wrapFetchWithSizeLimit((input, init) => fetch(input as any, init))\n  );\n\n  // Inner fetch handles auth/header injection and 401 detection. If the\n  // agent has request-signing configured, we wrap it with the AdCP signing\n  // fetch so the signature covers the exact bytes we're about to send (auth\n  // headers included, since the signer re-reads the final header record).\n  const baseFetch = async (url: string | URL | Request, options?: RequestInit): Promise<Response> => {\n    const context = callContextStorage.getStore();\n\n    const existingHeaders: Record<string, string> = {};\n    if (options?.headers) {\n      if (options.headers instanceof Headers) {\n        options.headers.forEach((value, key) => {\n          existingHeaders[key] = value;\n        });\n      } else if (Array.isArray(options.headers)) {\n        for (const [key, value] of options.headers) {\n          existingHeaders[key] = value;\n        }\n      } else {\n        Object.assign(existingHeaders, options.headers);\n      }\n    }\n\n    // Only inject trace context headers for actual tool requests, not discovery.\n    // The agent card endpoint is external/untrusted — don't leak trace IDs to it.\n    const urlString = typeof url === 'string' ? url : url.toString();\n    const isDiscoveryRequest = isAgentCardPath(urlString);\n    const traceHeaders = isDiscoveryRequest ? {} : injectTraceHeaders();\n    const requestTimeoutMs = isDiscoveryRequest\n      ? resolveRequestTimeoutMs(context?.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS)\n      : resolveRequestTimeoutMs(context?.requestTimeoutMs);\n\n    // Merge: existing < trace < custom < auth (auth always wins)\n    const headers: Record<string, string> = {\n      ...existingHeaders,\n      ...traceHeaders,\n      ...context?.customHeaders,\n      ...(authToken && {\n        Authorization: `Bearer ${authToken}`,\n        'x-adcp-auth': authToken,\n      }),\n    };\n\n    context?.debugLogs.push({\n      type: 'info',\n      message: `A2A: Fetch to ${urlString}`,\n      timestamp: new Date().toISOString(),\n      hasAuth: !!authToken,\n      headers: redactHeadersForDebug(headers),\n    });\n\n    const response = await withAbortSignal<Response>([context?.signal, options?.signal], requestTimeoutMs, signal =>\n      networkFetch(url as any, { ...options, headers, signal })\n    );\n\n    if (response.status === 401 && context) {\n      context.got401Ref.value = true;\n    }\n\n    return response;\n  };\n\n  if (!signingContext) return wrapFetchWithCapture(baseFetch);\n\n  // The signing wrapper assembles headers into the signature base. We invoke\n  // it first so the signer sees the caller-supplied headers; baseFetch then\n  // overlays auth/trace headers afterwards — A2A's auth scheme (bearer) is\n  // not among the MANDATORY_COMPONENTS and is injected by the counterparty's\n  // transport layer, not signed.\n  const signingFetch = buildAgentSigningFetch({\n    upstream: (input, init) => baseFetch(input as any, init),\n    signing: signingContext.signing,\n    getCapability: signingContext.getCapability,\n  });\n  return wrapFetchWithCapture(signingFetch as typeof fetch);\n}\n\n/**\n * Terminal A2A task states per A2A 0.3.0 §3.4. Only these can carry the\n * AdCP-mandated artifact + DataPart envelope (per transport-errors §A2A\n * Binding); intermediate states (`working`, `submitted`, `input-required`,\n * `auth-required`) carry no completion artifact.\n */\nconst TERMINAL_A2A_STATES = new Set(['completed', 'failed', 'rejected', 'canceled']);\n\n/**\n * Detect whether a JSON-RPC response carries a spec-compliant terminal-state\n * Task with at least one artifact containing a structured DataPart payload.\n * Per AdCP transport-errors §A2A Binding, the artifact's DataPart is the\n * canonical envelope for both the success arm (`completed`) and the error\n * arms (`failed` / `rejected` / `canceled`). The criterion intentionally\n * matches the unwrapper's terminal-state extraction in\n * `unwrapA2AResponse` — keeping protocol layer and unwrapper in lockstep\n * across all terminal states, not just the error arms.\n *\n * Used to short-circuit the generic \"A2A agent returned error\" throw when\n * a non-conformant seller surfaces both a transport-level `result.error`\n * hint and the canonical artifact envelope side-by-side. The DataPart is\n * authoritative; the throw would otherwise swallow it.\n */\nfunction hasTerminalTaskWithDataArtifact(response: unknown): boolean {\n  if (!response || typeof response !== 'object') return false;\n  const result = (response as { result?: unknown }).result;\n  if (!result || typeof result !== 'object') return false;\n  const r = result as { kind?: unknown; status?: unknown; artifacts?: unknown };\n  if (r.kind !== 'task') return false;\n  const status = r.status as { state?: unknown } | undefined;\n  if (typeof status?.state !== 'string' || !TERMINAL_A2A_STATES.has(status.state)) return false;\n  return getLatestA2ADataPartFromResponse(response) !== undefined;\n}\n\n/**\n * Protocol-level session identifiers that ride on the A2A Message envelope\n * (not in the skill parameters). `contextId` binds sends to a server-side\n * conversation; `taskId` resumes an existing non-terminal task.\n *\n * Callers (buyers) typically retain these across calls on a per-conversation\n * AgentClient; see AgentClient.getContextId() / getPendingTaskId().\n */\nexport interface A2ASessionIds {\n  contextId?: string;\n  taskId?: string;\n}\n\nexport async function callA2ATool(\n  agentUrl: string,\n  toolName: string,\n  parameters: Record<string, unknown>,\n  authToken?: string,\n  debugLogs: DebugLogEntry[] = [],\n  pushNotificationConfig?: PushNotificationConfig,\n  customHeaders?: Record<string, string>,\n  signingContext?: AgentSigningContext,\n  session?: A2ASessionIds,\n  signal?: AbortSignal,\n  requestTimeoutMs?: number\n): Promise<unknown> {\n  return withSpan(\n    'adcp.a2a.call_tool',\n    {\n      'adcp.tool': toolName,\n      'http.url': agentUrl,\n    },\n    async () => {\n      const context: A2ACallContext = {\n        customHeaders,\n        debugLogs,\n        got401Ref: { value: false },\n        signal,\n        requestTimeoutMs,\n      };\n      return signingContextStorage.run(signingContext, () =>\n        callContextStorage.run(context, () =>\n          callA2AToolImpl(\n            agentUrl,\n            toolName,\n            parameters,\n            authToken,\n            debugLogs,\n            pushNotificationConfig,\n            context,\n            session\n          )\n        )\n      );\n    }\n  );\n}\n\nasync function callA2AToolImpl(\n  agentUrl: string,\n  toolName: string,\n  parameters: Record<string, unknown>,\n  authToken: string | undefined,\n  debugLogs: DebugLogEntry[],\n  pushNotificationConfig: PushNotificationConfig | undefined,\n  context: A2ACallContext,\n  session: A2ASessionIds | undefined\n): Promise<unknown> {\n  try {\n    const client = await getOrCreateA2AClient(\n      agentUrl,\n      authToken,\n      context.customHeaders,\n      !!context.signal || context.requestTimeoutMs !== undefined\n    );\n\n    const requestPayload: {\n      message: {\n        messageId: string;\n        role: string;\n        kind: string;\n        parts: Array<{ kind: string; data: { skill: string; parameters: Record<string, unknown> } }>;\n        contextId?: string;\n        taskId?: string;\n      };\n      configuration?: { pushNotificationConfig: PushNotificationConfig };\n    } = {\n      message: {\n        messageId: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,\n        role: 'user',\n        kind: 'message',\n        parts: [\n          {\n            kind: 'data',\n            data: {\n              skill: toolName,\n              parameters: parameters,\n            },\n          },\n        ],\n        ...(session?.contextId && { contextId: session.contextId }),\n        ...(session?.taskId && { taskId: session.taskId }),\n      },\n    };\n\n    if (pushNotificationConfig) {\n      requestPayload.configuration = {\n        pushNotificationConfig: pushNotificationConfig,\n      };\n    }\n\n    const payloadSize = JSON.stringify(requestPayload).length;\n    const redactedParameters = redactIdempotencyKeyInArgs(parameters);\n    const redactedPayload = {\n      ...requestPayload,\n      message: {\n        ...requestPayload.message,\n        parts: [\n          {\n            kind: 'data',\n            data: { skill: toolName, parameters: redactedParameters },\n          },\n        ],\n      },\n      ...(requestPayload.configuration && {\n        configuration: {\n          pushNotificationConfig: redactPushNotificationConfigForDebug(\n            requestPayload.configuration.pushNotificationConfig\n          )!,\n        },\n      }),\n    };\n    debugLogs.push({\n      type: 'info',\n      message: `A2A: Calling skill ${toolName} with parameters: ${JSON.stringify(\n        redactedParameters\n      )}. Payload size: ${payloadSize} bytes`,\n      timestamp: new Date().toISOString(),\n      payloadSize,\n      actualPayload: redactedPayload,\n    });\n\n    debugLogs.push({\n      type: 'info',\n      message: `A2A: Sending message via sendMessage()`,\n      timestamp: new Date().toISOString(),\n      skill: toolName,\n    });\n\n    const messageResponse = await client.sendMessage(requestPayload);\n\n    debugLogs.push({\n      type: messageResponse?.error ? 'error' : 'success',\n      message: `A2A: Response received (${messageResponse?.error ? 'error' : 'success'})`,\n      timestamp: new Date().toISOString(),\n      response: messageResponse,\n      skill: toolName,\n    });\n\n    if (messageResponse?.error || messageResponse?.result?.error) {\n      // adcp-client#1575: when the seller emits a spec-compliant terminal-state\n      // Task carrying an `adcp_error` DataPart (per AdCP transport-errors §A2A\n      // Binding), the structured artifact is canonical — even if the seller\n      // also surfaced a transport-level error string. Pass the response\n      // through so the upstream unwrapper extracts `adcp_error.code` instead\n      // of throwing a generic message that loses the AdCP error envelope.\n      if (!hasTerminalTaskWithDataArtifact(messageResponse)) {\n        const errorObj = messageResponse.error || messageResponse.result?.error;\n        const errorMessage = errorObj.message || JSON.stringify(errorObj);\n        throw new Error(`A2A agent returned error: ${errorMessage}`);\n      }\n    }\n\n    return messageResponse;\n  } catch (error: unknown) {\n    if (is401Error(error, context.got401Ref.value)) {\n      // Evict this cache entry — credential may have expired or been\n      // revoked. Same disambiguator as the original `getOrCreateA2AClient`\n      // call: when the credential rode on customHeaders.Authorization (Basic\n      // case) rather than authToken, the cache key must reflect that or we\n      // evict the wrong entry.\n      const signingContext = signingContextStorage.getStore();\n      a2aClientCache.delete(a2aCacheKey(agentUrl, authToken, signingContext?.cacheKey, context.customHeaders));\n\n      debugLogs.push({\n        type: 'error',\n        message: `A2A: Authentication required for ${agentUrl}`,\n        timestamp: new Date().toISOString(),\n      });\n\n      // Re-probe to surface the WWW-Authenticate scheme on the error envelope.\n      // Basic-fronted agents (Apigee/Kong/AWS API GW with a BasicAuthentication\n      // policy) would otherwise leave consumers chasing OAuth metadata that\n      // doesn't exist. Matches the MCP discovery throw site in\n      // `SingleAgentClient.discoverMCPEndpoint`.\n      const challenge = await probeAuthChallenge(agentUrl);\n      const oauthMetadata = await discoverOAuthMetadata(agentUrl);\n      throw new AuthenticationRequiredError(agentUrl, oauthMetadata || undefined, undefined, challenge ?? undefined);\n    }\n\n    throw error;\n  }\n}\n"],"mappings":"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","names":["require"]}
+{"version":3,"sources":["../../../src/lib/protocols/a2a.ts"],"sourcesContent":["import { fileURLToPath as __adcpFileURLToPath } from 'node:url';\nimport { dirname as __adcpDirname } from 'node:path';\nimport { createRequire as __adcpCreateRequire } from 'node:module';\nconst __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));\nconst require = __adcpCreateRequire(import.meta.url);\n// Official A2A client implementation - NO FALLBACKS\nimport { A2AClient as A2AClientImpl } from '@a2a-js/sdk/client';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { createHmac, randomUUID } from 'node:crypto';\nimport type { PushNotificationConfig } from '../types/tools.generated';\nimport type { DebugLogEntry } from '../types/adcp';\nimport { AuthenticationRequiredError, is401Error } from '../errors';\nimport { discoverOAuthMetadata } from '../auth/oauth/discovery';\nimport { probeAuthChallenge } from '../auth/oauth/authorization-required';\nimport { withSpan, injectTraceHeaders } from '../observability/tracing';\nimport { isAgentCardPath, buildCardUrls } from '../utils/a2a-discovery';\nimport { buildAgentSigningFetch, signingContextStorage, type AgentSigningContext } from '../signing/client';\nimport { toSignerKey, isInlineSigningConfig, isProviderSigningConfig } from '../signing/agent-fetch';\nimport { createSigningFetch, type FetchLike } from '../signing/fetch';\nimport { createSigningFetchAsync } from '../signing/fetch-async';\nimport type { AgentConfig } from '../types/adcp';\nimport { redactIdempotencyKeyInArgs } from '../utils/idempotency';\nimport { wrapFetchWithCapture } from './rawResponseCapture';\nimport { wrapFetchWithSizeLimit } from './responseSizeLimit';\nimport { wrapFetchWithTransportDiagnostics } from './transportDiagnostics';\nimport { DEFAULT_REQUEST_TIMEOUT_MS, resolveRequestTimeoutMs, withAbortSignal } from './abort';\nimport { getLatestA2ADataPartFromResponse } from '../utils/a2a-artifacts';\n\n// The A2A SDK client is used untyped: request/response shapes are validated at\n// runtime against the AdCP wire contract, not against the SDK's exported\n// types. Preserves the prior behaviour of the CommonJS `require` form.\nconst A2AClient: any = A2AClientImpl;\n\nif (!A2AClient) {\n  throw new Error('A2A SDK client is required. Please install @a2a-js/sdk');\n}\n\n/**\n * Per-call state flowed through AsyncLocalStorage so concurrent callers\n * that share a cached A2AClient don't clobber each other's debugLogs,\n * customHeaders, or 401 flag.\n */\ninterface A2ACallContext {\n  customHeaders?: Record<string, string>;\n  debugLogs: DebugLogEntry[];\n  got401Ref: { value: boolean };\n  signal?: AbortSignal;\n  requestTimeoutMs?: number;\n  fetchFn?: typeof fetch;\n}\n\nconst callContextStorage = new AsyncLocalStorage<A2ACallContext>();\n\n/**\n * Cached A2AClient keyed by (agentUrl, authToken hash). Avoids re-fetching\n * /.well-known/agent.json on every tool call. The cached client's fetchImpl\n * reads per-call state from callContextStorage, so concurrent calls to the\n * same cache entry are safe.\n *\n * Process-global singleton — not suitable for multi-tenant servers that\n * want per-tenant isolation (use separate processes or explicit cache keys).\n */\nconst a2aClientCache = new Map<string, InstanceType<typeof A2AClient>>();\nconst pendingA2AClients = new Map<string, Promise<InstanceType<typeof A2AClient>>>();\n\n/**\n * Build the A2A connection-cache key. Mirrors the rationale in\n * `src/lib/protocols/mcp.ts:connectionCacheKey`: when the caller is using a\n * non-bearer scheme (RFC 7617 Basic from the CLI's `--auth-scheme basic`\n * shape, or any future caller-injected `Authorization` header), `authToken`\n * is undefined and the credential rides on the customHeaders bag. Hashing\n * only `authToken` would let two callers with different `user:pass`\n * credentials share a single cached A2AClient — single-CLI-process safe,\n * multi-tenant SDK consumer not safe.\n *\n * `customHeaders` also feed the key so tenant/routing headers cannot reuse a\n * card/client discovered for another caller. Scoped fetch calls bypass this\n * cache entirely (see `getOrCreateA2AClient`).\n */\nfunction a2aCacheKey(\n  agentUrl: string,\n  authToken?: string,\n  signingCacheKey?: string,\n  customHeaders?: Record<string, string>\n): string {\n  // 64-bit Map-key disambiguator — NOT a password hash. The cached client\n  // closes over the full credential, so a hypothetical hash collision still\n  // sends the original credential on the wire, just possibly cache-miss\n  // and reconnect. Routed via `cacheDisambiguator` (HMAC-SHA256 with empty\n  // key) instead of bare `createHash` so CodeQL's\n  // `js/insufficient-password-hash` heuristic doesn't misclassify the\n  // dataflow — see the helper docstring for the full rationale.\n  const fingerprint = authToken ?? extractA2AAuthHeader(customHeaders);\n  const tokenSuffix = fingerprint ? `::${cacheDisambiguator(fingerprint)}` : '';\n  const headersKey = headersCacheDisambiguator(customHeaders);\n  const headersSuffix = headersKey ? `::headers:${headersKey}` : '';\n  const signingSuffix = signingCacheKey ? `::${signingCacheKey}` : '';\n  return `${agentUrl}${tokenSuffix}${headersSuffix}${signingSuffix}`;\n}\n\n/**\n * Produce a stable 64-bit Map-key disambiguator from credential material.\n * Mirrors the helper in `src/lib/protocols/mcp.ts` — the two protocol\n * modules intentionally don't share runtime imports, so each carries its\n * own copy. See the MCP-side docstring for the full rationale.\n */\nfunction cacheDisambiguator(value: string): string {\n  return createHmac('sha256', '').update(value).digest('hex').slice(0, 16);\n}\n\n/**\n * Case-insensitive lookup of `Authorization` on a header bag. Mirrors the\n * MCP-side helper; A2A keeps its own copy because the two protocol modules\n * intentionally don't share runtime imports.\n */\nfunction extractA2AAuthHeader(headers: Record<string, string> | undefined): string | undefined {\n  if (!headers) return undefined;\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase() === 'authorization' && value) return value;\n  }\n  return undefined;\n}\n\nfunction headersCacheDisambiguator(headers?: Record<string, string>): string | undefined {\n  const entries = Object.entries(headers ?? {})\n    .filter(([key]) => {\n      const lower = key.toLowerCase();\n      return lower !== 'traceparent' && lower !== 'tracestate' && lower !== 'baggage';\n    })\n    .map(([key, value]) => [key.toLowerCase(), value] as const)\n    .sort(([a], [b]) => a.localeCompare(b));\n  return entries.length > 0 ? cacheDisambiguator(JSON.stringify(entries)) : undefined;\n}\n\nfunction redactHeadersForDebug(headers: Record<string, string>): Record<string, string> {\n  return Object.fromEntries(Object.keys(headers).map(key => [key, '***']));\n}\n\nfunction redactPushNotificationConfigForDebug(\n  config: PushNotificationConfig | undefined\n): PushNotificationConfig | undefined {\n  if (!config) return undefined;\n  return {\n    ...config,\n    ...(config.token && { token: '***' }),\n    ...(config.authentication && {\n      authentication: {\n        ...config.authentication,\n        ...(config.authentication.credentials && { credentials: '***' }),\n      },\n    }),\n  };\n}\n\n/**\n * Clear all cached A2A clients. Called by closeConnections('a2a').\n * A2A clients hold no persistent network resources (unlike MCP), so this\n * is just cache eviction.\n */\nexport function closeA2AConnections(): void {\n  a2aClientCache.clear();\n  pendingA2AClients.clear();\n}\n\n/**\n * Wall-clock cap on a fire-and-forget cancel. A2A sellers that accept the\n * TCP connect but never respond would otherwise pin the event loop past the\n * buyer's abort, which defeats the whole point of fire-and-forget.\n */\nconst CANCEL_TIMEOUT_MS = 5000;\n\n/**\n * Fire-and-forget A2A tasks/cancel for an in-flight task (A2A 0.3.0 §7.4).\n *\n * Sends a raw JSON-RPC 2.0 POST directly to the agent endpoint with the same\n * auth header shape as `callA2AToolImpl` (Bearer + x-adcp-auth). Does NOT\n * enter `callContextStorage` — debug-log capture and 401-cache-eviction are\n * intentionally skipped for best-effort cancellation.\n *\n * **Auth-code OAuth gap:** `authToken` is resolved by `getAuthToken(agent)`,\n * which returns `undefined` for authorization-code-flow sellers (those tokens\n * are managed by the OAuth provider path in `ProtocolClient.callTool`, not\n * accessible here). Cancel calls to those sellers go out unauthenticated and\n * will likely 401 non-fatally.\n *\n * **Phase 2 (adcp-client#1617 follow-up):** when `agent.request_signing` is\n * configured, the cancel POST is signed with the agent's signer key. The\n * `signingContextStorage` ALS scope around `callA2AToolImpl` does NOT extend\n * into `pollTaskCompletion` (sibling promise trees), so we can't replay the\n * captured ALS context — instead we rebuild a one-shot signer fetch from\n * `agent.request_signing` directly and use it for this single POST. Inline\n * keys go through `createSigningFetch` (sync); provider-backed configs use\n * `createSigningFetchAsync`. A `signed-requests` seller that requires\n * signing on `tasks/cancel` (or applies a uniform \"all mutating POSTs must\n * be signed\" policy) now accepts the cancel; one without signing config on\n * the agent gets the Phase 1 unsigned path.\n *\n * The caller is responsible for swallowing errors: cancel failure\n * (TaskNotCancelable, network error, auth rejection, network timeout) is\n * non-fatal because the buyer is already abandoning the task.\n *\n * @param agent     The agent config (used for URL, auth token, signing).\n * @param taskId    The server-assigned A2A Task.id to cancel.\n */\nexport async function cancelA2ATask(agent: AgentConfig, taskId: string, fetchFn?: typeof fetch): Promise<void> {\n  // Defense-in-depth (ad-tech-protocol-expert review of #1640): the cancel\n  // POST is JSON-RPC at the bare A2A endpoint. Calling this on an MCP agent\n  // would POST `tasks/cancel` JSON-RPC at an MCP endpoint and 404. The\n  // single call site (`pollTaskCompletion`) already gates on\n  // `agent.protocol === 'a2a'`; this assertion catches future call sites\n  // that forget the gate.\n  if (agent.protocol !== 'a2a') {\n    return;\n  }\n  const agentUrl = agent.agent_uri;\n  const authToken = agent.auth_token;\n\n  const headers: Record<string, string> = {\n    'content-type': 'application/json',\n    accept: 'application/json',\n  };\n  if (authToken) {\n    headers['Authorization'] = `Bearer ${authToken}`;\n    headers['x-adcp-auth'] = authToken;\n  }\n  // JSON-RPC 2.0 §4.1.3: `id: null` flags the request as a *notification*,\n  // and the server MUST NOT respond. A2A 0.3.0 §7.4 defines `tasks/cancel`\n  // as a request/response method (returns the canceled `Task` or\n  // `TaskNotCancelableError`), so a strict A2A server can legitimately\n  // reject `id: null` as a protocol violation. Use a real id and just drop\n  // the response on the floor — fire-and-forget is the caller's discipline,\n  // not a wire-protocol claim.\n  const body = JSON.stringify({\n    jsonrpc: '2.0',\n    id: randomUUID(),\n    method: 'tasks/cancel',\n    params: { id: taskId },\n  });\n  // Bound the cancel: a hung fetch would orphan-pin the event loop past the\n  // buyer's abort, defeating fire-and-forget. AbortSignal.timeout() is the\n  // standard primitive; the caller's `.catch()` swallows the AbortError.\n  const init: RequestInit = {\n    method: 'POST',\n    headers,\n    body,\n    signal: AbortSignal.timeout(CANCEL_TIMEOUT_MS),\n  };\n\n  // adcp-client#1617 Phase 2: sign the cancel POST when the agent has a\n  // signer configured. We bypass the `buildAgentSigningFetch` capability-\n  // gate path because `tasks/cancel` is an A2A protocol method, not an\n  // AdCP tool — the seller's `request_signing.supported_for` typically\n  // lists AdCP tool names, not protocol-level methods. The right model\n  // here: if the agent claims signing AT ALL, sign every mutating POST\n  // we send to it on the cancel path. Sellers with uniform \"must be\n  // signed\" policies accept this; sellers that only check signing on\n  // specific AdCP tools simply ignore the extra signature.\n  //\n  // TODO(adcp#4318, adcp-client#1617): when the AdCP spec adds explicit\n  // verifier coverage for A2A protocol methods (likely in 3.1 as a new\n  // `protocol_methods_supported_for` / `protocol_methods_required_for`\n  // field on `request_signing`), narrow this default by reading the\n  // seller's advertised coverage from `getCapability()` and gating on\n  // the `tasks/cancel` membership. The over-sign default stays as the\n  // fallback for spec-silent sellers (3.0.x and earlier).\n  if (agent.request_signing) {\n    const upstream: FetchLike = (input, ini) =>\n      fetchFn ? fetchFn(input as RequestInfo | URL, ini) : fetch(input as RequestInfo, ini);\n    if (isInlineSigningConfig(agent.request_signing)) {\n      const signed = createSigningFetch(upstream, toSignerKey(agent.request_signing));\n      await signed(agentUrl, init);\n      return;\n    }\n    if (isProviderSigningConfig(agent.request_signing)) {\n      const signed = createSigningFetchAsync(upstream, agent.request_signing.provider);\n      await signed(agentUrl, init);\n      return;\n    }\n  }\n\n  await (fetchFn ?? fetch)(agentUrl, init);\n}\n\nasync function getOrCreateA2AClient(\n  agentUrl: string,\n  authToken: string | undefined,\n  customHeaders?: Record<string, string>,\n  bypassCache = false\n): Promise<InstanceType<typeof A2AClient>> {\n  const signingContext = signingContextStorage.getStore();\n  const fetchFn = callContextStorage.getStore()?.fetchFn;\n  const cacheKey = a2aCacheKey(agentUrl, authToken, signingContext?.cacheKey, customHeaders);\n  // Scoped fetchers often carry request/tenant-specific egress policy. Keep\n  // those calls one-shot so neither agent-card discovery nor a client created\n  // under one policy can be reused by another caller, and so short-lived\n  // closure identities do not grow the global cache without bound.\n  if (bypassCache || fetchFn) {\n    return createA2AClient(agentUrl, authToken);\n  }\n  const cached = a2aClientCache.get(cacheKey);\n  if (cached) return cached;\n\n  const pending = pendingA2AClients.get(cacheKey);\n  if (pending) return pending;\n\n  const promise = createA2AClient(agentUrl, authToken)\n    .then(client => {\n      a2aClientCache.set(cacheKey, client);\n      return client;\n    })\n    .finally(() => {\n      pendingA2AClients.delete(cacheKey);\n    });\n\n  pendingA2AClients.set(cacheKey, promise);\n  return promise;\n}\n\nasync function createA2AClient(\n  agentUrl: string,\n  authToken: string | undefined\n): Promise<InstanceType<typeof A2AClient>> {\n  const fetchImpl = buildFetchImpl(authToken);\n  const cardUrls = buildCardUrls(agentUrl);\n\n  const context = callContextStorage.getStore();\n  context?.debugLogs.push({\n    type: 'info',\n    message: `A2A: Discovering agent card at ${cardUrls.join(', ')}`,\n    timestamp: new Date().toISOString(),\n  });\n\n  let client: InstanceType<typeof A2AClient> | undefined;\n  let lastError: Error = new Error(`A2A agent card not found at ${cardUrls.join(', ')}`);\n  for (const cardUrl of cardUrls) {\n    try {\n      client = await A2AClient.fromCardUrl(cardUrl, { fetchImpl });\n      break;\n    } catch (err: unknown) {\n      lastError = err as Error;\n      if (context?.got401Ref.value) break;\n    }\n  }\n  if (!client) throw lastError;\n\n  return client;\n}\n\nfunction buildFetchImpl(authToken: string | undefined) {\n  // The A2A client is cached per (url, authToken, signingCacheKey). We capture\n  // the signing context at client-creation time so all subsequent calls that\n  // share this cached client use the same signing identity — changing identity\n  // requires a different cache entry, built on a separate call that enters ALS\n  // with a different context.\n  const signingContext = signingContextStorage.getStore();\n\n  // Innermost wrapper: enforce response body size cap from the active\n  // `responseSizeLimitStorage` slot. Pass-through when no slot is set.\n  const networkFetch = wrapFetchWithTransportDiagnostics(\n    wrapFetchWithSizeLimit((input, init) => {\n      const scopedFetch = callContextStorage.getStore()?.fetchFn;\n      return scopedFetch ? scopedFetch(input, init) : fetch(input as any, init);\n    })\n  );\n\n  // Inner fetch handles auth/header injection and 401 detection. If the\n  // agent has request-signing configured, we wrap it with the AdCP signing\n  // fetch so the signature covers the exact bytes we're about to send (auth\n  // headers included, since the signer re-reads the final header record).\n  const baseFetch = async (url: string | URL | Request, options?: RequestInit): Promise<Response> => {\n    const context = callContextStorage.getStore();\n\n    const existingHeaders: Record<string, string> = {};\n    if (options?.headers) {\n      if (options.headers instanceof Headers) {\n        options.headers.forEach((value, key) => {\n          existingHeaders[key] = value;\n        });\n      } else if (Array.isArray(options.headers)) {\n        for (const [key, value] of options.headers) {\n          existingHeaders[key] = value;\n        }\n      } else {\n        Object.assign(existingHeaders, options.headers);\n      }\n    }\n\n    // Only inject trace context headers for actual tool requests, not discovery.\n    // The agent card endpoint is external/untrusted — don't leak trace IDs to it.\n    const urlString = typeof url === 'string' ? url : url.toString();\n    const isDiscoveryRequest = isAgentCardPath(urlString);\n    const traceHeaders = isDiscoveryRequest ? {} : injectTraceHeaders();\n    const requestTimeoutMs = isDiscoveryRequest\n      ? resolveRequestTimeoutMs(context?.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS)\n      : resolveRequestTimeoutMs(context?.requestTimeoutMs);\n\n    // Merge: existing < trace < custom < auth (auth always wins)\n    const headers: Record<string, string> = {\n      ...existingHeaders,\n      ...traceHeaders,\n      ...context?.customHeaders,\n      ...(authToken && {\n        Authorization: `Bearer ${authToken}`,\n        'x-adcp-auth': authToken,\n      }),\n    };\n\n    context?.debugLogs.push({\n      type: 'info',\n      message: `A2A: Fetch to ${urlString}`,\n      timestamp: new Date().toISOString(),\n      hasAuth: !!authToken,\n      headers: redactHeadersForDebug(headers),\n    });\n\n    const response = await withAbortSignal<Response>([context?.signal, options?.signal], requestTimeoutMs, signal =>\n      networkFetch(url as any, { ...options, headers, signal })\n    );\n\n    if (response.status === 401 && context) {\n      context.got401Ref.value = true;\n    }\n\n    return response;\n  };\n\n  if (!signingContext) return wrapFetchWithCapture(baseFetch);\n\n  // The signing wrapper assembles headers into the signature base. We invoke\n  // it first so the signer sees the caller-supplied headers; baseFetch then\n  // overlays auth/trace headers afterwards — A2A's auth scheme (bearer) is\n  // not among the MANDATORY_COMPONENTS and is injected by the counterparty's\n  // transport layer, not signed.\n  const signingFetch = buildAgentSigningFetch({\n    upstream: (input, init) => baseFetch(input as any, init),\n    signing: signingContext.signing,\n    getCapability: signingContext.getCapability,\n  });\n  return wrapFetchWithCapture(signingFetch as typeof fetch);\n}\n\n/**\n * Terminal A2A task states per A2A 0.3.0 §3.4. Only these can carry the\n * AdCP-mandated artifact + DataPart envelope (per transport-errors §A2A\n * Binding); intermediate states (`working`, `submitted`, `input-required`,\n * `auth-required`) carry no completion artifact.\n */\nconst TERMINAL_A2A_STATES = new Set(['completed', 'failed', 'rejected', 'canceled']);\n\n/**\n * Detect whether a JSON-RPC response carries a spec-compliant terminal-state\n * Task with at least one artifact containing a structured DataPart payload.\n * Per AdCP transport-errors §A2A Binding, the artifact's DataPart is the\n * canonical envelope for both the success arm (`completed`) and the error\n * arms (`failed` / `rejected` / `canceled`). The criterion intentionally\n * matches the unwrapper's terminal-state extraction in\n * `unwrapA2AResponse` — keeping protocol layer and unwrapper in lockstep\n * across all terminal states, not just the error arms.\n *\n * Used to short-circuit the generic \"A2A agent returned error\" throw when\n * a non-conformant seller surfaces both a transport-level `result.error`\n * hint and the canonical artifact envelope side-by-side. The DataPart is\n * authoritative; the throw would otherwise swallow it.\n */\nfunction hasTerminalTaskWithDataArtifact(response: unknown): boolean {\n  if (!response || typeof response !== 'object') return false;\n  const result = (response as { result?: unknown }).result;\n  if (!result || typeof result !== 'object') return false;\n  const r = result as { kind?: unknown; status?: unknown; artifacts?: unknown };\n  if (r.kind !== 'task') return false;\n  const status = r.status as { state?: unknown } | undefined;\n  if (typeof status?.state !== 'string' || !TERMINAL_A2A_STATES.has(status.state)) return false;\n  return getLatestA2ADataPartFromResponse(response) !== undefined;\n}\n\n/**\n * Protocol-level session identifiers that ride on the A2A Message envelope\n * (not in the skill parameters). `contextId` binds sends to a server-side\n * conversation; `taskId` resumes an existing non-terminal task.\n *\n * Callers (buyers) typically retain these across calls on a per-conversation\n * AgentClient; see AgentClient.getContextId() / getPendingTaskId().\n */\nexport interface A2ASessionIds {\n  contextId?: string;\n  taskId?: string;\n}\n\nexport async function callA2ATool(\n  agentUrl: string,\n  toolName: string,\n  parameters: Record<string, unknown>,\n  authToken?: string,\n  debugLogs: DebugLogEntry[] = [],\n  pushNotificationConfig?: PushNotificationConfig,\n  customHeaders?: Record<string, string>,\n  signingContext?: AgentSigningContext,\n  session?: A2ASessionIds,\n  signal?: AbortSignal,\n  requestTimeoutMs?: number,\n  fetchFn?: typeof fetch\n): Promise<unknown> {\n  return withSpan(\n    'adcp.a2a.call_tool',\n    {\n      'adcp.tool': toolName,\n      'http.url': agentUrl,\n    },\n    async () => {\n      const context: A2ACallContext = {\n        customHeaders,\n        debugLogs,\n        got401Ref: { value: false },\n        signal,\n        requestTimeoutMs,\n        fetchFn,\n      };\n      return signingContextStorage.run(signingContext, () =>\n        callContextStorage.run(context, () =>\n          callA2AToolImpl(\n            agentUrl,\n            toolName,\n            parameters,\n            authToken,\n            debugLogs,\n            pushNotificationConfig,\n            context,\n            session\n          )\n        )\n      );\n    }\n  );\n}\n\nasync function callA2AToolImpl(\n  agentUrl: string,\n  toolName: string,\n  parameters: Record<string, unknown>,\n  authToken: string | undefined,\n  debugLogs: DebugLogEntry[],\n  pushNotificationConfig: PushNotificationConfig | undefined,\n  context: A2ACallContext,\n  session: A2ASessionIds | undefined\n): Promise<unknown> {\n  try {\n    const client = await getOrCreateA2AClient(\n      agentUrl,\n      authToken,\n      context.customHeaders,\n      !!context.signal || context.requestTimeoutMs !== undefined\n    );\n\n    const requestPayload: {\n      message: {\n        messageId: string;\n        role: string;\n        kind: string;\n        parts: Array<{ kind: string; data: { skill: string; parameters: Record<string, unknown> } }>;\n        contextId?: string;\n        taskId?: string;\n      };\n      configuration?: { pushNotificationConfig: PushNotificationConfig };\n    } = {\n      message: {\n        messageId: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,\n        role: 'user',\n        kind: 'message',\n        parts: [\n          {\n            kind: 'data',\n            data: {\n              skill: toolName,\n              parameters: parameters,\n            },\n          },\n        ],\n        ...(session?.contextId && { contextId: session.contextId }),\n        ...(session?.taskId && { taskId: session.taskId }),\n      },\n    };\n\n    if (pushNotificationConfig) {\n      requestPayload.configuration = {\n        pushNotificationConfig: pushNotificationConfig,\n      };\n    }\n\n    const payloadSize = JSON.stringify(requestPayload).length;\n    const redactedParameters = redactIdempotencyKeyInArgs(parameters);\n    const redactedPayload = {\n      ...requestPayload,\n      message: {\n        ...requestPayload.message,\n        parts: [\n          {\n            kind: 'data',\n            data: { skill: toolName, parameters: redactedParameters },\n          },\n        ],\n      },\n      ...(requestPayload.configuration && {\n        configuration: {\n          pushNotificationConfig: redactPushNotificationConfigForDebug(\n            requestPayload.configuration.pushNotificationConfig\n          )!,\n        },\n      }),\n    };\n    debugLogs.push({\n      type: 'info',\n      message: `A2A: Calling skill ${toolName} with parameters: ${JSON.stringify(\n        redactedParameters\n      )}. Payload size: ${payloadSize} bytes`,\n      timestamp: new Date().toISOString(),\n      payloadSize,\n      actualPayload: redactedPayload,\n    });\n\n    debugLogs.push({\n      type: 'info',\n      message: `A2A: Sending message via sendMessage()`,\n      timestamp: new Date().toISOString(),\n      skill: toolName,\n    });\n\n    const messageResponse = await client.sendMessage(requestPayload);\n\n    debugLogs.push({\n      type: messageResponse?.error ? 'error' : 'success',\n      message: `A2A: Response received (${messageResponse?.error ? 'error' : 'success'})`,\n      timestamp: new Date().toISOString(),\n      response: messageResponse,\n      skill: toolName,\n    });\n\n    if (messageResponse?.error || messageResponse?.result?.error) {\n      // adcp-client#1575: when the seller emits a spec-compliant terminal-state\n      // Task carrying an `adcp_error` DataPart (per AdCP transport-errors §A2A\n      // Binding), the structured artifact is canonical — even if the seller\n      // also surfaced a transport-level error string. Pass the response\n      // through so the upstream unwrapper extracts `adcp_error.code` instead\n      // of throwing a generic message that loses the AdCP error envelope.\n      if (!hasTerminalTaskWithDataArtifact(messageResponse)) {\n        const errorObj = messageResponse.error || messageResponse.result?.error;\n        const errorMessage = errorObj.message || JSON.stringify(errorObj);\n        throw new Error(`A2A agent returned error: ${errorMessage}`);\n      }\n    }\n\n    return messageResponse;\n  } catch (error: unknown) {\n    if (is401Error(error, context.got401Ref.value)) {\n      // Evict this cache entry — credential may have expired or been\n      // revoked. Same disambiguator as the original `getOrCreateA2AClient`\n      // call: when the credential rode on customHeaders.Authorization (Basic\n      // case) rather than authToken, the cache key must reflect that or we\n      // evict the wrong entry.\n      const signingContext = signingContextStorage.getStore();\n      a2aClientCache.delete(a2aCacheKey(agentUrl, authToken, signingContext?.cacheKey, context.customHeaders));\n\n      debugLogs.push({\n        type: 'error',\n        message: `A2A: Authentication required for ${agentUrl}`,\n        timestamp: new Date().toISOString(),\n      });\n\n      // Re-probe to surface the WWW-Authenticate scheme on the error envelope.\n      // Basic-fronted agents (Apigee/Kong/AWS API GW with a BasicAuthentication\n      // policy) would otherwise leave consumers chasing OAuth metadata that\n      // doesn't exist. Matches the MCP discovery throw site in\n      // `SingleAgentClient.discoverMCPEndpoint`.\n      const challenge = await probeAuthChallenge(agentUrl, { fetchFn: context.fetchFn });\n      const oauthMetadata = await discoverOAuthMetadata(agentUrl, { fetch: context.fetchFn });\n      throw new AuthenticationRequiredError(agentUrl, oauthMetadata || undefined, undefined, challenge ?? undefined);\n    }\n\n    throw error;\n  }\n}\n"],"mappings":"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","names":["require"]}

package/dist/lib/protocols/index.d.mts

@@ -64,11 +64,28 @@ export interface TransportOptions {
      *
      * @remarks
      * Future hardening knobs (DNS-rebind defense, scheme allow-list, request
-     * timeout overrides) will land here as additional fields rather than
-     * forcing callers to compose their own `fetch` — wrap order with the SDK's
-     * existing signing / capture wrappers is non-obvious and a footgun.
+     * timeout overrides) will land here as additional fields. When `fetchFn`
+     * is supplied, the SDK composes it inside its signing, capture, size-limit,
+     * timeout, and diagnostics wrappers so callers do not have to reproduce
+     * that non-obvious ordering themselves.
      */
     maxResponseBytes?: number;
+    /**
+     * Scoped fetch implementation for all outbound HTTP performed on behalf of
+     * this client or call, including endpoint/card discovery, tool listing,
+     * OAuth discovery and token refresh, and MCP/A2A tool requests.
+     *
+     * The function is runtime-only configuration and is never serialized into
+     * agent records, storyboard artifacts, or compliance output. When unset,
+     * the SDK uses the global `fetch` implementation.
+     *
+     * For SSRF-sensitive metadata probes, supplying this function makes it the
+     * trusted network boundary: the SDK still validates schemes and resolved
+     * addresses, but a custom fetch API cannot accept the SDK's pinned undici
+     * dispatcher. The implementation must therefore prevent DNS rebinding (for
+     * example with an egress proxy or its own DNS pinning).
+     */
+    fetchFn?: typeof fetch;
     /**
      * Timeout in milliseconds for bounded one-shot transport requests such as
      * A2A agent-card discovery and MCP read-path probes. Defaults to 60 seconds

package/dist/lib/protocols/index.d.ts

@@ -64,11 +64,28 @@ export interface TransportOptions {
      *
      * @remarks
      * Future hardening knobs (DNS-rebind defense, scheme allow-list, request
-     * timeout overrides) will land here as additional fields rather than
-     * forcing callers to compose their own `fetch` — wrap order with the SDK's
-     * existing signing / capture wrappers is non-obvious and a footgun.
+     * timeout overrides) will land here as additional fields. When `fetchFn`
+     * is supplied, the SDK composes it inside its signing, capture, size-limit,
+     * timeout, and diagnostics wrappers so callers do not have to reproduce
+     * that non-obvious ordering themselves.
      */
     maxResponseBytes?: number;
+    /**
+     * Scoped fetch implementation for all outbound HTTP performed on behalf of
+     * this client or call, including endpoint/card discovery, tool listing,
+     * OAuth discovery and token refresh, and MCP/A2A tool requests.
+     *
+     * The function is runtime-only configuration and is never serialized into
+     * agent records, storyboard artifacts, or compliance output. When unset,
+     * the SDK uses the global `fetch` implementation.
+     *
+     * For SSRF-sensitive metadata probes, supplying this function makes it the
+     * trusted network boundary: the SDK still validates schemes and resolved
+     * addresses, but a custom fetch API cannot accept the SDK's pinned undici
+     * dispatcher. The implementation must therefore prevent DNS rebinding (for
+     * example with an egress proxy or its own DNS pinning).
+     */
+    fetchFn?: typeof fetch;
     /**
      * Timeout in milliseconds for bounded one-shot transport requests such as
      * A2A agent-card discovery and MCP read-path probes. Defaults to 60 seconds

package/dist/lib/protocols/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/protocols/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/protocols/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/protocols/index.js

@@ -56,6 +56,7 @@ var import_mcp3 = require('./mcp.js');
 var import_a2a3 = require('./a2a.js');
 var import_auth = require('../auth/index.js');
 var import_oauth = require('../auth/oauth/index.js');
+var import_provider_cache = require('../auth/oauth/provider-cache.js');
 var import_errors = require('../errors/index.js');
 var import_net = require('../net/index.js');
 var import_validation = require('../validation/index.js');
@@ -74,19 +75,6 @@ async function closeConnections(protocol = "mcp") {
     (0, import_a2a.closeA2AConnections)();
   }
 }
-const nonInteractiveOAuthProviderCache = /* @__PURE__ */ new WeakMap();
-function getNonInteractiveOAuthProvider(agent) {
-  let provider = nonInteractiveOAuthProviderCache.get(agent);
-  if (!provider) {
-    const storage = (0, import_oauth.getAgentStorage)(agent);
-    provider = (0, import_oauth.createNonInteractiveOAuthProvider)(agent, {
-      agentHint: agent.id,
-      storage
-    });
-    nonInteractiveOAuthProviderCache.set(agent, provider);
-  }
-  return provider;
-}
 function resolveWireMajor(adcpVersion) {
   if (adcpVersion === void 0) return import_version.ADCP_MAJOR_VERSION;
   const parsed = (0, import_version.parseAdcpMajorVersion)(adcpVersion);
@@ -187,7 +175,11 @@ class ProtocolClient {
             if (agent.oauth_client_credentials) {
               const ccStorage = (0, import_oauth.getAgentStorage)(agent);
               const allowPrivateIp = (0, import_net.isLikelyPrivateUrl)(agent.agent_uri);
-              await (0, import_oauth.ensureClientCredentialsTokens)(agent, { storage: ccStorage, allowPrivateIp });
+              await (0, import_oauth.ensureClientCredentialsTokens)(agent, {
+                storage: ccStorage,
+                allowPrivateIp,
+                fetch: transport?.fetchFn
+              });
             }
             const authToken = (0, import_auth.getAuthToken)(agent);
             const signingContext = (0, import_client.buildAgentSigningContext)(agent);
@@ -220,7 +212,11 @@ class ProtocolClient {
             if (agent.protocol === "mcp") {
               const argsWithWebhook = pushNotificationConfig ? { ...argsWithVersion, push_notification_config: pushNotificationConfig } : argsWithVersion;
               if (agent.oauth_tokens && !agent.oauth_client_credentials) {
-                const authProvider = getNonInteractiveOAuthProvider(agent);
+                const authProvider = (0, import_provider_cache.getNonInteractiveOAuthProvider)(agent, {
+                  agentHint: agent.id,
+                  storage: (0, import_oauth.getAgentStorage)(agent),
+                  allowHttp: (0, import_net.isLikelyPrivateUrl)(agent.agent_uri)
+                });
                 try {
                   return await (0, import_mcp3.callMCPToolWithOAuth)({
                     agentUrl: agent.agent_uri,
@@ -231,10 +227,11 @@ class ProtocolClient {
                     customHeaders: agent.headers,
                     signingContext,
                     signal,
-                    requestTimeoutMs: transport?.requestTimeoutMs
+                    requestTimeoutMs: transport?.requestTimeoutMs,
+                    fetchFn: transport?.fetchFn
                   });
                 } catch (err) {
-                  await rethrowAsNeedsAuthorization(err, agent.agent_uri);
+                  await rethrowAsNeedsAuthorization(err, agent.agent_uri, transport?.fetchFn);
                   throw err;
                 }
               }
@@ -251,14 +248,20 @@ class ProtocolClient {
                     ...signal && { signal },
                     ...transport?.requestTimeoutMs !== void 0 && {
                       requestTimeoutMs: transport.requestTimeoutMs
-                    }
+                    },
+                    ...transport?.fetchFn && { fetchFn: transport.fetchFn }
                   }
                 );
               } catch (err) {
                 if (agent.oauth_client_credentials && (0, import_errors.is401Error)(err)) {
                   const ccStorage = (0, import_oauth.getAgentStorage)(agent);
                   const allowPrivateIp = (0, import_net.isLikelyPrivateUrl)(agent.agent_uri);
-                  await (0, import_oauth.ensureClientCredentialsTokens)(agent, { storage: ccStorage, force: true, allowPrivateIp });
+                  await (0, import_oauth.ensureClientCredentialsTokens)(agent, {
+                    storage: ccStorage,
+                    force: true,
+                    allowPrivateIp,
+                    fetch: transport?.fetchFn
+                  });
                   const retryAuthToken = agent.oauth_tokens?.access_token ?? authToken;
                   try {
                     return await (0, import_mcp_tasks2.callMCPToolWithTasks)(
@@ -273,15 +276,16 @@ class ProtocolClient {
                         ...signal && { signal },
                         ...transport?.requestTimeoutMs !== void 0 && {
                           requestTimeoutMs: transport.requestTimeoutMs
-                        }
+                        },
+                        ...transport?.fetchFn && { fetchFn: transport.fetchFn }
                       }
                     );
                   } catch (retryErr) {
-                    await rethrowAsNeedsAuthorization(retryErr, agent.agent_uri);
+                    await rethrowAsNeedsAuthorization(retryErr, agent.agent_uri, transport?.fetchFn);
                     throw retryErr;
                   }
                 }
-                await rethrowAsNeedsAuthorization(err, agent.agent_uri);
+                await rethrowAsNeedsAuthorization(err, agent.agent_uri, transport?.fetchFn);
                 throw err;
               }
             } else if (agent.protocol === "a2a") {
@@ -297,13 +301,19 @@ class ProtocolClient {
                   signingContext,
                   session,
                   signal,
-                  transport?.requestTimeoutMs
+                  transport?.requestTimeoutMs,
+                  transport?.fetchFn
                 );
               } catch (err) {
                 if (agent.oauth_client_credentials && (0, import_errors.is401Error)(err)) {
                   const ccStorage = (0, import_oauth.getAgentStorage)(agent);
                   const allowPrivateIp = (0, import_net.isLikelyPrivateUrl)(agent.agent_uri);
-                  await (0, import_oauth.ensureClientCredentialsTokens)(agent, { storage: ccStorage, force: true, allowPrivateIp });
+                  await (0, import_oauth.ensureClientCredentialsTokens)(agent, {
+                    storage: ccStorage,
+                    force: true,
+                    allowPrivateIp,
+                    fetch: transport?.fetchFn
+                  });
                   const retryAuthToken = agent.oauth_tokens?.access_token ?? authToken;
                   try {
                     return await (0, import_a2a3.callA2ATool)(
@@ -317,14 +327,15 @@ class ProtocolClient {
                       signingContext,
                       session,
                       signal,
-                      transport?.requestTimeoutMs
+                      transport?.requestTimeoutMs,
+                      transport?.fetchFn
                     );
                   } catch (retryErr) {
-                    await rethrowAsNeedsAuthorization(retryErr, agent.agent_uri);
+                    await rethrowAsNeedsAuthorization(retryErr, agent.agent_uri, transport?.fetchFn);
                     throw retryErr;
                   }
                 }
-                await rethrowAsNeedsAuthorization(err, agent.agent_uri);
+                await rethrowAsNeedsAuthorization(err, agent.agent_uri, transport?.fetchFn);
                 throw err;
               }
             } else {
@@ -336,11 +347,11 @@ class ProtocolClient {
     );
   }
 }
-async function rethrowAsNeedsAuthorization(err, agentUrl) {
+async function rethrowAsNeedsAuthorization(err, agentUrl, fetchFn) {
   if (err instanceof import_oauth.NeedsAuthorizationError) throw err;
   if (!(0, import_errors.is401Error)(err)) return;
   const allowPrivateIp = (0, import_net.isLikelyPrivateUrl)(agentUrl);
-  const requirements = await (0, import_oauth.discoverAuthorizationRequirements)(agentUrl, { allowPrivateIp });
+  const requirements = await (0, import_oauth.discoverAuthorizationRequirements)(agentUrl, { allowPrivateIp, fetchFn });
   if (requirements) {
     throw new import_oauth.NeedsAuthorizationError(requirements);
   }
@@ -358,7 +369,8 @@ const createMCPClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
         debugLogs,
         headers,
         {
-          ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs }
+          ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
+          ...transport?.fetchFn && { fetchFn: transport.fetchFn }
         }
       )
     )
@@ -380,7 +392,8 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
         void 0,
         void 0,
         void 0,
-        transport?.requestTimeoutMs
+        transport?.requestTimeoutMs,
+        transport?.fetchFn
       )
     )
   };