@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.1

package/dist/lib/errors/index.js

@@ -28,6 +28,7 @@ __export(errors_exports, {
   AccountSetupRequiredError: () => AccountSetupRequiredError,
   ActionNotAllowedError: () => ActionNotAllowedError,
   AgentNotFoundError: () => AgentNotFoundError,
+  AgentRateLimitedError: () => AgentRateLimitedError,
   AuthenticationCredentialsRejectedError: () => AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError: () => AuthenticationRequiredError,
   BuyerSetupError: () => BuyerSetupError,
@@ -474,6 +475,47 @@ class ResponseTooLargeError extends ADCPError {
   contentLengthHeader;
   code = "RESPONSE_TOO_LARGE";
 }
+class AgentRateLimitedError extends ADCPError {
+  constructor(agentUrl, status, retryAfter, cause) {
+    const safeAgentUrl = sanitizeAgentUrlForError(agentUrl);
+    const retryAfterMs = parseRetryAfterMs(retryAfter);
+    const validRetryAfter = retryAfterMs === void 0 ? void 0 : retryAfter?.trim();
+    const retryHint = retryAfterMs === void 0 ? "No usable Retry-After header; back off before retrying." : `Retry-After: ${validRetryAfter} (${Math.ceil(retryAfterMs / 1e3)}s).`;
+    super(
+      `Agent rate limited MCP endpoint discovery: HTTP ${status} from ${safeAgentUrl}. ${retryHint} Discovery stopped at this probe to avoid spending more of the agent's request budget; this does not indicate a wrong agent_uri.`
+    );
+    this.status = status;
+    this.agentUrl = safeAgentUrl;
+    if (retryAfterMs !== void 0) {
+      this.retryAfter = validRetryAfter;
+      this.retryAfterMs = retryAfterMs;
+    }
+    this.details = {
+      agentUrl: safeAgentUrl,
+      status,
+      ...retryAfterMs !== void 0 && { retryAfter: validRetryAfter, retryAfterMs }
+    };
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: cause, enumerable: false, configurable: true });
+    }
+  }
+  status;
+  code = "RATE_LIMITED";
+  /** The probed URL, without credentials, query or fragment. */
+  agentUrl;
+  /** `Retry-After` as the agent sent it. Set only when it is valid delta-seconds or an HTTP-date. */
+  retryAfter;
+  /** Delay from `Retry-After`, in milliseconds. */
+  retryAfterMs;
+}
+function parseRetryAfterMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return void 0;
+  if (/^\d{1,10}$/.test(trimmed)) return Number(trimmed) * 1e3;
+  if (!/^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)) return void 0;
+  const date = Date.parse(trimmed);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
 class ActionNotAllowedError extends ADCPError {
   code = "ACTION_NOT_ALLOWED";
   attemptedAction;
@@ -677,6 +719,7 @@ class PreparedFixturesDeniedError extends ADCPError {
   AccountSetupRequiredError,
   ActionNotAllowedError,
   AgentNotFoundError,
+  AgentRateLimitedError,
   AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
   BuyerSetupError,

package/dist/lib/errors/index.mjs

@@ -413,6 +413,47 @@ class ResponseTooLargeError extends ADCPError {
   contentLengthHeader;
   code = "RESPONSE_TOO_LARGE";
 }
+class AgentRateLimitedError extends ADCPError {
+  constructor(agentUrl, status, retryAfter, cause) {
+    const safeAgentUrl = sanitizeAgentUrlForError(agentUrl);
+    const retryAfterMs = parseRetryAfterMs(retryAfter);
+    const validRetryAfter = retryAfterMs === void 0 ? void 0 : retryAfter?.trim();
+    const retryHint = retryAfterMs === void 0 ? "No usable Retry-After header; back off before retrying." : `Retry-After: ${validRetryAfter} (${Math.ceil(retryAfterMs / 1e3)}s).`;
+    super(
+      `Agent rate limited MCP endpoint discovery: HTTP ${status} from ${safeAgentUrl}. ${retryHint} Discovery stopped at this probe to avoid spending more of the agent's request budget; this does not indicate a wrong agent_uri.`
+    );
+    this.status = status;
+    this.agentUrl = safeAgentUrl;
+    if (retryAfterMs !== void 0) {
+      this.retryAfter = validRetryAfter;
+      this.retryAfterMs = retryAfterMs;
+    }
+    this.details = {
+      agentUrl: safeAgentUrl,
+      status,
+      ...retryAfterMs !== void 0 && { retryAfter: validRetryAfter, retryAfterMs }
+    };
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: cause, enumerable: false, configurable: true });
+    }
+  }
+  status;
+  code = "RATE_LIMITED";
+  /** The probed URL, without credentials, query or fragment. */
+  agentUrl;
+  /** `Retry-After` as the agent sent it. Set only when it is valid delta-seconds or an HTTP-date. */
+  retryAfter;
+  /** Delay from `Retry-After`, in milliseconds. */
+  retryAfterMs;
+}
+function parseRetryAfterMs(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return void 0;
+  if (/^\d{1,10}$/.test(trimmed)) return Number(trimmed) * 1e3;
+  if (!/^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)) return void 0;
+  const date = Date.parse(trimmed);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
 class ActionNotAllowedError extends ADCPError {
   code = "ACTION_NOT_ALLOWED";
   attemptedAction;
@@ -615,6 +656,7 @@ export {
   AccountSetupRequiredError,
   ActionNotAllowedError,
   AgentNotFoundError,
+  AgentRateLimitedError,
   AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
   BuyerSetupError,

package/dist/lib/index.d.mts

@@ -57,7 +57,7 @@ export * from './handlers/types.mjs';
 export type { Storage, AtomicTakeStorage, DeferredTaskStorage, BatchStorage, PatternStorage, AgentCapabilities, ConversationState, DeferredTaskState, StorageConfig, StorageFactory, StorageMiddleware, } from './storage/interfaces.mjs';
 export { MemoryStorage, createMemoryStorage, createMemoryStorageConfig } from './storage/MemoryStorage.mjs';
 export { ADCPError, TaskTimeoutError, MaxClarificationError, DeferredTaskError, TaskAbortedError, AgentNotFoundError, UnsupportedTaskError, ProtocolError, ValidationError as ADCPValidationError, // Rename to avoid conflict
-MissingInputHandlerError, InvalidContextError, ConfigurationError, AuthenticationCredentialsRejectedError, AuthenticationRequiredError, FeatureUnsupportedError, ProtocolFeatureUnsupportedError, UnsupportedBuyingModeError, AccountRequiredError, AccountPendingApprovalError, AccountAmbiguousError, BuyerSetupError, AccountNotFoundError, AccountSetupRequiredError, AccountPaymentRequiredError, AccountNotProvisionedError, SDK_ERROR_TO_PROTOCOL_ERROR_CODE, VersionUnsupportedError, IdempotencyConflictError, IdempotencyExpiredError, ResponseTooLargeError, ActionNotAllowedError, PreparedFixturesDeniedError, adcpErrorToTypedError, getClientPreflightAdcpError, isADCPError, isErrorOfType, extractErrorInfo, is401Error, mapSdkErrorCodeToProtocolErrorCode, } from './errors/index.mjs';
+MissingInputHandlerError, InvalidContextError, ConfigurationError, AuthenticationCredentialsRejectedError, AuthenticationRequiredError, FeatureUnsupportedError, ProtocolFeatureUnsupportedError, UnsupportedBuyingModeError, AccountRequiredError, AccountPendingApprovalError, AccountAmbiguousError, BuyerSetupError, AccountNotFoundError, AccountSetupRequiredError, AccountPaymentRequiredError, AccountNotProvisionedError, SDK_ERROR_TO_PROTOCOL_ERROR_CODE, VersionUnsupportedError, IdempotencyConflictError, IdempotencyExpiredError, ResponseTooLargeError, AgentRateLimitedError, ActionNotAllowedError, PreparedFixturesDeniedError, adcpErrorToTypedError, getClientPreflightAdcpError, isADCPError, isErrorOfType, extractErrorInfo, is401Error, mapSdkErrorCodeToProtocolErrorCode, } from './errors/index.mjs';
 export type { OAuthMetadataInfo, ClientPreflightAdcpErrorInfo, ClientPreflightAdcpErrorRecovery, FeatureUnsupportedErrorOptions, ProtocolFeatureUnsupportedErrorOptions, ActionNotAllowedErrorDetails, ActionNotAllowedReasonValue, ActionNotAllowedAttemptedAction, ActionNotAllowedAvailableAction, ActionNotAllowedRecovery, } from './errors/index.mjs';
 export type { ActionNotAllowedDetails, ActionNotAllowedReason, AvailableActionsResult, AvailableActionsSource, DecomposedUpdateMediaBuy, DecomposedUpdateMediaBuyMutation, LegacyCoarseAction, MediaBuyActionContext, MediaBuyActionId, MediaBuyActionMode, MediaBuyAvailableAction, MediaBuyMutationDirection, MediaBuyMutationScope, MediaBuyUpdateFieldAction, MediaBuyValidAction, ModeMismatchRecovery, PreflightAllowed, PreflightDenial, PreflightDenied, BuyerPropertyPolicy, NormalizedPolicyDomain, ProductPolicyProductLike, ProductPolicyResolvedProperty, ProductPropertyPolicyIdentifier, ProductPropertyPolicyDiagnostic, ProductPropertyPolicyDiagnosticCode, ProductPropertyPolicyDiagnosticSeverity, ProductPropertyPolicyMode, ProductPropertyPolicySelectorBehavior, ProductPropertyPolicyValidationResult, PreflightResult, ResolvedAction, SLAWindow, SlaWindow, StructuredOnlyMediaBuyAction, ResolvedTargetingInput, TargetingInputFor, ValidateProductsAgainstPropertyPolicyOptions, UpdateFieldEntry, UpdateMediaBuyRequestLike, } from './media-buy/index.mjs';
 export { ACTIONS_BY_FIELD, LEGACY_COARSE_ACTIONS, STRUCTURED_ONLY_MEDIA_BUY_ACTIONS, UPDATE_FIELDS_BY_ACTION, applyTargetingInput, hasTargetingClears, resolveTargetingInput, canAddPackages, canCancel, canDecreaseBudget, canExtendFlight, canIncreaseBudget, canPause, canReallocateBudget, canRemoveCreative, canRemovePackages, canReplaceCreative, canResume, canShortenFlight, canUpdateCreativeAssignments, canUpdateFlightDates, canUpdateFrequencyCaps, canUpdatePacing, canUpdateTargeting, decomposeUpdateMediaBuy, findAvailableAction, getActionForMutation, getAvailableActions, getRollupParent, ProductPropertyPolicyError, normalizeDomainForPropertyPolicy, preflightUpdateMediaBuy, recoveryForModeMismatch, validateProductsAgainstPropertyPolicy, } from './media-buy/index.mjs';

package/dist/lib/index.d.ts

@@ -57,7 +57,7 @@ export * from './handlers/types';
 export type { Storage, AtomicTakeStorage, DeferredTaskStorage, BatchStorage, PatternStorage, AgentCapabilities, ConversationState, DeferredTaskState, StorageConfig, StorageFactory, StorageMiddleware, } from './storage/interfaces';
 export { MemoryStorage, createMemoryStorage, createMemoryStorageConfig } from './storage/MemoryStorage';
 export { ADCPError, TaskTimeoutError, MaxClarificationError, DeferredTaskError, TaskAbortedError, AgentNotFoundError, UnsupportedTaskError, ProtocolError, ValidationError as ADCPValidationError, // Rename to avoid conflict
-MissingInputHandlerError, InvalidContextError, ConfigurationError, AuthenticationCredentialsRejectedError, AuthenticationRequiredError, FeatureUnsupportedError, ProtocolFeatureUnsupportedError, UnsupportedBuyingModeError, AccountRequiredError, AccountPendingApprovalError, AccountAmbiguousError, BuyerSetupError, AccountNotFoundError, AccountSetupRequiredError, AccountPaymentRequiredError, AccountNotProvisionedError, SDK_ERROR_TO_PROTOCOL_ERROR_CODE, VersionUnsupportedError, IdempotencyConflictError, IdempotencyExpiredError, ResponseTooLargeError, ActionNotAllowedError, PreparedFixturesDeniedError, adcpErrorToTypedError, getClientPreflightAdcpError, isADCPError, isErrorOfType, extractErrorInfo, is401Error, mapSdkErrorCodeToProtocolErrorCode, } from './errors';
+MissingInputHandlerError, InvalidContextError, ConfigurationError, AuthenticationCredentialsRejectedError, AuthenticationRequiredError, FeatureUnsupportedError, ProtocolFeatureUnsupportedError, UnsupportedBuyingModeError, AccountRequiredError, AccountPendingApprovalError, AccountAmbiguousError, BuyerSetupError, AccountNotFoundError, AccountSetupRequiredError, AccountPaymentRequiredError, AccountNotProvisionedError, SDK_ERROR_TO_PROTOCOL_ERROR_CODE, VersionUnsupportedError, IdempotencyConflictError, IdempotencyExpiredError, ResponseTooLargeError, AgentRateLimitedError, ActionNotAllowedError, PreparedFixturesDeniedError, adcpErrorToTypedError, getClientPreflightAdcpError, isADCPError, isErrorOfType, extractErrorInfo, is401Error, mapSdkErrorCodeToProtocolErrorCode, } from './errors';
 export type { OAuthMetadataInfo, ClientPreflightAdcpErrorInfo, ClientPreflightAdcpErrorRecovery, FeatureUnsupportedErrorOptions, ProtocolFeatureUnsupportedErrorOptions, ActionNotAllowedErrorDetails, ActionNotAllowedReasonValue, ActionNotAllowedAttemptedAction, ActionNotAllowedAvailableAction, ActionNotAllowedRecovery, } from './errors';
 export type { ActionNotAllowedDetails, ActionNotAllowedReason, AvailableActionsResult, AvailableActionsSource, DecomposedUpdateMediaBuy, DecomposedUpdateMediaBuyMutation, LegacyCoarseAction, MediaBuyActionContext, MediaBuyActionId, MediaBuyActionMode, MediaBuyAvailableAction, MediaBuyMutationDirection, MediaBuyMutationScope, MediaBuyUpdateFieldAction, MediaBuyValidAction, ModeMismatchRecovery, PreflightAllowed, PreflightDenial, PreflightDenied, BuyerPropertyPolicy, NormalizedPolicyDomain, ProductPolicyProductLike, ProductPolicyResolvedProperty, ProductPropertyPolicyIdentifier, ProductPropertyPolicyDiagnostic, ProductPropertyPolicyDiagnosticCode, ProductPropertyPolicyDiagnosticSeverity, ProductPropertyPolicyMode, ProductPropertyPolicySelectorBehavior, ProductPropertyPolicyValidationResult, PreflightResult, ResolvedAction, SLAWindow, SlaWindow, StructuredOnlyMediaBuyAction, ResolvedTargetingInput, TargetingInputFor, ValidateProductsAgainstPropertyPolicyOptions, UpdateFieldEntry, UpdateMediaBuyRequestLike, } from './media-buy';
 export { ACTIONS_BY_FIELD, LEGACY_COARSE_ACTIONS, STRUCTURED_ONLY_MEDIA_BUY_ACTIONS, UPDATE_FIELDS_BY_ACTION, applyTargetingInput, hasTargetingClears, resolveTargetingInput, canAddPackages, canCancel, canDecreaseBudget, canExtendFlight, canIncreaseBudget, canPause, canReallocateBudget, canRemoveCreative, canRemovePackages, canReplaceCreative, canResume, canShortenFlight, canUpdateCreativeAssignments, canUpdateFlightDates, canUpdateFrequencyCaps, canUpdatePacing, canUpdateTargeting, decomposeUpdateMediaBuy, findAvailableAction, getActionForMutation, getAvailableActions, getRollupParent, ProductPropertyPolicyError, normalizeDomainForPropertyPolicy, preflightUpdateMediaBuy, recoveryForModeMismatch, validateProductsAgainstPropertyPolicy, } from './media-buy';

package/dist/lib/index.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   AgentClient: () => import_AgentClient.AgentClient,
   AgentNotFoundError: () => import_errors.AgentNotFoundError,
   AgentOAuthClientCredentialsSchema: () => import_oauth4.AgentOAuthClientCredentialsSchema,
+  AgentRateLimitedError: () => import_errors.AgentRateLimitedError,
   Asset: () => import_asset_builders.Asset,
   AsyncHandler: () => import_AsyncHandler.AsyncHandler,
   AuthenticationCredentialsRejectedError: () => import_errors.AuthenticationCredentialsRejectedError,
@@ -896,6 +897,7 @@ function createAdCPClientFromEnv() {
   AgentClient,
   AgentNotFoundError,
   AgentOAuthClientCredentialsSchema,
+  AgentRateLimitedError,
   Asset,
   AsyncHandler,
   AuthenticationCredentialsRejectedError,

package/dist/lib/index.mjs

@@ -234,6 +234,7 @@ import {
   IdempotencyConflictError,
   IdempotencyExpiredError,
   ResponseTooLargeError,
+  AgentRateLimitedError,
   ActionNotAllowedError,
   PreparedFixturesDeniedError,
   adcpErrorToTypedError,
@@ -858,6 +859,7 @@ export {
   AgentClient,
   AgentNotFoundError,
   AgentOAuthClientCredentialsSchema,
+  AgentRateLimitedError,
   Asset,
   AsyncHandler,
   AuthenticationCredentialsRejectedError,

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,6 +20,7 @@ var mcp_modern_exports = {};
 __export(mcp_modern_exports, {
   closeModernMCPConnections: () => closeModernMCPConnections,
   probeModernMCPConnection: () => probeModernMCPConnection,
+  retryAfterOf: () => retryAfterOf,
   tryCallModernMCPTool: () => tryCallModernMCPTool,
   tryListModernMCPTools: () => tryListModernMCPTools
 });
@@ -248,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
     }
@@ -293,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++) {
@@ -314,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);
@@ -341,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);
@@ -510,6 +534,7 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.allowPrivateIp
   );
   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 }),
@@ -650,6 +675,7 @@ async function closeModernMCPConnections() {
 0 && (module.exports = {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 });

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

@@ -16,6 +16,7 @@ import { is401Error } from "../errors/index.mjs";
 import { withSpan, injectTraceHeaders } from "../observability/tracing.mjs";
 import {
   currentMCPConnectionScopeKey,
+  markMCPConnectionScopeInterrupted,
   isMCPConnectionScopeCacheKeyActive,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending
@@ -255,9 +256,15 @@ async function createNegotiatedClient(cacheKey, options, authHeaders, useCachedD
     getCapability: options.signingContext.getCapability,
     adcpVersion: options.signingContext.adcpVersion
   }) : diagnosticFetch;
+  const transportFetch = wrapFetchWithCapture(withPerRequestTraceHeaders(signedFetch));
+  let throttleRetryAfter;
   const transport = new StreamableHTTPClientTransport(new URL(options.agentUrl), {
     requestInit: { headers: splitConnectionHeaders(authHeaders).identity, redirect: "manual" },
-    fetch: 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
     }
@@ -300,8 +307,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++) {
@@ -321,12 +342,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);
-      registerMCPConnectionScopeCleanup("modern", cacheKey, async () => {
+      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);
@@ -348,7 +369,10 @@ function createSharedModernConnection(cacheKey, options, authHeaders) {
   return promise;
 }
 async function retireFailedConnection(cacheKey, client, error) {
-  if (isAbortOrTimeoutError(error)) return;
+  if (isAbortOrTimeoutError(error)) {
+    markMCPConnectionScopeInterrupted();
+    return;
+  }
   if (modernConnections.get(cacheKey) === client) {
     modernConnections.delete(cacheKey);
     legacyConnectionExpiresAt.delete(cacheKey);
@@ -517,6 +541,7 @@ async function probeModernMCPConnection(agentUrl, authToken, customHeaders, opti
     options.allowPrivateIp
   );
   const scoped = shouldReuseMCPConnection(options.fetchFn !== void 0);
+  if (isKnownLegacy(cacheKey)) return { connected: false };
   let client;
   return runWithMCPCallContext(
     callContextFor({ customHeaders, requestTimeoutMs: options.requestTimeoutMs }),
@@ -656,6 +681,7 @@ async function closeModernMCPConnections() {
 export {
   closeModernMCPConnections,
   probeModernMCPConnection,
+  retryAfterOf,
   tryCallModernMCPTool,
   tryListModernMCPTools
 };

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

@@ -1,6 +1,8 @@
-type ScopeCleanup = () => Promise<void>;
+type ScopeCleanup = (terminateSession: boolean) => Promise<void>;
 /** Cache-key suffix for the current caller-owned MCP workflow. */
 export declare function currentMCPConnectionScopeKey(): string | undefined;
+/** Preserve seller work even when a higher layer handles a request timeout. */
+export declare function markMCPConnectionScopeInterrupted(): void;
 /** Whether an LRU entry belongs to a workflow that has not finished yet. */
 export declare function isMCPConnectionScopeCacheKeyActive(cacheKey: string): boolean;
 /** Register one idempotent cache-entry cleanup with the current workflow. */

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

@@ -1,6 +1,8 @@
-type ScopeCleanup = () => Promise<void>;
+type ScopeCleanup = (terminateSession: boolean) => Promise<void>;
 /** Cache-key suffix for the current caller-owned MCP workflow. */
 export declare function currentMCPConnectionScopeKey(): string | undefined;
+/** Preserve seller work even when a higher layer handles a request timeout. */
+export declare function markMCPConnectionScopeInterrupted(): void;
 /** Whether an LRU entry belongs to a workflow that has not finished yet. */
 export declare function isMCPConnectionScopeCacheKeyActive(cacheKey: string): boolean;
 /** Register one idempotent cache-entry cleanup with the current workflow. */

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

@@ -21,18 +21,24 @@ __export(mcp_scope_exports, {
   closeCurrentMCPConnectionScope: () => closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey: () => currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive: () => isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted: () => markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup: () => registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending: () => registerMCPConnectionScopePending,
   withMCPConnectionScope: () => withMCPConnectionScope
 });
 module.exports = __toCommonJS(mcp_scope_exports);
 var import_node_async_hooks = require("node:async_hooks");
+var import_abort = require('./abort.js');
 const scopeStorage = new import_node_async_hooks.AsyncLocalStorage();
 const activeScopeKeys = /* @__PURE__ */ new Set();
 let nextScopeId = 0;
 function currentMCPConnectionScopeKey() {
   return scopeStorage.getStore()?.cacheKey;
 }
+function markMCPConnectionScopeInterrupted() {
+  const scope = scopeStorage.getStore();
+  if (scope?.preserveOnInterruption) scope.interrupted = true;
+}
 function isMCPConnectionScopeCacheKeyActive(cacheKey) {
   const marker = cacheKey.lastIndexOf("::scope:");
   return marker >= 0 && activeScopeKeys.has(cacheKey.slice(marker + 2));
@@ -55,17 +61,27 @@ async function closeCurrentMCPConnectionScope() {
   }
   const cleanups = [...scope.cleanups.values()];
   scope.cleanups.clear();
-  await Promise.allSettled(cleanups.map((cleanup) => cleanup()));
+  await Promise.allSettled(cleanups.map((cleanup) => cleanup(!scope.signal?.aborted && !scope.interrupted)));
   return true;
 }
 async function withMCPConnectionScope(fn, options = {}) {
   if (scopeStorage.getStore() && options.isolate !== true) return fn();
   const id = ++nextScopeId;
-  const scope = { id, cacheKey: `scope:${id}`, pending: /* @__PURE__ */ new Set(), cleanups: /* @__PURE__ */ new Map() };
+  const scope = {
+    id,
+    cacheKey: `scope:${id}`,
+    pending: /* @__PURE__ */ new Set(),
+    cleanups: /* @__PURE__ */ new Map(),
+    signal: options.signal,
+    preserveOnInterruption: options.preserveOnInterruption
+  };
   activeScopeKeys.add(scope.cacheKey);
   return scopeStorage.run(scope, async () => {
     try {
       return await fn();
+    } catch (error) {
+      if ((0, import_abort.isAbortOrTimeoutError)(error)) markMCPConnectionScopeInterrupted();
+      throw error;
     } finally {
       try {
         await closeCurrentMCPConnectionScope();
@@ -80,6 +96,7 @@ async function withMCPConnectionScope(fn, options = {}) {
   closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending,
   withMCPConnectionScope

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

@@ -4,12 +4,17 @@ import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isAbortOrTimeoutError } from "./abort.mjs";
 const scopeStorage = new AsyncLocalStorage();
 const activeScopeKeys = /* @__PURE__ */ new Set();
 let nextScopeId = 0;
 function currentMCPConnectionScopeKey() {
   return scopeStorage.getStore()?.cacheKey;
 }
+function markMCPConnectionScopeInterrupted() {
+  const scope = scopeStorage.getStore();
+  if (scope?.preserveOnInterruption) scope.interrupted = true;
+}
 function isMCPConnectionScopeCacheKeyActive(cacheKey) {
   const marker = cacheKey.lastIndexOf("::scope:");
   return marker >= 0 && activeScopeKeys.has(cacheKey.slice(marker + 2));
@@ -32,17 +37,27 @@ async function closeCurrentMCPConnectionScope() {
   }
   const cleanups = [...scope.cleanups.values()];
   scope.cleanups.clear();
-  await Promise.allSettled(cleanups.map((cleanup) => cleanup()));
+  await Promise.allSettled(cleanups.map((cleanup) => cleanup(!scope.signal?.aborted && !scope.interrupted)));
   return true;
 }
 async function withMCPConnectionScope(fn, options = {}) {
   if (scopeStorage.getStore() && options.isolate !== true) return fn();
   const id = ++nextScopeId;
-  const scope = { id, cacheKey: `scope:${id}`, pending: /* @__PURE__ */ new Set(), cleanups: /* @__PURE__ */ new Map() };
+  const scope = {
+    id,
+    cacheKey: `scope:${id}`,
+    pending: /* @__PURE__ */ new Set(),
+    cleanups: /* @__PURE__ */ new Map(),
+    signal: options.signal,
+    preserveOnInterruption: options.preserveOnInterruption
+  };
   activeScopeKeys.add(scope.cacheKey);
   return scopeStorage.run(scope, async () => {
     try {
       return await fn();
+    } catch (error) {
+      if (isAbortOrTimeoutError(error)) markMCPConnectionScopeInterrupted();
+      throw error;
     } finally {
       try {
         await closeCurrentMCPConnectionScope();
@@ -56,6 +71,7 @@ export {
   closeCurrentMCPConnectionScope,
   currentMCPConnectionScopeKey,
   isMCPConnectionScopeCacheKeyActive,
+  markMCPConnectionScopeInterrupted,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending,
   withMCPConnectionScope

package/dist/lib/protocols/mcp.js

@@ -207,10 +207,10 @@ async function getOrCreateConnection(cacheKey, baseUrl, authHeaders, debugLogs,
         throw new Error(`MCP ${label} completed after connection teardown`);
       }
       connectionCache.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("legacy", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("legacy", cacheKey, async (terminateSession) => {
         if (connectionCache.get(cacheKey) !== client) return;
         connectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsed();
       return client;
@@ -280,10 +280,10 @@ async function getOrCreateOAuthConnection(cacheKey, options) {
         throw new Error("OAuth MCP connection completed after connection teardown");
       }
       oauthConnectionCache.set(cacheKey, client);
-      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("oauth", cacheKey, async () => {
+      (0, import_mcp_scope.registerMCPConnectionScopeCleanup)("oauth", cacheKey, async (terminateSession) => {
         if (oauthConnectionCache.get(cacheKey) !== client) return;
         oauthConnectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsedOAuth();
       return client;
@@ -337,7 +337,10 @@ async function withCachedOAuthConnectionImpl(options, label, fn) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if ((0, import_abort.isAbortOrTimeoutError)(error)) throw error;
+    if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+      (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+      throw error;
+    }
     if ((0, import_errors.is401Error)(error)) {
       options.debugLogs.push({
         type: "warning",
@@ -405,7 +408,10 @@ async function withCachedConnectionImpl(agentUrl, authToken, authHeaders, debugL
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if ((0, import_abort.isAbortOrTimeoutError)(error)) throw error;
+    if ((0, import_abort.isAbortOrTimeoutError)(error)) {
+      (0, import_mcp_scope.markMCPConnectionScopeInterrupted)();
+      throw error;
+    }
     if ((0, import_errors.is401Error)(error)) {
       debugLogs.push({
         type: "warning",

package/dist/lib/protocols/mcp.mjs

@@ -35,6 +35,7 @@ import {
 import { closeModernMCPConnections, tryCallModernMCPTool } from "./mcp-modern.mjs";
 import {
   currentMCPConnectionScopeKey,
+  markMCPConnectionScopeInterrupted,
   isMCPConnectionScopeCacheKeyActive,
   registerMCPConnectionScopeCleanup,
   registerMCPConnectionScopePending
@@ -208,10 +209,10 @@ async function getOrCreateConnection(cacheKey, baseUrl, authHeaders, debugLogs,
         throw new Error(`MCP ${label} completed after connection teardown`);
       }
       connectionCache.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("legacy", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("legacy", cacheKey, async (terminateSession) => {
         if (connectionCache.get(cacheKey) !== client) return;
         connectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsed();
       return client;
@@ -281,10 +282,10 @@ async function getOrCreateOAuthConnection(cacheKey, options) {
         throw new Error("OAuth MCP connection completed after connection teardown");
       }
       oauthConnectionCache.set(cacheKey, client);
-      registerMCPConnectionScopeCleanup("oauth", cacheKey, async () => {
+      registerMCPConnectionScopeCleanup("oauth", cacheKey, async (terminateSession) => {
         if (oauthConnectionCache.get(cacheKey) !== client) return;
         oauthConnectionCache.delete(cacheKey);
-        await closeMCPClient(client);
+        await closeMCPClient(client, terminateSession);
       });
       evictLeastRecentlyUsedOAuth();
       return client;
@@ -338,7 +339,10 @@ async function withCachedOAuthConnectionImpl(options, label, fn) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if (isAbortOrTimeoutError(error)) throw error;
+    if (isAbortOrTimeoutError(error)) {
+      markMCPConnectionScopeInterrupted();
+      throw error;
+    }
     if (is401Error(error)) {
       options.debugLogs.push({
         type: "warning",
@@ -406,7 +410,10 @@ async function withCachedConnectionImpl(agentUrl, authToken, authHeaders, debugL
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       error
     });
-    if (isAbortOrTimeoutError(error)) throw error;
+    if (isAbortOrTimeoutError(error)) {
+      markMCPConnectionScopeInterrupted();
+      throw error;
+    }
     if (is401Error(error)) {
       debugLogs.push({
         type: "warning",

package/dist/lib/testing/client.d.mts

@@ -89,6 +89,7 @@ schemaAdcpVersion?: string): Promise<{
     profile: AgentProfile;
     step: TestStepResult;
     caughtError?: unknown;
+    evidence?: TestStepResult;
 }>;
 /**
  * Discover what channels, pricing models, formats the agent supports

package/dist/lib/testing/client.d.ts

@@ -89,6 +89,7 @@ schemaAdcpVersion?: string): Promise<{
     profile: AgentProfile;
     step: TestStepResult;
     caughtError?: unknown;
+    evidence?: TestStepResult;
 }>;
 /**
  * Discover what channels, pricing models, formats the agent supports