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

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

@@ -95,6 +95,7 @@ interface WebhookManager {
     registerWebhook(agent: AgentConfig, taskId: string, webhookUrl: string): Promise<void>;
     processWebhook(token: string, body: any): Promise<void>;
 }
+type AdcpTaskStatusTool = 'get_task_status' | 'tasks_get' | 'tasks/get';
 /**
  * Core task execution engine that handles the conversation loop with agents
  */
@@ -210,6 +211,11 @@ export declare class TaskExecutor {
          * dispatches. Per-call options can override individual fields.
          */
         transport?: import('../protocols/index.mjs').TransportOptions;
+        /** Resolve the advertised AdCP work-status tool using the client's scoped discovery evidence. */
+        resolveTaskStatusTool?: (agent: AgentConfig, options: {
+            transport?: import('../protocols/index.mjs').TransportOptions;
+            signal?: AbortSignal;
+        }) => Promise<AdcpTaskStatusTool>;
     });
     /**
      * Access the governance middleware for direct outcome reporting (async tasks).
@@ -328,6 +334,7 @@ export declare class TaskExecutor {
      * Task tracking methods (PR #78)
      */
     listTasks(agent: AgentConfig, transport?: import('../protocols/index.mjs').TransportOptions): Promise<TaskInfo[]>;
+    private resolveTaskStatusTool;
     private getTaskStatusWithRawResponse;
     getTaskStatus(agent: AgentConfig, taskId: string, transport?: import('../protocols/index.mjs').TransportOptions, signal?: AbortSignal, wireOptions?: {
         wireAdcpVersion?: string;

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

@@ -95,6 +95,7 @@ interface WebhookManager {
     registerWebhook(agent: AgentConfig, taskId: string, webhookUrl: string): Promise<void>;
     processWebhook(token: string, body: any): Promise<void>;
 }
+type AdcpTaskStatusTool = 'get_task_status' | 'tasks_get' | 'tasks/get';
 /**
  * Core task execution engine that handles the conversation loop with agents
  */
@@ -210,6 +211,11 @@ export declare class TaskExecutor {
          * dispatches. Per-call options can override individual fields.
          */
         transport?: import('../protocols').TransportOptions;
+        /** Resolve the advertised AdCP work-status tool using the client's scoped discovery evidence. */
+        resolveTaskStatusTool?: (agent: AgentConfig, options: {
+            transport?: import('../protocols').TransportOptions;
+            signal?: AbortSignal;
+        }) => Promise<AdcpTaskStatusTool>;
     });
     /**
      * Access the governance middleware for direct outcome reporting (async tasks).
@@ -328,6 +334,7 @@ export declare class TaskExecutor {
      * Task tracking methods (PR #78)
      */
     listTasks(agent: AgentConfig, transport?: import('../protocols').TransportOptions): Promise<TaskInfo[]>;
+    private resolveTaskStatusTool;
     private getTaskStatusWithRawResponse;
     getTaskStatus(agent: AgentConfig, taskId: string, transport?: import('../protocols').TransportOptions, signal?: AbortSignal, wireOptions?: {
         wireAdcpVersion?: string;

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;
@@ -732,6 +733,8 @@ class TaskExecutor {
       status: args.status
     };
     const taskState = this.activeTasks.get(args.taskId);
+    const wireAdcpVersion = taskState?.wireAdcpVersion ?? this.config.wireAdcpVersion;
+    if (wireAdcpVersion !== void 0) meta.wireAdcpVersion = wireAdcpVersion;
     if (taskState?.serverVersion !== void 0) meta.serverVersion = taskState.serverVersion;
     if (taskState?.serverVersionSynthetic !== void 0) {
       meta.serverVersionSynthetic = taskState.serverVersionSynthetic;
@@ -825,6 +828,7 @@ class TaskExecutor {
     }
     const taskState = {
       taskId,
+      wireAdcpVersion: wireAdcpVersion ?? options.negotiatedAdcpVersion ?? options.selectedAdcpVersion,
       taskName,
       params,
       status: "pending",
@@ -1095,7 +1099,7 @@ class TaskExecutor {
         () => import_protocols.ProtocolClient.callTool(agent, taskName, dispatchParams, callOptions)
       );
       (0, import_abort.throwIfAborted)(postDispatchOptions.signal);
-      const respStatus = this.responseParser.getStatus(response);
+      const respStatus = this.responseParser.getStatus(response, taskName);
       taskState.serverTaskId = this.responseParser.getTaskId(response);
       await this.config.onActivity?.({
         type: "protocol_response",
@@ -1278,7 +1282,7 @@ class TaskExecutor {
     };
   }
   async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
-    const status = this.responseParser.getStatus(response);
+    const status = this.responseParser.getStatus(response, taskName);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
     if (task && serverTaskId) task.serverTaskId = serverTaskId;
@@ -2530,8 +2534,15 @@ class TaskExecutor {
       }
     });
   }
-  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId) {
-    const toolName = agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
+  async resolveTaskStatusTool(agent, transport, signal) {
+    if (this.config.resolveTaskStatusTool) {
+      return this.config.resolveTaskStatusTool(agent, { transport: transport ?? this.config.transport, signal });
+    }
+    return agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
+  }
+  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId, pollingTool) {
+    const toolName = pollingTool ?? await this.resolveTaskStatusTool(agent, transport, signal);
+    (0, import_abort.throwIfAborted)(signal);
     const response = await import_protocols.ProtocolClient.callTool(
       agent,
       toolName,
@@ -2554,7 +2565,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.",
@@ -2589,6 +2601,7 @@ class TaskExecutor {
     }
     const pollStartTime = Date.now();
     const correlationId = metadataTaskId ?? taskId;
+    let pollingTool;
     const withServerTaskId = (metadata) => ({
       ...metadata,
       serverTaskId: taskId
@@ -2629,6 +2642,7 @@ class TaskExecutor {
       let status;
       let rawResponse;
       try {
+        pollingTool ??= await this.resolveTaskStatusTool(agent, transportSnapshot, signal);
         const pollResult = await this.getTaskStatusWithRawResponse(
           agent,
           taskId,
@@ -2638,7 +2652,8 @@ class TaskExecutor {
           serverVersion,
           wireAdcpVersion,
           versionEnvelope,
-          metadataTaskId
+          metadataTaskId,
+          pollingTool
         );
         status = pollResult.task;
         rawResponse = pollResult.rawResponse;

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;
@@ -718,6 +719,8 @@ class TaskExecutor {
       status: args.status
     };
     const taskState = this.activeTasks.get(args.taskId);
+    const wireAdcpVersion = taskState?.wireAdcpVersion ?? this.config.wireAdcpVersion;
+    if (wireAdcpVersion !== void 0) meta.wireAdcpVersion = wireAdcpVersion;
     if (taskState?.serverVersion !== void 0) meta.serverVersion = taskState.serverVersion;
     if (taskState?.serverVersionSynthetic !== void 0) {
       meta.serverVersionSynthetic = taskState.serverVersionSynthetic;
@@ -811,6 +814,7 @@ class TaskExecutor {
     }
     const taskState = {
       taskId,
+      wireAdcpVersion: wireAdcpVersion ?? options.negotiatedAdcpVersion ?? options.selectedAdcpVersion,
       taskName,
       params,
       status: "pending",
@@ -1081,7 +1085,7 @@ class TaskExecutor {
         () => ProtocolClient.callTool(agent, taskName, dispatchParams, callOptions)
       );
       throwIfAborted(postDispatchOptions.signal);
-      const respStatus = this.responseParser.getStatus(response);
+      const respStatus = this.responseParser.getStatus(response, taskName);
       taskState.serverTaskId = this.responseParser.getTaskId(response);
       await this.config.onActivity?.({
         type: "protocol_response",
@@ -1264,7 +1268,7 @@ class TaskExecutor {
     };
   }
   async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
-    const status = this.responseParser.getStatus(response);
+    const status = this.responseParser.getStatus(response, taskName);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
     if (task && serverTaskId) task.serverTaskId = serverTaskId;
@@ -2516,8 +2520,15 @@ class TaskExecutor {
       }
     });
   }
-  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId) {
-    const toolName = agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
+  async resolveTaskStatusTool(agent, transport, signal) {
+    if (this.config.resolveTaskStatusTool) {
+      return this.config.resolveTaskStatusTool(agent, { transport: transport ?? this.config.transport, signal });
+    }
+    return agent.protocol === "mcp" ? "tasks_get" : "tasks/get";
+  }
+  async getTaskStatusWithRawResponse(agent, taskId, transport, signal, expectedTaskType, serverVersion, wireAdcpVersion, versionEnvelope, operationId, pollingTool) {
+    const toolName = pollingTool ?? await this.resolveTaskStatusTool(agent, transport, signal);
+    throwIfAborted(signal);
     const response = await ProtocolClient.callTool(
       agent,
       toolName,
@@ -2540,7 +2551,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.",
@@ -2575,6 +2587,7 @@ class TaskExecutor {
     }
     const pollStartTime = Date.now();
     const correlationId = metadataTaskId ?? taskId;
+    let pollingTool;
     const withServerTaskId = (metadata) => ({
       ...metadata,
       serverTaskId: taskId
@@ -2615,6 +2628,7 @@ class TaskExecutor {
       let status;
       let rawResponse;
       try {
+        pollingTool ??= await this.resolveTaskStatusTool(agent, transportSnapshot, signal);
         const pollResult = await this.getTaskStatusWithRawResponse(
           agent,
           taskId,
@@ -2624,7 +2638,8 @@ class TaskExecutor {
           serverVersion,
           wireAdcpVersion,
           versionEnvelope,
-          metadataTaskId
+          metadataTaskId,
+          pollingTool
         );
         status = pollResult.task;
         rawResponse = pollResult.rawResponse;

package/dist/lib/core/task-status.d.mts

@@ -31,3 +31,5 @@ export declare function extractAdcpTaskStatusFromPayload(payload: unknown): ADCP
  * back to the transport-layer status.
  */
 export declare function extractAdcpStatusFromA2aTaskResult(result: unknown): ADCPStatus | undefined;
+/** A status query describes another task; its status/error are data, not the query's lifecycle. */
+export declare function isTaskStatusResponse(value: unknown, toolName?: string): boolean;

package/dist/lib/core/task-status.d.ts

@@ -31,3 +31,5 @@ export declare function extractAdcpTaskStatusFromPayload(payload: unknown): ADCP
  * back to the transport-layer status.
  */
 export declare function extractAdcpStatusFromA2aTaskResult(result: unknown): ADCPStatus | undefined;
+/** A status query describes another task; its status/error are data, not the query's lifecycle. */
+export declare function isTaskStatusResponse(value: unknown, toolName?: string): boolean;

package/dist/lib/core/task-status.js

@@ -22,7 +22,8 @@ __export(task_status_exports, {
   TASK_ENVELOPE_FIELDS: () => TASK_ENVELOPE_FIELDS,
   extractAdcpStatusFromA2aTaskResult: () => extractAdcpStatusFromA2aTaskResult,
   extractAdcpTaskStatusFromPayload: () => extractAdcpTaskStatusFromPayload,
-  isAdcpStatus: () => isAdcpStatus
+  isAdcpStatus: () => isAdcpStatus,
+  isTaskStatusResponse: () => isTaskStatusResponse
 });
 module.exports = __toCommonJS(task_status_exports);
 var import_a2a_artifacts = require('../utils/a2a-artifacts.js');
@@ -80,11 +81,19 @@ function extractAdcpStatusFromA2aTaskResult(result) {
   const extracted = (0, import_a2a_artifacts.getLatestA2ADataPartFromTask)(result);
   return extractAdcpTaskStatusFromPayload(extracted?.data);
 }
+function isTaskStatusResponse(value, toolName) {
+  if (toolName !== "get_task_status" || !value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return ["task_id", "task_type", "protocol", "status", "created_at", "updated_at"].every(
+    (field) => typeof record[field] === "string"
+  ) && record.adcp_error === void 0 && record.errors === void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ADCP_STATUS,
   TASK_ENVELOPE_FIELDS,
   extractAdcpStatusFromA2aTaskResult,
   extractAdcpTaskStatusFromPayload,
-  isAdcpStatus
+  isAdcpStatus,
+  isTaskStatusResponse
 });

package/dist/lib/core/task-status.mjs

@@ -53,10 +53,18 @@ function extractAdcpStatusFromA2aTaskResult(result) {
   const extracted = getLatestA2ADataPartFromTask(result);
   return extractAdcpTaskStatusFromPayload(extracted?.data);
 }
+function isTaskStatusResponse(value, toolName) {
+  if (toolName !== "get_task_status" || !value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return ["task_id", "task_type", "protocol", "status", "created_at", "updated_at"].every(
+    (field) => typeof record[field] === "string"
+  ) && record.adcp_error === void 0 && record.errors === void 0;
+}
 export {
   ADCP_STATUS,
   TASK_ENVELOPE_FIELDS,
   extractAdcpStatusFromA2aTaskResult,
   extractAdcpTaskStatusFromPayload,
-  isAdcpStatus
+  isAdcpStatus,
+  isTaskStatusResponse
 };

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).

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/identity-3.3/trust.d.mts

@@ -149,10 +149,7 @@ export interface DemandGrantAuthorization {
 export interface DemandGrantOptions {
     evaluator: TrustEvaluator;
     now?: () => number;
-    /**
-     * Only evaluated for uncovered claims, never fetch failures, and never for a scope an
-     * `exclusive_grants: true` record names in any grant.
-     */
+    /** Only evaluated for uncovered claims against a record without `exclusive_grants: true`; never fetch failures. */
     sellerAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;
     /** Only for authoritative absence; never after a 200 or an exclusive record. */
     legacyAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;

package/dist/lib/identity-3.3/trust.d.ts

@@ -149,10 +149,7 @@ export interface DemandGrantAuthorization {
 export interface DemandGrantOptions {
     evaluator: TrustEvaluator;
     now?: () => number;
-    /**
-     * Only evaluated for uncovered claims, never fetch failures, and never for a scope an
-     * `exclusive_grants: true` record names in any grant.
-     */
+    /** Only evaluated for uncovered claims against a record without `exclusive_grants: true`; never fetch failures. */
     sellerAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;
     /** Only for authoritative absence; never after a 200 or an exclusive record. */
     legacyAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;

package/dist/lib/identity-3.3/trust.js

@@ -47,7 +47,7 @@ var import_etld = require('../signing/agent-resolver/etld.js');
 var import_strict_json = require('../signing/agent-resolver/strict-json.js');
 var import_tldts = require("tldts");
 var import_schemas = __toESM(require('./schemas.draft.js'));
-const ajv = new import_ajv.default({ strict: false, allErrors: false });
+const ajv = new import_ajv.default({ inlineRefs: false, strict: false, allErrors: false });
 (0, import_ajv_formats.default)(ajv);
 for (const schema of import_schemas.default) ajv.addSchema(schema);
 function validateIdentity33Schema(id, value) {
@@ -335,13 +335,16 @@ function authorityGroup(operator) {
   const provider = (0, import_tldts.parse)(operator).domain;
   return `private:${provider ?? operator}`;
 }
+const INTERMEDIARY_FETCH_CONCURRENCY = 8;
 function grantsScope(grant, scope) {
   return grant.scopes.some(
     (granted) => granted === "*" || granted === scope || granted === "adcp:all" && scope.startsWith("adcp:")
   );
 }
 function grantMatches(grant, target, claim, now) {
-  if (registrableGrantee(grant.grantee) !== target) return false;
+  return registrableGrantee(grant.grantee) === target && grantCovers(grant, claim, now);
+}
+function grantCovers(grant, claim, now) {
   if (!grantsScope(grant, claim.scope)) return false;
   if (grant.agents && !grant.agents.some((agent) => grantAgentOrigin(agent.url) === (0, import_canonicalize.canonicalAgentOrigin)(claim.signerOrigin)))
     return false;
@@ -367,7 +370,6 @@ async function authorizeDemandGrant(claim, options) {
     ...grants.some((g) => g.valid_until) ? { expiresAt: Math.min(...grants.map((g) => g.valid_until ? Date.parse(g.valid_until) / 1e3 : Infinity)) } : {}
   });
   if (brand === operator && account === operator) return result("implicit", [brand]);
-  if (brand === operator && account !== operator) throw new IdentityAuthorizationError("grant_absent");
   let house;
   try {
     house = await options.resolveBrandHouse?.(claim.brand);
@@ -377,33 +379,44 @@ async function authorizeDemandGrant(claim, options) {
     unavailable(cause);
   }
   const authoritativeBrand = house ? (0, import_etld.eTldPlusOne)(house.domain) : brand;
-  if (authoritativeBrand === operator && account === operator) return result("implicit", [brand, operator]);
+  const self = /* @__PURE__ */ new Set([brand, authoritativeBrand]);
+  if (self.has(account) && self.has(operator)) return result("implicit", [.../* @__PURE__ */ new Set([brand, account, operator])]);
   const grantClaim = house ? { ...claim, brand: { ...claim.brand, brand_id: house.brand_id } } : claim;
   const record = await options.evaluator.get(authoritativeBrand);
   if (record.status === "absent") {
     if (await options.legacyAuthorization?.(claim)) return result("legacy", [brand, account, operator]);
     throw new IdentityAuthorizationError("grant_absent");
   }
-  const first = (record.record.grants ?? []).filter((g) => grantMatches(g, account, grantClaim, now));
-  if (account === operator && first.length) return result("trust", [brand, operator], [first[0]]);
-  const selfOperated = account === brand || account === authoritativeBrand;
-  if (selfOperated && account !== operator) {
-    const direct = (record.record.grants ?? []).find((g) => grantMatches(g, operator, grantClaim, now));
-    if (direct) return result("trust", [brand, operator], [direct]);
+  const firsts = [];
+  for (const grant of record.record.grants ?? []) {
+    const grantee = registrableGrantee(grant.grantee);
+    if (grantee === void 0 || !grantCovers(grant, grantClaim, now)) continue;
+    if (!self.has(account) && account !== grantee) continue;
+    if (grantee === operator) return result("trust", [brand, operator], [grant]);
+    firsts.push({ grant, grantee });
+  }
+  const grantees = [...new Set(firsts.map((f) => f.grantee))];
+  const records = /* @__PURE__ */ new Map();
+  for (let i = 0; i < grantees.length; i += INTERMEDIARY_FETCH_CONCURRENCY) {
+    const batch = grantees.slice(i, i + INTERMEDIARY_FETCH_CONCURRENCY);
+    const settled = await Promise.allSettled(batch.map((grantee) => options.evaluator.get(grantee)));
+    settled.forEach(
+      (outcome, j) => records.set(batch[j], outcome.status === "fulfilled" ? outcome.value : { failed: outcome.reason })
+    );
   }
-  if (account !== operator && account !== brand && first.length) {
-    const intermediary = await options.evaluator.get(account);
-    if (intermediary.status === "present") {
-      const second = (intermediary.record.grants ?? []).find((g) => grantMatches(g, operator, grantClaim, now));
-      if (second) return result("trust", [brand, account, operator], [first[0], second]);
+  let outage;
+  for (const { grant: first, grantee } of firsts) {
+    const intermediary = records.get(grantee);
+    if ("failed" in intermediary) {
+      outage ??= intermediary.failed;
+      continue;
     }
+    if (intermediary.status !== "present") continue;
+    const second = (intermediary.record.grants ?? []).find((g) => grantMatches(g, operator, grantClaim, now));
+    if (second) return result("trust", [brand, grantee, operator], [first, second]);
   }
-  const covered = (record.record.grants ?? []).some((g) => {
-    const grantee = registrableGrantee(g.grantee);
-    return grantee !== void 0 && (grantee === account || selfOperated && grantee === operator) && grantsScope(g, claim.scope);
-  });
-  const exclusive = record.record.exclusive_grants === true && (record.record.grants ?? []).some((g) => grantsScope(g, claim.scope));
-  if (!covered && !exclusive && await options.sellerAuthorization?.(claim))
+  if (outage !== void 0) throw outage;
+  if (record.record.exclusive_grants !== true && await options.sellerAuthorization?.(claim))
     return result("seller", [brand, account, operator]);
   throw new IdentityAuthorizationError("grant_absent");
 }