@adcp/sdk 16.4.0 → 16.6.0

package/dist/lib/protocols/index.js

@@ -54,6 +54,7 @@ __export(protocols_exports, {
   wrapFetchWithTransportDiagnostics: () => import_transportDiagnostics2.wrapFetchWithTransportDiagnostics
 });
 module.exports = __toCommonJS(protocols_exports);
+var import_mcp_connection_policy = require('./mcp-connection-policy.js');
 var import_errors = require('../errors/index.js');
 var import_mcp = require('./mcp.js');
 var import_mcp2 = require('./mcp.js');
@@ -148,6 +149,7 @@ function applyVersionEnvelope(args, envelope) {
 }
 let warnedLegacyTransportFetch = false;
 function normalizeTransportOptions(transport) {
+  (0, import_mcp_connection_policy.assertMCPConnectionPolicy)(transport);
   if (!transport?.fetchFn) return transport;
   if (transport.trustedFetchFn && transport.trustedFetchFn !== transport.fetchFn) {
     throw new TypeError("TransportOptions cannot set different fetchFn and trustedFetchFn implementations");
@@ -226,6 +228,12 @@ class ProtocolClient {
    * @param options - Optional call-level configuration. See {@link CallToolOptions}.
    */
   static async callTool(agent, toolName, args, options = {}) {
+    return (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
+      normalizeTransportOptions(options.transport),
+      () => ProtocolClient.callToolWithConnectionPolicy(agent, toolName, args, options)
+    );
+  }
+  static async callToolWithConnectionPolicy(agent, toolName, args, options = {}) {
     const {
       debugLogs = [],
       webhookUrl,
@@ -307,7 +315,9 @@ class ProtocolClient {
                   ...versionEnvelopeMode !== "auto" && { versionEnvelope: versionEnvelopeMode },
                   transport,
                   signal,
-                  ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
+                  ...transport?.requestTimeoutMs !== void 0 && {
+                    requestTimeoutMs: transport.requestTimeoutMs
+                  },
                   onTransportActivity,
                   transportActivityContext
                 })
@@ -321,7 +331,7 @@ class ProtocolClient {
                   allowHttp: (0, import_net.isLikelyPrivateUrl)(agent.agent_uri)
                 });
                 try {
-                  return await (0, import_mcp3.callMCPToolWithOAuth)({
+                  return await (0, import_mcp3.callMCPToolWithOAuthInContext)({
                     agentUrl: agent.agent_uri,
                     toolName,
                     args: preparedCall.args,
@@ -347,7 +357,7 @@ class ProtocolClient {
                 }
               }
               try {
-                return await (0, import_mcp_tasks2.callMCPToolWithTasks)(
+                return await (0, import_mcp_tasks2.callMCPToolWithTasksInContext)(
                   agent.agent_uri,
                   toolName,
                   preparedCall.args,
@@ -377,7 +387,7 @@ class ProtocolClient {
                   });
                   const retryAuthToken = agent.oauth_tokens?.access_token ?? authToken;
                   try {
-                    return await (0, import_mcp_tasks2.callMCPToolWithTasks)(
+                    return await (0, import_mcp_tasks2.callMCPToolWithTasksInContext)(
                       agent.agent_uri,
                       toolName,
                       preparedCall.args,
@@ -518,20 +528,23 @@ const createMCPClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, args, debugLogs) => (0, import_responseSizeLimit2.withResponseSizeLimit)(
-      transport?.maxResponseBytes,
-      () => (0, import_mcp_tasks2.callMCPToolWithTasks)(
-        agentUrl,
-        toolName,
-        applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(args, versionEnvelope), args),
-        authToken,
-        debugLogs,
-        headers,
-        {
-          ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
-          ...transport?.trustedFetchFn && { fetchFn: transport.trustedFetchFn },
-          ...transport?.allowPrivateIp !== void 0 && { allowPrivateIp: transport.allowPrivateIp }
-        }
+    callTool: async (toolName, args, debugLogs) => (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
+      transport,
+      () => (0, import_responseSizeLimit2.withResponseSizeLimit)(
+        transport?.maxResponseBytes,
+        () => (0, import_mcp_tasks2.callMCPToolWithTasksInContext)(
+          agentUrl,
+          toolName,
+          applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(args, versionEnvelope), args),
+          authToken,
+          debugLogs,
+          headers,
+          {
+            ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
+            ...transport?.trustedFetchFn && { fetchFn: transport.trustedFetchFn },
+            ...transport?.allowPrivateIp !== void 0 && { allowPrivateIp: transport.allowPrivateIp }
+          }
+        )
       )
     )
   };
@@ -540,23 +553,26 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, parameters, debugLogs) => (0, import_responseSizeLimit2.withResponseSizeLimit)(
-      transport?.maxResponseBytes,
-      () => (0, import_a2a3.callA2ATool)(
-        agentUrl,
-        toolName,
-        applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(parameters, versionEnvelope), parameters),
-        authToken,
-        debugLogs,
-        void 0,
-        headers,
-        void 0,
-        void 0,
-        void 0,
-        transport?.requestTimeoutMs,
-        transport?.trustedFetchFn,
-        transport?.allowPrivateIp,
-        transport?.legacyCompat
+    callTool: async (toolName, parameters, debugLogs) => (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
+      transport,
+      () => (0, import_responseSizeLimit2.withResponseSizeLimit)(
+        transport?.maxResponseBytes,
+        () => (0, import_a2a3.callA2ATool)(
+          agentUrl,
+          toolName,
+          applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(parameters, versionEnvelope), parameters),
+          authToken,
+          debugLogs,
+          void 0,
+          headers,
+          void 0,
+          void 0,
+          void 0,
+          transport?.requestTimeoutMs,
+          transport?.trustedFetchFn,
+          transport?.allowPrivateIp,
+          transport?.legacyCompat
+        )
       )
     )
   };

package/dist/lib/protocols/index.mjs

@@ -3,6 +3,7 @@ import { dirname as __adcpDirname } from "node:path";
 import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
+import { assertMCPConnectionPolicy, withMCPConnectionPolicy } from "./mcp-connection-policy.mjs";
 import { VersionUnsupportedError } from "../errors/index.mjs";
 import {
   callMCPTool,
@@ -42,8 +43,8 @@ import {
   mapMCPTaskStatus,
   serverSupportsTasks
 } from "./mcp-tasks.mjs";
-import { callMCPToolWithTasks as callMCPToolWithTasks2, callMCPToolWithClient } from "./mcp-tasks.mjs";
-import { callMCPToolWithOAuth as callMCPToolWithOAuth2 } from "./mcp.mjs";
+import { callMCPToolWithTasksInContext as callMCPToolWithTasks2, callMCPToolWithClient } from "./mcp-tasks.mjs";
+import { callMCPToolWithOAuthInContext as callMCPToolWithOAuth2 } from "./mcp.mjs";
 import { callA2ATool as callA2ATool2 } from "./a2a.mjs";
 import { getAuthToken } from "../auth/index.mjs";
 import {
@@ -126,6 +127,7 @@ function applyVersionEnvelope(args, envelope) {
 }
 let warnedLegacyTransportFetch = false;
 function normalizeTransportOptions(transport) {
+  assertMCPConnectionPolicy(transport);
   if (!transport?.fetchFn) return transport;
   if (transport.trustedFetchFn && transport.trustedFetchFn !== transport.fetchFn) {
     throw new TypeError("TransportOptions cannot set different fetchFn and trustedFetchFn implementations");
@@ -204,6 +206,12 @@ class ProtocolClient {
    * @param options - Optional call-level configuration. See {@link CallToolOptions}.
    */
   static async callTool(agent, toolName, args, options = {}) {
+    return withMCPConnectionPolicy(
+      normalizeTransportOptions(options.transport),
+      () => ProtocolClient.callToolWithConnectionPolicy(agent, toolName, args, options)
+    );
+  }
+  static async callToolWithConnectionPolicy(agent, toolName, args, options = {}) {
     const {
       debugLogs = [],
       webhookUrl,
@@ -285,7 +293,9 @@ class ProtocolClient {
                   ...versionEnvelopeMode !== "auto" && { versionEnvelope: versionEnvelopeMode },
                   transport,
                   signal,
-                  ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
+                  ...transport?.requestTimeoutMs !== void 0 && {
+                    requestTimeoutMs: transport.requestTimeoutMs
+                  },
                   onTransportActivity,
                   transportActivityContext
                 })
@@ -496,20 +506,23 @@ const createMCPClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, args, debugLogs) => withResponseSizeLimit(
-      transport?.maxResponseBytes,
-      () => callMCPToolWithTasks2(
-        agentUrl,
-        toolName,
-        applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(args, versionEnvelope), args),
-        authToken,
-        debugLogs,
-        headers,
-        {
-          ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
-          ...transport?.trustedFetchFn && { fetchFn: transport.trustedFetchFn },
-          ...transport?.allowPrivateIp !== void 0 && { allowPrivateIp: transport.allowPrivateIp }
-        }
+    callTool: async (toolName, args, debugLogs) => withMCPConnectionPolicy(
+      transport,
+      () => withResponseSizeLimit(
+        transport?.maxResponseBytes,
+        () => callMCPToolWithTasks2(
+          agentUrl,
+          toolName,
+          applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(args, versionEnvelope), args),
+          authToken,
+          debugLogs,
+          headers,
+          {
+            ...transport?.requestTimeoutMs !== void 0 && { requestTimeoutMs: transport.requestTimeoutMs },
+            ...transport?.trustedFetchFn && { fetchFn: transport.trustedFetchFn },
+            ...transport?.allowPrivateIp !== void 0 && { allowPrivateIp: transport.allowPrivateIp }
+          }
+        )
       )
     )
   };
@@ -518,23 +531,26 @@ const createA2AClient = (agentUrl, authToken, headers, serverVersion, adcpVersio
   transport = normalizeTransportOptions(transport);
   const versionEnvelope = buildVersionEnvelopeForMode(versionEnvelopeMode, adcpVersion, serverVersion);
   return {
-    callTool: (toolName, parameters, debugLogs) => withResponseSizeLimit(
-      transport?.maxResponseBytes,
-      () => callA2ATool2(
-        agentUrl,
-        toolName,
-        applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(parameters, versionEnvelope), parameters),
-        authToken,
-        debugLogs,
-        void 0,
-        headers,
-        void 0,
-        void 0,
-        void 0,
-        transport?.requestTimeoutMs,
-        transport?.trustedFetchFn,
-        transport?.allowPrivateIp,
-        transport?.legacyCompat
+    callTool: async (toolName, parameters, debugLogs) => withMCPConnectionPolicy(
+      transport,
+      () => withResponseSizeLimit(
+        transport?.maxResponseBytes,
+        () => callA2ATool2(
+          agentUrl,
+          toolName,
+          applyPublishedSchemaCompatibility(toolName, applyVersionEnvelope(parameters, versionEnvelope), parameters),
+          authToken,
+          debugLogs,
+          void 0,
+          headers,
+          void 0,
+          void 0,
+          void 0,
+          transport?.requestTimeoutMs,
+          transport?.trustedFetchFn,
+          transport?.allowPrivateIp,
+          transport?.legacyCompat
+        )
       )
     )
   };

package/dist/lib/protocols/mcp-connection-policy.d.mts

@@ -0,0 +1,12 @@
+/** Local connection ownership; these fields must never be serialized on the wire. */
+export interface MCPConnectionPolicy {
+    connectionPartition?: string;
+    connectionReuse?: 'process';
+}
+export declare function assertMCPConnectionPolicy(policy?: MCPConnectionPolicy): void;
+/** Install a detached policy, including an empty one, at each public call boundary. */
+export declare function withMCPConnectionPolicy<T>(policy: MCPConnectionPolicy | undefined, run: () => T): T;
+/** Opaque process-local partition used only by internal connection and capability keys. */
+export declare function mcpConnectionPartitionKey(partition?: string): string | undefined;
+/** Scopes own their sessions; unscoped sharing requires explicit caller identity or opt-in. */
+export declare function shouldReuseMCPConnection(injectedFetch?: boolean): boolean;

package/dist/lib/protocols/mcp-connection-policy.d.ts

@@ -0,0 +1,12 @@
+/** Local connection ownership; these fields must never be serialized on the wire. */
+export interface MCPConnectionPolicy {
+    connectionPartition?: string;
+    connectionReuse?: 'process';
+}
+export declare function assertMCPConnectionPolicy(policy?: MCPConnectionPolicy): void;
+/** Install a detached policy, including an empty one, at each public call boundary. */
+export declare function withMCPConnectionPolicy<T>(policy: MCPConnectionPolicy | undefined, run: () => T): T;
+/** Opaque process-local partition used only by internal connection and capability keys. */
+export declare function mcpConnectionPartitionKey(partition?: string): string | undefined;
+/** Scopes own their sessions; unscoped sharing requires explicit caller identity or opt-in. */
+export declare function shouldReuseMCPConnection(injectedFetch?: boolean): boolean;

package/dist/lib/protocols/mcp-connection-policy.js

@@ -0,0 +1,67 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var mcp_connection_policy_exports = {};
+__export(mcp_connection_policy_exports, {
+  assertMCPConnectionPolicy: () => assertMCPConnectionPolicy,
+  mcpConnectionPartitionKey: () => mcpConnectionPartitionKey,
+  shouldReuseMCPConnection: () => shouldReuseMCPConnection,
+  withMCPConnectionPolicy: () => withMCPConnectionPolicy
+});
+module.exports = __toCommonJS(mcp_connection_policy_exports);
+var import_node_crypto = require("node:crypto");
+var import_global_async_local_storage = require('../utils/global-async-local-storage.js');
+var import_mcp_scope = require('./mcp-scope.js');
+const partitionSalt = (0, import_node_crypto.randomBytes)(32);
+const policyStorage = (0, import_global_async_local_storage.globalAsyncLocalStorage)("mcpConnectionPolicy");
+function assertMCPConnectionPolicy(policy) {
+  if (policy?.connectionPartition !== void 0 && (typeof policy.connectionPartition !== "string" || policy.connectionPartition.trim().length === 0)) {
+    throw new TypeError("transport.connectionPartition must be a nonempty string");
+  }
+  if (policy?.connectionReuse !== void 0 && policy.connectionReuse !== "process") {
+    throw new TypeError('transport.connectionReuse must be "process" when configured');
+  }
+}
+function withMCPConnectionPolicy(policy, run) {
+  assertMCPConnectionPolicy(policy);
+  return policyStorage.run(
+    policy && Object.freeze({
+      connectionPartition: policy.connectionPartition,
+      connectionReuse: policy.connectionReuse
+    }),
+    run
+  );
+}
+function mcpConnectionPartitionKey(partition) {
+  if (arguments.length === 0) partition = policyStorage.getStore()?.connectionPartition;
+  if (partition === void 0) return void 0;
+  return (0, import_node_crypto.createHash)("sha256").update(partitionSalt).update(partition).digest("hex");
+}
+function shouldReuseMCPConnection(injectedFetch = false) {
+  if ((0, import_mcp_scope.currentMCPConnectionScopeKey)() !== void 0) return true;
+  if (injectedFetch) return false;
+  const policy = policyStorage.getStore();
+  return policy?.connectionPartition !== void 0 || policy?.connectionReuse === "process";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertMCPConnectionPolicy,
+  mcpConnectionPartitionKey,
+  shouldReuseMCPConnection,
+  withMCPConnectionPolicy
+});

package/dist/lib/protocols/mcp-connection-policy.mjs

@@ -0,0 +1,45 @@
+import { fileURLToPath as __adcpFileURLToPath } from "node:url";
+import { dirname as __adcpDirname } from "node:path";
+import { createRequire as __adcpCreateRequire } from "node:module";
+const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
+const require2 = __adcpCreateRequire(import.meta.url);
+import { createHash, randomBytes } from "node:crypto";
+import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
+import { currentMCPConnectionScopeKey } from "./mcp-scope.mjs";
+const partitionSalt = randomBytes(32);
+const policyStorage = globalAsyncLocalStorage("mcpConnectionPolicy");
+function assertMCPConnectionPolicy(policy) {
+  if (policy?.connectionPartition !== void 0 && (typeof policy.connectionPartition !== "string" || policy.connectionPartition.trim().length === 0)) {
+    throw new TypeError("transport.connectionPartition must be a nonempty string");
+  }
+  if (policy?.connectionReuse !== void 0 && policy.connectionReuse !== "process") {
+    throw new TypeError('transport.connectionReuse must be "process" when configured');
+  }
+}
+function withMCPConnectionPolicy(policy, run) {
+  assertMCPConnectionPolicy(policy);
+  return policyStorage.run(
+    policy && Object.freeze({
+      connectionPartition: policy.connectionPartition,
+      connectionReuse: policy.connectionReuse
+    }),
+    run
+  );
+}
+function mcpConnectionPartitionKey(partition) {
+  if (arguments.length === 0) partition = policyStorage.getStore()?.connectionPartition;
+  if (partition === void 0) return void 0;
+  return createHash("sha256").update(partitionSalt).update(partition).digest("hex");
+}
+function shouldReuseMCPConnection(injectedFetch = false) {
+  if (currentMCPConnectionScopeKey() !== void 0) return true;
+  if (injectedFetch) return false;
+  const policy = policyStorage.getStore();
+  return policy?.connectionPartition !== void 0 || policy?.connectionReuse === "process";
+}
+export {
+  assertMCPConnectionPolicy,
+  mcpConnectionPartitionKey,
+  shouldReuseMCPConnection,
+  withMCPConnectionPolicy
+};

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

@@ -41,6 +41,8 @@ export interface ModernMCPConnectionOptions {
     /** Use the v2 SDK's negotiated legacy client instead of handing off to v1. */
     handleLegacy?: boolean;
 }
+/** `Retry-After` recorded on an MCP connect error by {@link withRetryAfter}, if any. */
+export declare function retryAfterOf(error: unknown): string | undefined;
 /**
  * Try a tool call using the MCP 2026-07-28 protocol era.
  *

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

@@ -41,6 +41,8 @@ export interface ModernMCPConnectionOptions {
     /** Use the v2 SDK's negotiated legacy client instead of handing off to v1. */
     handleLegacy?: boolean;
 }
+/** `Retry-After` recorded on an MCP connect error by {@link withRetryAfter}, if any. */
+export declare function retryAfterOf(error: unknown): string | undefined;
 /**
  * Try a tool call using the MCP 2026-07-28 protocol era.
  *

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

@@ -20,10 +20,12 @@ var mcp_modern_exports = {};
 __export(mcp_modern_exports, {
   closeModernMCPConnections: () => closeModernMCPConnections,
   probeModernMCPConnection: () => probeModernMCPConnection,
+  retryAfterOf: () => retryAfterOf,
   tryCallModernMCPTool: () => tryCallModernMCPTool,
   tryListModernMCPTools: () => tryListModernMCPTools
 });
 module.exports = __toCommonJS(mcp_modern_exports);
+var import_mcp_connection_policy = require('./mcp-connection-policy.js');
 var import_client = require("@modelcontextprotocol/client");
 var import_node_crypto = require("node:crypto");
 var import_auth = require('../auth/index.js');
@@ -103,6 +105,8 @@ function connectionCacheKey(agentUrl, headers, signingCacheKey, authProvider, fe
   if (handleLegacy !== void 0) parts.push(`handle-legacy:${handleLegacy}`);
   if (allowPrivateIp !== void 0) parts.push(`allow-private-ip:${allowPrivateIp}`);
   parts.push((0, import_responseSizeLimit.responseSizeCapCacheKey)());
+  const partitionKey = (0, import_mcp_connection_policy.mcpConnectionPartitionKey)();
+  if (partitionKey) parts.push(`partition:${partitionKey}`);
   const scopeKey = (0, import_mcp_scope.currentMCPConnectionScopeKey)();
   if (scopeKey) parts.push(scopeKey);
   return parts.join("::");
@@ -245,9 +249,15 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     getCapability: options.signingContext.getCapability,
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
+  const transportFetch = (0, import_rawResponseCapture.wrapFetchWithCapture)(withPerRequestTraceHeaders(signedFetch));
+  let throttleRetryAfter;
   const transport = new import_client.StreamableHTTPClientTransport(new URL(options.agentUrl), {
     requestInit: { headers: (0, import_mcp_call_context.splitConnectionHeaders)(authHeaders).identity, redirect: "manual" },
-    fetch: (0, import_rawResponseCapture.wrapFetchWithCapture)(withPerRequestTraceHeaders(signedFetch)),
+    fetch: async (input, init) => {
+      const response = await transportFetch(input, init);
+      throttleRetryAfter = response.status === 429 || response.status === 503 ? response.headers.get("retry-after") ?? void 0 : void 0;
+      return response;
+    },
     ...options.authProvider && {
       authProvider: options.authProvider
     }
@@ -272,7 +282,7 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     if (prior && !skipProbe) clientsUsingCachedDiscovery.add(client);
     if (!prior) {
       const discover = client.getDiscoverResult();
-      if (generation === connectionGeneration) {
+      if (generation === connectionGeneration && useCachedDiscovery) {
         if (client.getProtocolEra() === "modern" && discover) cacheModernDiscovery(cacheKey, discover);
         else modernDiscoveries.delete(cacheKey);
       }
@@ -290,8 +300,22 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     if (isNegotiationAuthFailure(error) && !skipProbe && presentedStaticCredential(authHeaders, options.authProvider)) {
       return createNegotiatedClient(cacheKey, options, authHeaders, useCachedDiscovery, true);
     }
-    throw error;
+    throw withRetryAfter(error, throttleRetryAfter);
+  }
+}
+function withRetryAfter(error, retryAfter) {
+  if (retryAfter === void 0 || !error || typeof error !== "object") return error;
+  const status = httpStatusOf(error);
+  if (status !== 429 && status !== 503) return error;
+  try {
+    Object.defineProperty(error, "retryAfter", { value: retryAfter, enumerable: false, configurable: true });
+  } catch {
   }
+  return error;
+}
+function retryAfterOf(error) {
+  const value = error && typeof error === "object" ? error.retryAfter : void 0;
+  return typeof value === "string" ? value : void 0;
 }
 async function getOrCreateModernConnection(cacheKey, options, authHeaders) {
   for (let attempt = 0; ; attempt++) {
@@ -311,12 +335,12 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   const promise = createNegotiatedClient(cacheKey, options, authHeaders).then(async (client) => {
     if ((client.getProtocolEra() === "modern" || options.handleLegacy === true) && generation === connectionGeneration) {
       modernConnections.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("modern", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("modern", cacheKey, async (terminateSession) => {
         if (modernConnections.get(cacheKey) !== client) return;
         modernConnections.delete(cacheKey);
         legacyConnectionExpiresAt.delete(cacheKey);
         modernDiscoveries.delete(cacheKey);
-        await closeModernClient(client);
+        await closeModernClient(client, terminateSession);
       });
       if (client.getProtocolEra() === "legacy") {
         legacyConnectionExpiresAt.set(cacheKey, Date.now() + LEGACY_CLASSIFICATION_TTL_MS);
@@ -338,7 +362,10 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   return promise;
 }
 async function retireFailedConnection(cacheKey, client, error) {
-  if ((0, import_abort.isAbortOrTimeoutError)(error)) return;
+  if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+    (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+    return;
+  }
   if (modernConnections.get(cacheKey) === client) {
     modernConnections.delete(cacheKey);
     legacyConnectionExpiresAt.delete(cacheKey);
@@ -369,11 +396,11 @@ async function attemptModernCall(options, toolName, args) {
     options.allowPrivateIp
   );
   if (isKnownLegacy(cacheKey)) return { handled: false };
-  const oneShot = options.fetchFn !== void 0 && (0, import_mcp_scope.currentMCPConnectionScopeKey)() === void 0;
+  const oneShot = !(0, import_mcp_connection_policy.shouldReuseMCPConnection)(options.fetchFn !== void 0);
   let client;
   let callSucceeded = false;
   try {
-    client = oneShot ? await createNegotiatedClient(cacheKey, options, authHeaders) : await getOrCreateModernConnection(cacheKey, options, authHeaders);
+    client = oneShot ? await createNegotiatedClient(cacheKey, options, authHeaders, false) : await getOrCreateModernConnection(cacheKey, options, authHeaders);
   } catch (error) {
     const status = httpStatusOf(error);
     if (status === 404 || status === 405) {
@@ -506,7 +533,8 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.handleLegacy,
     options.allowPrivateIp
   );
-  const scoped = (0, import_mcp_scope.currentMCPConnectionScopeKey)() !== void 0;
+  const scoped = (0, import_mcp_connection_policy.shouldReuseMCPConnection)(options.fetchFn !== void 0);
+  if (isKnownLegacy(cacheKey)) return { connected: false };
   let client;
   return (0, import_mcp_call_context.runWithMCPCallContext)(
     callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
@@ -556,7 +584,7 @@ async function tryListModernMCPTools(agentUrl, authToken, customHeaders, options
     options.handleLegacy,
     options.allowPrivateIp
   );
-  const scoped = (0, import_mcp_scope.currentMCPConnectionScopeKey)() !== void 0;
+  const scoped = (0, import_mcp_connection_policy.shouldReuseMCPConnection)(options.fetchFn !== void 0);
   if (scoped && isKnownLegacy(cacheKey)) return { handled: false };
   let client;
   const sharedClients = /* @__PURE__ */ new WeakSet();
@@ -591,7 +619,7 @@ async function tryListModernMCPTools(agentUrl, authToken, customHeaders, options
     async () => {
       try {
         client = await acquire(
-          () => scoped ? getOrCreateModernConnection(cacheKey, connectionOptions, authHeaders) : createNegotiatedClient(cacheKey, connectionOptions, authHeaders)
+          () => scoped ? getOrCreateModernConnection(cacheKey, connectionOptions, authHeaders) : createNegotiatedClient(cacheKey, connectionOptions, authHeaders, false)
         );
         return await listTools(client);
       } catch (error) {
@@ -647,6 +675,7 @@ async function closeModernMCPConnections() {
 0 && (module.exports = {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 });