@adcp/sdk 15.4.0 → 15.5.0

package/dist/lib/protocols/mcp-modern.mjs

@@ -20,6 +20,20 @@ import {
   registerMCPConnectionScopePending
 } from "./mcp-scope.mjs";
 import { terminateSessionBestEffort } from "./session-termination.mjs";
+import {
+  applyMCPCallHeaders,
+  isCorrelationHeader,
+  withAmbientIdentityHeaders,
+  closeWhenIdle,
+  linkedCallSignal,
+  joinPendingConnection,
+  RETRY_CONNECT,
+  requestTimeoutFor,
+  runCallPhase,
+  runWithMCPCallContext,
+  splitConnectionHeaders,
+  trackConnectionUse
+} from "./mcp-call-context.mjs";
 import { buildAgentSigningFetch, signingContextStorage } from "../signing/client.mjs";
 import {
   isAbortOrTimeoutError,
@@ -44,10 +58,8 @@ const LEGACY_CLASSIFICATION_TTL_MS = 5 * 60 * 1e3;
 const MODERN_DISCOVERY_TTL_MS = 5 * 60 * 1e3;
 const modernOAuthProviderIds = /* @__PURE__ */ new WeakMap();
 const modernFetchFnIds = /* @__PURE__ */ new WeakMap();
-const modernSignalIds = /* @__PURE__ */ new WeakMap();
 let nextModernOAuthProviderId = 0;
 let nextModernFetchFnId = 0;
-let nextModernSignalId = 0;
 let connectionGeneration = 0;
 async function closeModernClient(client, terminateSession = true) {
   const transport = modernTransports.get(client);
@@ -67,7 +79,7 @@ function buildAuthHeaders(authToken, customHeaders, authProvider) {
       return key !== "authorization" && key !== "x-adcp-auth";
     })
   ) : customHeaders;
-  return createMCPRequestHeaders(filteredHeaders, authProvider ? void 0 : authToken);
+  return withAmbientIdentityHeaders(createMCPRequestHeaders(filteredHeaders, authProvider ? void 0 : authToken));
 }
 function oauthProviderCacheKey(provider) {
   if (!provider) return void 0;
@@ -87,33 +99,26 @@ function fetchFnCacheKey(fetchFn) {
   }
   return key;
 }
-function signalCacheKey(signal) {
-  if (!signal) return void 0;
-  let key = modernSignalIds.get(signal);
-  if (!key) {
-    key = `signal:${++nextModernSignalId}`;
-    modernSignalIds.set(signal, key);
-  }
-  return key;
-}
-function connectionCacheKey(agentUrl, headers, signingCacheKey, authProvider, fetchFn, signal, requestTimeoutMs, handleLegacy, allowPrivateIp) {
-  const normalizedHeaders = Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]).sort(([left], [right]) => left.localeCompare(right));
+function connectionCacheKey(agentUrl, headers, signingCacheKey, authProvider, fetchFn, handleLegacy, allowPrivateIp) {
+  const normalizedHeaders = Object.entries(splitConnectionHeaders(headers).identity).map(([key, value]) => [key.toLowerCase(), value]).sort(([left], [right]) => left.localeCompare(right));
   const parts = [agentUrl, `headers:${cacheDisambiguator(JSON.stringify(normalizedHeaders))}`];
   if (signingCacheKey) parts.push(signingCacheKey);
   const providerKey = oauthProviderCacheKey(authProvider);
   if (providerKey) parts.push(providerKey);
   const fetchKey = fetchFnCacheKey(fetchFn);
   if (fetchKey) parts.push(fetchKey);
-  const signalKey = signalCacheKey(signal);
-  if (signalKey) parts.push(signalKey);
-  if (requestTimeoutMs !== void 0) parts.push(`timeout:${requestTimeoutMs}`);
   if (handleLegacy !== void 0) parts.push(`handle-legacy:${handleLegacy}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
   const scopeKey = currentMCPConnectionScopeKey();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");
 }
-function isKnownLegacy(cacheKey) {
+function classificationKey(cacheKey) {
+  const marker = cacheKey.lastIndexOf("::scope:");
+  return marker >= 0 ? cacheKey.slice(0, marker) : cacheKey;
+}
+function isKnownLegacy(connectionKey) {
+  const cacheKey = classificationKey(connectionKey);
   const classifiedAt = knownLegacyConnections.get(cacheKey);
   if (classifiedAt === void 0) return false;
   if (Date.now() - classifiedAt > LEGACY_CLASSIFICATION_TTL_MS) {
@@ -124,7 +129,9 @@ function isKnownLegacy(cacheKey) {
   knownLegacyConnections.set(cacheKey, classifiedAt);
   return true;
 }
-function markKnownLegacy(cacheKey) {
+function markKnownLegacy(connectionKey) {
+  const cacheKey = classificationKey(connectionKey);
+  modernDiscoveries.delete(connectionKey);
   modernDiscoveries.delete(cacheKey);
   knownLegacyConnections.delete(cacheKey);
   knownLegacyConnections.set(cacheKey, Date.now());
@@ -146,6 +153,7 @@ function getCachedModernDiscovery(cacheKey) {
   return { kind: "modern", discover: cached.discover };
 }
 function cacheModernDiscovery(cacheKey, discover) {
+  knownLegacyConnections.delete(classificationKey(cacheKey));
   modernDiscoveries.delete(cacheKey);
   modernDiscoveries.set(cacheKey, {
     discover,
@@ -172,8 +180,12 @@ function withPerRequestTraceHeaders(fetchImpl) {
   return (input, init) => {
     const headers = new Headers(input instanceof Request ? input.headers : void 0);
     new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
-    for (const [key, value] of Object.entries(injectTraceHeaders())) headers.set(key, value);
-    return fetchImpl(input, { ...init, headers });
+    applyMCPCallHeaders(headers);
+    if (headers.has("traceparent")) return fetchImpl(input, { ...init, headers, ...linkedCallSignal(init) });
+    for (const [key, value] of Object.entries(injectTraceHeaders())) {
+      if (isCorrelationHeader(key) && !headers.has(key)) headers.set(key, value);
+    }
+    return fetchImpl(input, { ...init, headers, ...linkedCallSignal(init) });
   };
 }
 function getCachedConnection(cacheKey) {
@@ -183,7 +195,7 @@ function getCachedConnection(cacheKey) {
     if (legacyExpiry !== void 0 && legacyExpiry <= Date.now()) {
       modernConnections.delete(cacheKey);
       legacyConnectionExpiresAt.delete(cacheKey);
-      void closeModernClient(client).catch(() => {
+      void closeWhenIdle(client, () => closeModernClient(client)).catch(() => {
       });
       return void 0;
     }
@@ -199,7 +211,7 @@ function evictLeastRecentlyUsed() {
   const client = modernConnections.get(oldestKey);
   modernConnections.delete(oldestKey);
   legacyConnectionExpiresAt.delete(oldestKey);
-  if (client) void closeModernClient(client).catch(() => {
+  if (client) void closeWhenIdle(client, () => closeModernClient(client)).catch(() => {
   });
 }
 function isNegotiationAuthFailure(error) {
@@ -214,13 +226,24 @@ function presentedStaticCredential(authHeaders, authProvider) {
 }
 async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedDiscovery = true, skipProbe = false) {
   const generation = connectionGeneration;
-  const requestTimeoutMs = resolveRequestTimeoutMs(options.requestTimeoutMs);
   const clientRequestTimeoutMs = resolveClientRequestTimeoutMs(options.requestTimeoutMs);
   const rawNetworkFetch = createAgentTransportFetch(options.agentUrl, {
     trustedFetchFn: options.fetchFn,
     allowPrivateIp: options.allowPrivateIp
   });
-  const networkFetch = (input, init) => withAbortSignal([init?.signal], requestTimeoutMs, (signal) => rawNetworkFetch(input, { ...init, signal }));
+  const networkFetch = (input, init) => (
+    // `init.signal` already carries the active call's cancellation (linked at the
+    // outermost transport wrapper), including on legacy-era sessions where the
+    // v2 client cancels with a notification and leaves the HTTP stream open.
+    withAbortSignal(
+      [init?.signal],
+      requestTimeoutFor(init),
+      (deadline) => rawNetworkFetch(input, {
+        ...init,
+        signal: init?.signal && deadline ? AbortSignal.any([init.signal, deadline]) : deadline ?? init?.signal
+      })
+    )
+  );
   const diagnosticFetch = wrapFetchWithTransportDiagnostics(wrapFetchWithSizeLimit(networkFetch));
   const signedFetch = options.signingContext ? buildAgentSigningFetch({
     upstream: wrapFetchWithSignedRequestRejection(diagnosticFetch, options.agentUrl),
@@ -229,7 +252,7 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
   const transport = new StreamableHTTPClientTransport(new URL(options.agentUrl), {
-    requestInit: { headers: authHeaders, redirect: "manual" },
+    requestInit: { headers: splitConnectionHeaders(authHeaders).identity, redirect: "manual" },
     fetch: wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch)),
     ...options.authProvider && {
       authProvider: options.authProvider
@@ -277,10 +300,19 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
   }
 }
 async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
-  const cached = getCachedConnection(cacheKey);
-  if (cached) return cached;
-  const pending = pendingModernConnections.get(cacheKey);
-  if (pending) return pending;
+  for (let attempt = 0; ; attempt++) {
+    const cached = getCachedConnection(cacheKey);
+    if (cached) return cached;
+    const pending = pendingModernConnections.get(cacheKey);
+    if (pending) {
+      const joined = await joinPendingConnection(pending, options, attempt);
+      if (joined === RETRY_CONNECT) continue;
+      return joined;
+    }
+    return createSharedModernConnection(cacheKey, options, authHeaders);
+  }
+}
+function createSharedModernConnection(cacheKey, options, authHeaders) {
   const generation = connectionGeneration;
   const promise = createNegotiatedClient(cacheKey, options, authHeaders).then(async (client) => {
     if ((client.getProtocolEra() === "modern" || options.handleLegacy === true) && generation === connectionGeneration) {
@@ -311,6 +343,16 @@ async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
   registerMCPConnectionScopePending(promise);
   return promise;
 }
+async function retireFailedConnection(cacheKey, client, error) {
+  if (isAbortOrTimeoutError(error)) return;
+  if (modernConnections.get(cacheKey) === client) {
+    modernConnections.delete(cacheKey);
+    legacyConnectionExpiresAt.delete(cacheKey);
+  }
+  modernDiscoveries.delete(cacheKey);
+  await closeWhenIdle(client, () => closeModernClient(client, true)).catch(() => {
+  });
+}
 async function callOnModernClient(client, toolName, args, signal, requestTimeoutMs) {
   const resolvedRequestTimeoutMs = resolveClientRequestTimeoutMs(requestTimeoutMs);
   return await client.callTool(
@@ -329,14 +371,11 @@ async function attemptModernCall(options, toolName, args) {
     options.signingContext?.cacheKey,
     options.authProvider,
     options.fetchFn,
-    options.signal,
-    options.requestTimeoutMs,
     options.handleLegacy,
     options.allowPrivateIp
   );
   if (isKnownLegacy(cacheKey)) return { handled: false };
-  const guardedConnection = options.signal !== void 0 || options.requestTimeoutMs !== void 0 || options.fetchFn !== void 0;
-  const oneShot = guardedConnection && currentMCPConnectionScopeKey() === void 0;
+  const oneShot = options.fetchFn !== void 0 && currentMCPConnectionScopeKey() === void 0;
   let client;
   let callSucceeded = false;
   try {
@@ -390,16 +429,21 @@ async function attemptModernCall(options, toolName, args) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
   try {
-    const response = await callOnModernClient(client, toolName, args, options.signal, options.requestTimeoutMs);
+    const response = await trackConnectionUse(
+      client,
+      () => runCallPhase(
+        options.signal,
+        () => callOnModernClient(client, toolName, args, options.signal, options.requestTimeoutMs)
+      )
+    );
     callSucceeded = true;
     return { handled: true, response };
   } catch (error) {
-    modernConnections.delete(cacheKey);
-    legacyConnectionExpiresAt.delete(cacheKey);
-    modernDiscoveries.delete(cacheKey);
-    try {
-      await closeModernClient(client, !isAbortOrTimeoutError(error));
-    } catch {
+    if (oneShot) {
+      await closeModernClient(client, !isAbortOrTimeoutError(error)).catch(() => {
+      });
+    } else {
+      await retireFailedConnection(cacheKey, client, error);
     }
     throw error;
   } finally {
@@ -407,28 +451,39 @@ async function attemptModernCall(options, toolName, args) {
     });
   }
 }
+function callContextFor(options) {
+  const { perRequest } = splitConnectionHeaders(options.customHeaders);
+  const requestTimeoutMs = resolveRequestTimeoutMs(options.requestTimeoutMs);
+  return {
+    ...Object.keys(perRequest).length > 0 && { headers: perRequest },
+    ...requestTimeoutMs !== void 0 && { requestTimeoutMs }
+  };
+}
 async function tryCallModernMCPTool(agentUrl, toolName, args, authToken, debugLogs = [], customHeaders, options = {}) {
   return withSpan(
     "adcp.mcp.negotiate",
     { "adcp.tool": toolName, "http.url": agentUrl },
     () => signingContextStorage.run(
       options.signingContext,
-      () => attemptModernCall(
-        {
-          agentUrl,
-          authToken,
-          customHeaders,
-          debugLogs,
-          signingContext: options.signingContext,
-          authProvider: options.authProvider,
-          signal: options.signal,
-          requestTimeoutMs: options.requestTimeoutMs,
-          fetchFn: options.fetchFn,
-          allowPrivateIp: options.allowPrivateIp,
-          handleLegacy: options.handleLegacy
-        },
-        toolName,
-        args
+      () => runWithMCPCallContext(
+        callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
+        () => attemptModernCall(
+          {
+            agentUrl,
+            authToken,
+            customHeaders,
+            debugLogs,
+            signingContext: options.signingContext,
+            authProvider: options.authProvider,
+            signal: options.signal,
+            requestTimeoutMs: options.requestTimeoutMs,
+            fetchFn: options.fetchFn,
+            allowPrivateIp: options.allowPrivateIp,
+            handleLegacy: options.handleLegacy
+          },
+          toolName,
+          args
+        )
       )
     )
   );
@@ -454,26 +509,34 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.signingContext?.cacheKey,
     options.authProvider,
     options.fetchFn,
-    options.signal,
-    options.requestTimeoutMs,
     options.handleLegacy,
     options.allowPrivateIp
   );
+  const scoped = currentMCPConnectionScopeKey() !== void 0;
   let client;
-  try {
-    client = await createNegotiatedClient(cacheKey, connectionOptions, authHeaders, false);
-    return { connected: true, era: client.getProtocolEra() };
-  } catch (error) {
-    modernDiscoveries.delete(cacheKey);
-    if (is401Error(error) || isAbortOrTimeoutError(error)) throw error;
-    const status = httpStatusOf(error);
-    if (status === 404 || status === 405) return { connected: false };
-    if (isLegacyEraNegotiationFailure(error, status)) return { connected: false };
-    throw error;
-  } finally {
-    if (client) await closeModernClient(client).catch(() => {
-    });
-  }
+  return runWithMCPCallContext(
+    callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
+    async () => {
+      try {
+        client = scoped ? await getOrCreateModernConnection(cacheKey, connectionOptions, authHeaders) : await createNegotiatedClient(cacheKey, connectionOptions, authHeaders, false);
+        const era = client.getProtocolEra();
+        if (scoped && era === "legacy" && connectionOptions.handleLegacy !== true) markKnownLegacy(cacheKey);
+        return { connected: true, era };
+      } catch (error) {
+        modernDiscoveries.delete(cacheKey);
+        if (is401Error(error) || isAbortOrTimeoutError(error)) throw error;
+        const status = httpStatusOf(error);
+        if (status === 404 || status === 405) return { connected: false };
+        if (isLegacyEraNegotiationFailure(error, status)) return { connected: false };
+        throw error;
+      } finally {
+        if (client && !(scoped && modernConnections.get(cacheKey) === client)) {
+          await closeModernClient(client).catch(() => {
+          });
+        }
+      }
+    }
+  );
 }
 async function tryListModernMCPTools(agentUrl, authToken, customHeaders, options = {}) {
   const connectionOptions = {
@@ -486,7 +549,8 @@ async function tryListModernMCPTools(agentUrl, authToken, customHeaders, options
     signal: options.signal,
     requestTimeoutMs: options.requestTimeoutMs,
     fetchFn: options.fetchFn,
-    allowPrivateIp: options.allowPrivateIp
+    allowPrivateIp: options.allowPrivateIp,
+    handleLegacy: options.handleLegacy
   };
   const authHeaders = buildAuthHeaders(authToken, customHeaders, options.authProvider);
   const cacheKey = connectionCacheKey(
@@ -495,50 +559,75 @@ async function tryListModernMCPTools(agentUrl, authToken, customHeaders, options
     options.signingContext?.cacheKey,
     options.authProvider,
     options.fetchFn,
-    options.signal,
-    options.requestTimeoutMs,
     options.handleLegacy,
     options.allowPrivateIp
   );
+  const scoped = currentMCPConnectionScopeKey() !== void 0;
+  if (scoped && isKnownLegacy(cacheKey)) return { handled: false };
   let client;
+  const sharedClients = /* @__PURE__ */ new WeakSet();
+  const acquire = async (create) => {
+    const acquired = await create();
+    if (scoped && modernConnections.get(cacheKey) === acquired) sharedClients.add(acquired);
+    return acquired;
+  };
   const listTools = async (connectedClient) => {
-    if (connectedClient.getProtocolEra() !== "modern") return { handled: false };
+    if (connectedClient.getProtocolEra() !== "modern" && connectionOptions.handleLegacy !== true) {
+      if (scoped) markKnownLegacy(cacheKey);
+      return { handled: false };
+    }
     const resolvedRequestTimeoutMs = resolveClientRequestTimeoutMs(options.requestTimeoutMs);
-    const result = await connectedClient.listTools(
-      options.adcpVersion === void 0 ? void 0 : { _meta: { adcp_version: options.adcpVersion } },
-      {
-        ...options.signal && { signal: options.signal },
-        ...resolvedRequestTimeoutMs !== void 0 && { timeout: resolvedRequestTimeoutMs }
-      }
+    const result = await trackConnectionUse(
+      connectedClient,
+      () => runCallPhase(
+        options.signal,
+        () => connectedClient.listTools(
+          options.adcpVersion === void 0 ? void 0 : { _meta: { adcp_version: options.adcpVersion } },
+          {
+            ...options.signal && { signal: options.signal },
+            ...resolvedRequestTimeoutMs !== void 0 && { timeout: resolvedRequestTimeoutMs }
+          }
+        )
+      )
     );
     return { handled: true, tools: result.tools };
   };
-  try {
-    client = await createNegotiatedClient(cacheKey, connectionOptions, authHeaders);
-    return await listTools(client);
-  } catch (error) {
-    let failure = error;
-    modernDiscoveries.delete(cacheKey);
-    if (!is401Error(failure) && !isAbortOrTimeoutError(failure) && client && clientsUsingCachedDiscovery.has(client)) {
-      await closeModernClient(client, false).catch(() => {
-      });
+  return runWithMCPCallContext(
+    callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
+    async () => {
       try {
-        client = await createNegotiatedClient(cacheKey, connectionOptions, authHeaders, false);
+        client = await acquire(
+          () => scoped ? getOrCreateModernConnection(cacheKey, connectionOptions, authHeaders) : createNegotiatedClient(cacheKey, connectionOptions, authHeaders)
+        );
         return await listTools(client);
-      } catch (retryError) {
-        failure = retryError;
+      } catch (error) {
+        let failure = error;
         modernDiscoveries.delete(cacheKey);
+        if (client && sharedClients.has(client)) {
+          await retireFailedConnection(cacheKey, client, failure);
+        }
+        if (!is401Error(failure) && !isAbortOrTimeoutError(failure) && client && clientsUsingCachedDiscovery.has(client)) {
+          if (!sharedClients.has(client)) await closeModernClient(client, false).catch(() => {
+          });
+          try {
+            client = await acquire(() => createNegotiatedClient(cacheKey, connectionOptions, authHeaders, false));
+            return await listTools(client);
+          } catch (retryError) {
+            failure = retryError;
+            modernDiscoveries.delete(cacheKey);
+          }
+        }
+        if (is401Error(failure) || isAbortOrTimeoutError(failure)) throw failure;
+        const status = httpStatusOf(failure);
+        if (status === 404 || status === 405) return { handled: false };
+        if (isLegacyEraNegotiationFailure(failure, status)) return { handled: false };
+        throw failure;
+      } finally {
+        if (client && !sharedClients.has(client)) await closeModernClient(client).catch(() => {
+        });
       }
     }
-    if (is401Error(failure) || isAbortOrTimeoutError(failure)) throw failure;
-    const status = httpStatusOf(failure);
-    if (status === 404 || status === 405) return { handled: false };
-    if (isLegacyEraNegotiationFailure(failure, status)) return { handled: false };
-    throw failure;
-  } finally {
-    if (client) await closeModernClient(client).catch(() => {
-    });
-  }
+  );
 }
 async function closeModernMCPConnections() {
   connectionGeneration++;

package/dist/lib/protocols/mcp-scope.d.mts

@@ -13,6 +13,21 @@ export declare function closeCurrentMCPConnectionScope(): Promise<boolean>;
  * Isolate connection reuse to one runner/workflow and close it on every exit.
  * Nested callers join the existing scope so a storyboard still gets exactly
  * one reusable session rather than one session per helper layer.
+ *
+ * Every MCP call made inside `fn` — endpoint probe, capability discovery,
+ * `tools/list`, and tool calls — reuses one negotiated session per
+ * (endpoint, credential, tenant headers, signing identity, transport policy).
+ * Per-call correlation headers, `AbortSignal`s and timeouts do not choose the
+ * session. The scope terminates its sessions once, when `fn` settles; pass
+ * `{ isolate: true }` to force a fresh scope even when called from inside one.
+ *
+ * @example
+ * ```ts
+ * await withMCPConnectionScope(async () => {
+ *   await client.syncAccounts(accounts);
+ *   await client.getProducts(brief); // same MCP session, one `initialize`
+ * });
+ * ```
  */
 export declare function withMCPConnectionScope<T>(fn: () => Promise<T>, options?: {
     isolate?: boolean;

package/dist/lib/protocols/mcp-scope.d.ts

@@ -13,6 +13,21 @@ export declare function closeCurrentMCPConnectionScope(): Promise<boolean>;
  * Isolate connection reuse to one runner/workflow and close it on every exit.
  * Nested callers join the existing scope so a storyboard still gets exactly
  * one reusable session rather than one session per helper layer.
+ *
+ * Every MCP call made inside `fn` — endpoint probe, capability discovery,
+ * `tools/list`, and tool calls — reuses one negotiated session per
+ * (endpoint, credential, tenant headers, signing identity, transport policy).
+ * Per-call correlation headers, `AbortSignal`s and timeouts do not choose the
+ * session. The scope terminates its sessions once, when `fn` settles; pass
+ * `{ isolate: true }` to force a fresh scope even when called from inside one.
+ *
+ * @example
+ * ```ts
+ * await withMCPConnectionScope(async () => {
+ *   await client.syncAccounts(accounts);
+ *   await client.getProducts(brief); // same MCP session, one `initialize`
+ * });
+ * ```
  */
 export declare function withMCPConnectionScope<T>(fn: () => Promise<T>, options?: {
     isolate?: boolean;

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

@@ -43,8 +43,10 @@ export interface MCPCallOptions {
     /**
      * Scoped fetch implementation used for MCP requests, OAuth discovery, and token exchange.
      * Direct SDK calls retain isolated one-shot connections. Runner workflows opt into
-     * scoped reuse, where the exact fetch function, cancellation signal, timeout,
-     * credential, and headers all participate in connection identity.
+     * scoped reuse, where the exact fetch function, credential, signing identity,
+     * tenant/routing headers and transport policy participate in connection identity.
+     * The cancellation signal, timeout and correlation headers are per call: they
+     * bound that call's requests and never choose or split the session.
      */
     fetchFn?: typeof fetch;
     /** Explicitly allow private/loopback agent addresses for this connection. */

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

@@ -43,8 +43,10 @@ export interface MCPCallOptions {
     /**
      * Scoped fetch implementation used for MCP requests, OAuth discovery, and token exchange.
      * Direct SDK calls retain isolated one-shot connections. Runner workflows opt into
-     * scoped reuse, where the exact fetch function, cancellation signal, timeout,
-     * credential, and headers all participate in connection identity.
+     * scoped reuse, where the exact fetch function, credential, signing identity,
+     * tenant/routing headers and transport policy participate in connection identity.
+     * The cancellation signal, timeout and correlation headers are per call: they
+     * bound that call's requests and never choose or split the session.
      */
     fetchFn?: typeof fetch;
     /** Explicitly allow private/loopback agent addresses for this connection. */