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

package/dist/lib/adapters/version/3.1/bidding.js

@@ -96,7 +96,7 @@ const updateMediaBuyAdapter = {
 function adaptMediaBuyStatus(toolName) {
   return (data) => {
     if (!isObject(data)) return { data };
-    const adapted = (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName });
+    const adapted = (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName, adcpVersion: "3.1" });
     if (adapted === data || adapted.media_buy_status === data.media_buy_status) return { data };
     return {
       data: adapted,

package/dist/lib/adapters/version/3.1/bidding.mjs

@@ -72,7 +72,7 @@ const updateMediaBuyAdapter = {
 function adaptMediaBuyStatus(toolName) {
   return (data) => {
     if (!isObject(data)) return { data };
-    const adapted = injectLegacyEnvelopeStatus(data, { toolName });
+    const adapted = injectLegacyEnvelopeStatus(data, { toolName, adcpVersion: "3.1" });
     if (adapted === data || adapted.media_buy_status === data.media_buy_status) return { data };
     return {
       data: adapted,

package/dist/lib/core/ResponseValidator.js

@@ -252,7 +252,7 @@ class ResponseValidator {
     if (!schema) {
       return null;
     }
-    const validatePayload = data && typeof data === "object" && !Array.isArray(data) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName }) : data;
+    const validatePayload = data && typeof data === "object" && !Array.isArray(data) ? (0, import_envelope_status_compat.injectLegacyEnvelopeStatus)(data, { toolName, adcpVersion: responseAdcpVersion }) : data;
     const result = schema.safeParse((0, import_response_schemas.prepareResponseForSchemaValidation)(toolName, validatePayload, responseAdcpVersion));
     return result.success ? null : result.error;
   }

package/dist/lib/core/ResponseValidator.mjs

@@ -228,7 +228,7 @@ class ResponseValidator {
     if (!schema) {
       return null;
     }
-    const validatePayload = data && typeof data === "object" && !Array.isArray(data) ? injectLegacyEnvelopeStatus(data, { toolName }) : data;
+    const validatePayload = data && typeof data === "object" && !Array.isArray(data) ? injectLegacyEnvelopeStatus(data, { toolName, adcpVersion: responseAdcpVersion }) : data;
     const result = schema.safeParse(prepareResponseForSchemaValidation(toolName, validatePayload, responseAdcpVersion));
     return result.success ? null : result.error;
   }

package/dist/lib/core/SingleAgentClient.d.mts

@@ -726,6 +726,9 @@ export declare class SingleAgentClient {
      * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
      * - Otherwise AuthenticationRequiredError carries the advertised challenge
      *
+     * Rate limiting (429, or 503 with Retry-After) stops probing at that URL and
+     * throws AgentRateLimitedError carrying the status and Retry-After.
+     *
      * Note: This is async and called lazily on first agent interaction
      */
     private discoverMCPEndpoint;
@@ -888,11 +891,10 @@ export declare class SingleAgentClient {
      * @returns true if signature is valid
      */
     verifyWebhookSignature(rawBodyOrPayload: string | Buffer | Uint8Array | unknown, signature: WebhookHeaderValue, timestamp: WebhookHeaderValue): boolean;
-    /**
-     * Execute task and call appropriate handler on completion
-     *
-     * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
-     */
+    /** One task owns discovery and dispatch sessions unless the caller already owns reuse. */
+    private withConnectionScope;
+    private withTaskConnectionScope;
+    /** Execute a task, adapt maintained AdCP 3 releases, and call the completion handler. */
     private executeAndHandle;
     private executeAndHandleWithinDeadline;
     private finalizeTaskResult;

package/dist/lib/core/SingleAgentClient.d.ts

@@ -726,6 +726,9 @@ export declare class SingleAgentClient {
      * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
      * - Otherwise AuthenticationRequiredError carries the advertised challenge
      *
+     * Rate limiting (429, or 503 with Retry-After) stops probing at that URL and
+     * throws AgentRateLimitedError carrying the status and Retry-After.
+     *
      * Note: This is async and called lazily on first agent interaction
      */
     private discoverMCPEndpoint;
@@ -888,11 +891,10 @@ export declare class SingleAgentClient {
      * @returns true if signature is valid
      */
     verifyWebhookSignature(rawBodyOrPayload: string | Buffer | Uint8Array | unknown, signature: WebhookHeaderValue, timestamp: WebhookHeaderValue): boolean;
-    /**
-     * Execute task and call appropriate handler on completion
-     *
-     * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
-     */
+    /** One task owns discovery and dispatch sessions unless the caller already owns reuse. */
+    private withConnectionScope;
+    private withTaskConnectionScope;
+    /** Execute a task, adapt maintained AdCP 3 releases, and call the completion handler. */
     private executeAndHandle;
     private executeAndHandleWithinDeadline;
     private finalizeTaskResult;

package/dist/lib/core/SingleAgentClient.js

@@ -35,6 +35,7 @@ __export(SingleAgentClient_exports, {
 });
 module.exports = __toCommonJS(SingleAgentClient_exports);
 var import_mcp_connection_policy = require('../protocols/mcp-connection-policy.js');
+var import_mcp_scope = require('../protocols/mcp-scope.js');
 var import_protocol_methods = require('../signing/protocol-methods.js');
 var import_pricing_adapter = require('../utils/pricing-adapter.js');
 var import_creative_adapter = require('../utils/creative-adapter.js');
@@ -2199,6 +2200,9 @@ class SingleAgentClient {
    * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
    * - Otherwise AuthenticationRequiredError carries the advertised challenge
    *
+   * Rate limiting (429, or 503 with Retry-After) stops probing at that URL and
+   * throws AgentRateLimitedError carrying the status and Retry-After.
+   *
    * Note: This is async and called lazily on first agent interaction
    */
   async discoverMCPEndpoint(providedUri, options) {
@@ -2209,8 +2213,8 @@ class SingleAgentClient {
   }
   async discoverMCPEndpointWithConnectionPolicy(providedUri, options) {
     (0, import_abort2.throwIfAborted)(options?.signal);
-    const { connectMCPWithFallback } = await import("../protocols/mcp.js");
-    const { probeModernMCPConnection } = await import("../protocols/mcp-modern.js");
+    const { connectMCPWithFallback, withScopedLegacyConnection } = await import("../protocols/mcp.js");
+    const { probeModernMCPConnection, retryAfterOf } = await import("../protocols/mcp-modern.js");
     const transport = (0, import_protocols.normalizeTransportOptions)(options?.transport ?? this.config.transport);
     const usesScopedFetch = this.usesScopedDiscoveryTransport(options);
     const endpointEpoch = this.discoveryEpochSnapshot(options);
@@ -2240,19 +2244,35 @@ class SingleAgentClient {
           }
           return { success: true };
         }
-        const client = await connectMCPWithFallback(
-          new URL(url),
-          authHeaders,
-          [],
-          "endpoint discovery",
-          transport?.trustedFetchFn,
+        const shared = await withScopedLegacyConnection(
           {
+            agentUrl: url,
+            authToken,
+            customHeaders: agentHeaders,
+            authProvider,
             signal: options?.signal,
             requestTimeoutMs: transport?.requestTimeoutMs,
+            fetchFn: transport?.trustedFetchFn,
             allowPrivateIp: transport?.allowPrivateIp
-          }
+          },
+          "endpoint discovery",
+          async () => void 0
         );
-        await client.close();
+        if (!shared) {
+          const client = await connectMCPWithFallback(
+            new URL(url),
+            authHeaders,
+            [],
+            "endpoint discovery",
+            transport?.trustedFetchFn,
+            {
+              signal: options?.signal,
+              requestTimeoutMs: transport?.requestTimeoutMs,
+              allowPrivateIp: transport?.allowPrivateIp
+            }
+          );
+          await client.close();
+        }
         if (mayRetain()) {
           this.discoveredMcpEra = "legacy";
           this.discoveredMcpEraAt = Date.now();
@@ -2269,7 +2289,8 @@ class SingleAgentClient {
         }
         const errObj = error;
         const status = errObj?.status || errObj?.response?.status || errObj?.cause?.status;
-        return { success: false, status, error };
+        const retryAfter = retryAfterOf(error);
+        return { success: false, status, ...retryAfter !== void 0 && { retryAfter }, error };
       }
     };
     const urlsToTry = [];
@@ -2292,6 +2313,9 @@ class SingleAgentClient {
         firstWorkingUrl = url;
         break;
       }
+      if (result.status === 429 || result.status === 503 && result.retryAfter !== void 0) {
+        throw new import_errors.AgentRateLimitedError(url, result.status, result.retryAfter, result.error);
+      }
       if (result.status === 401) {
         got401 = true;
         first401Error ??= result.error;
@@ -3504,17 +3528,24 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       timestamp
     }).ok;
   }
-  /**
-   * Execute task and call appropriate handler on completion
-   *
-   * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
-   */
+  /** One task owns discovery and dispatch sessions unless the caller already owns reuse. */
+  withConnectionScope(options, run) {
+    const transport = (0, import_protocols.normalizeTransportOptions)(options?.transport ?? this.config.transport);
+    return (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
+      transport,
+      () => (0, import_mcp_connection_policy.shouldReuseMCPConnection)(transport?.trustedFetchFn !== void 0) ? run() : (0, import_mcp_scope.withMCPConnectionScope)(run, { signal: options?.signal, preserveOnInterruption: true })
+    );
+  }
+  withTaskConnectionScope(options, run) {
+    return (0, import_task_deadline.withTaskDeadline)(options, (effective) => this.withConnectionScope(effective, () => run(effective)));
+  }
+  /** Execute a task, adapt maintained AdCP 3 releases, and call the completion handler. */
   async executeAndHandle(taskType, handlerName, params, inputHandler, options, transformCompletedResponse, legacyFormatConverter, canonicalRequest, projectionCatalogs) {
     const requestParamsSnapshot = structuredClone(params);
     const canonicalRequestSnapshot = canonicalRequest === void 0 ? void 0 : structuredClone(canonicalRequest);
     const deferredProjectionCatalogs = projectionCatalogs ? structuredClone(projectionCatalogs) : void 0;
     const taskOptionsSnapshot = snapshotTaskOptions(options);
-    return (0, import_task_deadline.withTaskDeadline)(
+    return this.withTaskConnectionScope(
       taskOptionsSnapshot,
       (effectiveOptions) => this.executeAndHandleWithinDeadline(
         taskType,
@@ -5060,7 +5091,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       legacyFormatConverter,
       projectionCatalogs ?? this.config.projectionCatalogs
     );
-    return (0, import_task_deadline.withTaskDeadline)(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
+    return this.withTaskConnectionScope(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
       this.assertRequestSupportedByConfiguredVersion("get_products", params, effectiveOptions);
       let request = await this.applyAccountPolicy("get_products", params, effectiveOptions);
       const legacyAccountId = request.account_id;
@@ -5269,7 +5300,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...snapshotTaskOptions(options),
       ...projectionCatalogs !== void 0 && { projectionCatalogs }
     };
-    return (0, import_task_deadline.withTaskDeadline)(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.createMediaBuyWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -5428,7 +5459,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...snapshotTaskOptions(options),
       ...projectionCatalogs !== void 0 && { projectionCatalogs }
     };
-    return (0, import_task_deadline.withTaskDeadline)(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.updateMediaBuyWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -5519,7 +5550,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...projectionCatalogs !== void 0 && { projectionCatalogs },
       ...creativeFormatProjection !== void 0 && { creativeFormatProjection }
     };
-    return (0, import_task_deadline.withTaskDeadline)(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.syncCreativesWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -6036,7 +6067,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @param options - Task execution options
    */
   async getAdcpCapabilities(params, inputHandler, options) {
-    return (0, import_task_deadline.withTaskDeadline)(
+    return this.withTaskConnectionScope(
       snapshotTaskOptions(options),
       (effectiveOptions) => this.getAdcpCapabilitiesWithinDeadline(params, inputHandler, effectiveOptions)
     );
@@ -6118,7 +6149,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     );
   }
   async resolveAccount(hints = {}, options, onTaskResult) {
-    return (0, import_task_deadline.withTaskDeadline)(snapshotTaskOptions(options), async (effectiveOptions) => {
+    return this.withTaskConnectionScope(snapshotTaskOptions(options), async (effectiveOptions) => {
       const capabilities = await this.getCapabilities(effectiveOptions);
       if (capabilities._synthetic || !capabilities.account) {
         throw new import_errors3.AccountRequiredError(
@@ -6598,7 +6629,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async executeTaskUnprojected(taskName, params, inputHandler, options, handlerName, beforeDispatch) {
     const requestParamsSnapshot = structuredClone(params);
     const taskOptionsSnapshot = snapshotTaskOptions(options);
-    return (0, import_task_deadline.withTaskDeadline)(taskOptionsSnapshot, async (effectiveOptions) => {
+    return this.withTaskConnectionScope(taskOptionsSnapshot, async (effectiveOptions) => {
       const result = await this.executeTaskUnprojectedWithinDeadline(
         taskName,
         requestParamsSnapshot,
@@ -7177,10 +7208,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * ```
    */
   async getAgentInfo(options) {
-    return (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
-      (0, import_protocols.normalizeTransportOptions)(options?.transport ?? this.config.transport),
-      () => this.getAgentInfoWithConnectionPolicy(options)
-    );
+    return this.withConnectionScope(options, () => this.getAgentInfoWithConnectionPolicy(options));
   }
   async getAgentInfoWithConnectionPolicy(options) {
     (0, import_abort2.throwIfAborted)(options?.signal);
@@ -7431,10 +7459,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * ```
    */
   async getCapabilities(options) {
-    return (0, import_mcp_connection_policy.withMCPConnectionPolicy)(
-      (0, import_protocols.normalizeTransportOptions)(options?.transport ?? this.config.transport),
-      () => this.getCapabilitiesWithConnectionPolicy(options)
-    );
+    return this.withConnectionScope(options, () => this.getCapabilitiesWithConnectionPolicy(options));
   }
   async getCapabilitiesWithConnectionPolicy(options) {
     (0, import_abort2.throwIfAborted)(options?.signal);

package/dist/lib/core/SingleAgentClient.mjs

@@ -3,7 +3,8 @@ 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 { withMCPConnectionPolicy } from "../protocols/mcp-connection-policy.mjs";
+import { shouldReuseMCPConnection, withMCPConnectionPolicy } from "../protocols/mcp-connection-policy.mjs";
+import { withMCPConnectionScope } from "../protocols/mcp-scope.mjs";
 import { hasUnsignedCapabilityBootstrap } from "../signing/protocol-methods.mjs";
 import { normalizeGetProductsResponse } from "../utils/pricing-adapter.mjs";
 import { normalizeMediaBuyResponse } from "../utils/creative-adapter.mjs";
@@ -74,6 +75,7 @@ import { getSignedRequestRejection } from "../protocols/signedRequestRejection.m
 import { withAmbientIdentityHeaders } from "../protocols/mcp-call-context.mjs";
 import { ProtocolClient, normalizeTransportOptions } from "../protocols/index.mjs";
 import {
+  AgentRateLimitedError,
   AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
   ConfigurationError,
@@ -2309,6 +2311,9 @@ class SingleAgentClient {
    * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
    * - Otherwise AuthenticationRequiredError carries the advertised challenge
    *
+   * Rate limiting (429, or 503 with Retry-After) stops probing at that URL and
+   * throws AgentRateLimitedError carrying the status and Retry-After.
+   *
    * Note: This is async and called lazily on first agent interaction
    */
   async discoverMCPEndpoint(providedUri, options) {
@@ -2319,8 +2324,8 @@ class SingleAgentClient {
   }
   async discoverMCPEndpointWithConnectionPolicy(providedUri, options) {
     throwIfAborted(options?.signal);
-    const { connectMCPWithFallback } = await import("../protocols/mcp.mjs");
-    const { probeModernMCPConnection } = await import("../protocols/mcp-modern.mjs");
+    const { connectMCPWithFallback, withScopedLegacyConnection } = await import("../protocols/mcp.mjs");
+    const { probeModernMCPConnection, retryAfterOf } = await import("../protocols/mcp-modern.mjs");
     const transport = normalizeTransportOptions(options?.transport ?? this.config.transport);
     const usesScopedFetch = this.usesScopedDiscoveryTransport(options);
     const endpointEpoch = this.discoveryEpochSnapshot(options);
@@ -2350,19 +2355,35 @@ class SingleAgentClient {
           }
           return { success: true };
         }
-        const client = await connectMCPWithFallback(
-          new URL(url),
-          authHeaders,
-          [],
-          "endpoint discovery",
-          transport?.trustedFetchFn,
+        const shared = await withScopedLegacyConnection(
           {
+            agentUrl: url,
+            authToken,
+            customHeaders: agentHeaders,
+            authProvider,
             signal: options?.signal,
             requestTimeoutMs: transport?.requestTimeoutMs,
+            fetchFn: transport?.trustedFetchFn,
             allowPrivateIp: transport?.allowPrivateIp
-          }
+          },
+          "endpoint discovery",
+          async () => void 0
         );
-        await client.close();
+        if (!shared) {
+          const client = await connectMCPWithFallback(
+            new URL(url),
+            authHeaders,
+            [],
+            "endpoint discovery",
+            transport?.trustedFetchFn,
+            {
+              signal: options?.signal,
+              requestTimeoutMs: transport?.requestTimeoutMs,
+              allowPrivateIp: transport?.allowPrivateIp
+            }
+          );
+          await client.close();
+        }
         if (mayRetain()) {
           this.discoveredMcpEra = "legacy";
           this.discoveredMcpEraAt = Date.now();
@@ -2379,7 +2400,8 @@ class SingleAgentClient {
         }
         const errObj = error;
         const status = errObj?.status || errObj?.response?.status || errObj?.cause?.status;
-        return { success: false, status, error };
+        const retryAfter = retryAfterOf(error);
+        return { success: false, status, ...retryAfter !== void 0 && { retryAfter }, error };
       }
     };
     const urlsToTry = [];
@@ -2402,6 +2424,9 @@ class SingleAgentClient {
         firstWorkingUrl = url;
         break;
       }
+      if (result.status === 429 || result.status === 503 && result.retryAfter !== void 0) {
+        throw new AgentRateLimitedError(url, result.status, result.retryAfter, result.error);
+      }
       if (result.status === 401) {
         got401 = true;
         first401Error ??= result.error;
@@ -3614,17 +3639,24 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       timestamp
     }).ok;
   }
-  /**
-   * Execute task and call appropriate handler on completion
-   *
-   * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
-   */
+  /** One task owns discovery and dispatch sessions unless the caller already owns reuse. */
+  withConnectionScope(options, run) {
+    const transport = normalizeTransportOptions(options?.transport ?? this.config.transport);
+    return withMCPConnectionPolicy(
+      transport,
+      () => shouldReuseMCPConnection(transport?.trustedFetchFn !== void 0) ? run() : withMCPConnectionScope(run, { signal: options?.signal, preserveOnInterruption: true })
+    );
+  }
+  withTaskConnectionScope(options, run) {
+    return withTaskDeadline(options, (effective) => this.withConnectionScope(effective, () => run(effective)));
+  }
+  /** Execute a task, adapt maintained AdCP 3 releases, and call the completion handler. */
   async executeAndHandle(taskType, handlerName, params, inputHandler, options, transformCompletedResponse, legacyFormatConverter, canonicalRequest, projectionCatalogs) {
     const requestParamsSnapshot = structuredClone(params);
     const canonicalRequestSnapshot = canonicalRequest === void 0 ? void 0 : structuredClone(canonicalRequest);
     const deferredProjectionCatalogs = projectionCatalogs ? structuredClone(projectionCatalogs) : void 0;
     const taskOptionsSnapshot = snapshotTaskOptions(options);
-    return withTaskDeadline(
+    return this.withTaskConnectionScope(
       taskOptionsSnapshot,
       (effectiveOptions) => this.executeAndHandleWithinDeadline(
         taskType,
@@ -5170,7 +5202,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       legacyFormatConverter,
       projectionCatalogs ?? this.config.projectionCatalogs
     );
-    return withTaskDeadline(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
+    return this.withTaskConnectionScope(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
       this.assertRequestSupportedByConfiguredVersion("get_products", params, effectiveOptions);
       let request = await this.applyAccountPolicy("get_products", params, effectiveOptions);
       const legacyAccountId = request.account_id;
@@ -5379,7 +5411,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...snapshotTaskOptions(options),
       ...projectionCatalogs !== void 0 && { projectionCatalogs }
     };
-    return withTaskDeadline(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.createMediaBuyWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -5538,7 +5570,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...snapshotTaskOptions(options),
       ...projectionCatalogs !== void 0 && { projectionCatalogs }
     };
-    return withTaskDeadline(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.updateMediaBuyWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -5629,7 +5661,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ...projectionCatalogs !== void 0 && { projectionCatalogs },
       ...creativeFormatProjection !== void 0 && { creativeFormatProjection }
     };
-    return withTaskDeadline(
+    return this.withTaskConnectionScope(
       snapshottedOptions,
       (effectiveOptions) => this.syncCreativesWithinDeadline(requestSnapshot, inputHandler, effectiveOptions)
     );
@@ -6146,7 +6178,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @param options - Task execution options
    */
   async getAdcpCapabilities(params, inputHandler, options) {
-    return withTaskDeadline(
+    return this.withTaskConnectionScope(
       snapshotTaskOptions(options),
       (effectiveOptions) => this.getAdcpCapabilitiesWithinDeadline(params, inputHandler, effectiveOptions)
     );
@@ -6228,7 +6260,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     );
   }
   async resolveAccount(hints = {}, options, onTaskResult) {
-    return withTaskDeadline(snapshotTaskOptions(options), async (effectiveOptions) => {
+    return this.withTaskConnectionScope(snapshotTaskOptions(options), async (effectiveOptions) => {
       const capabilities = await this.getCapabilities(effectiveOptions);
       if (capabilities._synthetic || !capabilities.account) {
         throw new AccountRequiredError(
@@ -6708,7 +6740,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async executeTaskUnprojected(taskName, params, inputHandler, options, handlerName, beforeDispatch) {
     const requestParamsSnapshot = structuredClone(params);
     const taskOptionsSnapshot = snapshotTaskOptions(options);
-    return withTaskDeadline(taskOptionsSnapshot, async (effectiveOptions) => {
+    return this.withTaskConnectionScope(taskOptionsSnapshot, async (effectiveOptions) => {
       const result = await this.executeTaskUnprojectedWithinDeadline(
         taskName,
         requestParamsSnapshot,
@@ -7287,10 +7319,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * ```
    */
   async getAgentInfo(options) {
-    return withMCPConnectionPolicy(
-      normalizeTransportOptions(options?.transport ?? this.config.transport),
-      () => this.getAgentInfoWithConnectionPolicy(options)
-    );
+    return this.withConnectionScope(options, () => this.getAgentInfoWithConnectionPolicy(options));
   }
   async getAgentInfoWithConnectionPolicy(options) {
     throwIfAborted(options?.signal);
@@ -7541,10 +7570,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * ```
    */
   async getCapabilities(options) {
-    return withMCPConnectionPolicy(
-      normalizeTransportOptions(options?.transport ?? this.config.transport),
-      () => this.getCapabilitiesWithConnectionPolicy(options)
-    );
+    return this.withConnectionScope(options, () => this.getCapabilitiesWithConnectionPolicy(options));
   }
   async getCapabilitiesWithConnectionPolicy(options) {
     throwIfAborted(options?.signal);

package/dist/lib/core/TaskExecutor.js

@@ -292,7 +292,7 @@ function assertGovernedPayloadHasNoCallbackCredentials(taskName, payload, option
     scanResult.path
   );
 }
-function mapTasksGetResponseToTaskInfo(payload) {
+function mapTasksGetResponseToTaskInfo(payload, adcpVersion) {
   if (payload == null || typeof payload !== "object") {
     return { taskId: "", status: "unknown", taskType: "unknown", createdAt: Date.now(), updatedAt: Date.now() };
   }
@@ -312,7 +312,8 @@ function mapTasksGetResponseToTaskInfo(payload) {
   if (messageField !== void 0) taskInfo.message = messageField;
   if (flat.result !== void 0) {
     taskInfo.result = flat.result != null && typeof flat.result === "object" && !Array.isArray(flat.result) ? (0, import_envelope_status_compat.normalizeLegacyMediaBuyStatusForReturn)(flat.result, {
-      toolName: taskInfo.taskType
+      toolName: taskInfo.taskType,
+      adcpVersion
     }) : flat.result;
   }
   return taskInfo;
@@ -2554,7 +2555,8 @@ class TaskExecutor {
         }
       }
     );
-    const task = mapTasksGetResponseToTaskInfo(response);
+    const resultAdcpVersion = (versionEnvelope ?? this.config.versionEnvelope) === "major-only" ? "3.0" : wireAdcpVersion ?? this.config.wireAdcpVersion ?? this.config.adcpVersion ?? import_version.ADCP_VERSION;
+    const task = mapTasksGetResponseToTaskInfo(response, resultAdcpVersion);
     if (!task.taskId || task.taskId !== taskId) {
       throw new TaskBindingMismatchError(
         "tasks/get returned a task identity that does not match the requested task.",

package/dist/lib/core/TaskExecutor.mjs

@@ -278,7 +278,7 @@ function assertGovernedPayloadHasNoCallbackCredentials(taskName, payload, option
     scanResult.path
   );
 }
-function mapTasksGetResponseToTaskInfo(payload) {
+function mapTasksGetResponseToTaskInfo(payload, adcpVersion) {
   if (payload == null || typeof payload !== "object") {
     return { taskId: "", status: "unknown", taskType: "unknown", createdAt: Date.now(), updatedAt: Date.now() };
   }
@@ -298,7 +298,8 @@ function mapTasksGetResponseToTaskInfo(payload) {
   if (messageField !== void 0) taskInfo.message = messageField;
   if (flat.result !== void 0) {
     taskInfo.result = flat.result != null && typeof flat.result === "object" && !Array.isArray(flat.result) ? normalizeLegacyMediaBuyStatusForReturn(flat.result, {
-      toolName: taskInfo.taskType
+      toolName: taskInfo.taskType,
+      adcpVersion
     }) : flat.result;
   }
   return taskInfo;
@@ -2540,7 +2541,8 @@ class TaskExecutor {
         }
       }
     );
-    const task = mapTasksGetResponseToTaskInfo(response);
+    const resultAdcpVersion = (versionEnvelope ?? this.config.versionEnvelope) === "major-only" ? "3.0" : wireAdcpVersion ?? this.config.wireAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION;
+    const task = mapTasksGetResponseToTaskInfo(response, resultAdcpVersion);
     if (!task.taskId || task.taskId !== taskId) {
       throw new TaskBindingMismatchError(
         "tasks/get returned a task identity that does not match the requested task.",

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

@@ -410,6 +410,28 @@ export declare class ResponseTooLargeError extends ADCPError {
      */
     contentLengthHeader?: number | undefined);
 }
+/**
+ * Error thrown when an agent rate-limits the SDK's endpoint discovery: a
+ * probe answered HTTP 429, or HTTP 503 with a `Retry-After` header.
+ *
+ * Discovery stops at the first such probe instead of trying the remaining
+ * candidate URLs, which would only spend more of the seller's request budget.
+ * The rate limit says nothing about whether `agent_uri` is correct.
+ *
+ * Recovery: `transient`. Wait `retryAfterMs` (when the agent sent
+ * `Retry-After`) and retry.
+ */
+export declare class AgentRateLimitedError extends ADCPError {
+    readonly status: number;
+    readonly code = "RATE_LIMITED";
+    /** The probed URL, without credentials, query or fragment. */
+    readonly agentUrl: string;
+    /** `Retry-After` as the agent sent it. Set only when it is valid delta-seconds or an HTTP-date. */
+    readonly retryAfter?: string;
+    /** Delay from `Retry-After`, in milliseconds. */
+    readonly retryAfterMs?: number;
+    constructor(agentUrl: string, status: number, retryAfter?: string, cause?: unknown);
+}
 /**
  * Error thrown when an `update_media_buy` request is rejected because the
  * action it maps to isn't currently allowed on the buy (AdCP 3.1, RFC #4480).

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

@@ -410,6 +410,28 @@ export declare class ResponseTooLargeError extends ADCPError {
      */
     contentLengthHeader?: number | undefined);
 }
+/**
+ * Error thrown when an agent rate-limits the SDK's endpoint discovery: a
+ * probe answered HTTP 429, or HTTP 503 with a `Retry-After` header.
+ *
+ * Discovery stops at the first such probe instead of trying the remaining
+ * candidate URLs, which would only spend more of the seller's request budget.
+ * The rate limit says nothing about whether `agent_uri` is correct.
+ *
+ * Recovery: `transient`. Wait `retryAfterMs` (when the agent sent
+ * `Retry-After`) and retry.
+ */
+export declare class AgentRateLimitedError extends ADCPError {
+    readonly status: number;
+    readonly code = "RATE_LIMITED";
+    /** The probed URL, without credentials, query or fragment. */
+    readonly agentUrl: string;
+    /** `Retry-After` as the agent sent it. Set only when it is valid delta-seconds or an HTTP-date. */
+    readonly retryAfter?: string;
+    /** Delay from `Retry-After`, in milliseconds. */
+    readonly retryAfterMs?: number;
+    constructor(agentUrl: string, status: number, retryAfter?: string, cause?: unknown);
+}
 /**
  * Error thrown when an `update_media_buy` request is rejected because the
  * action it maps to isn't currently allowed on the buy (AdCP 3.1, RFC #4480).