@adcp/sdk 14.1.0 → 14.3.0

package/dist/lib/server/create-adcp-server.js

@@ -65,6 +65,7 @@ var import_envelope_status_compat = require('../utils/envelope-status-compat.js'
 var import_schema_validator = require('../validation/schema-validator.js');
 var import_sync_reporting_status_envelope = require('../validation/sync-reporting-status-envelope.js');
 var import_schema_errors = require('../validation/schema-errors.js');
+var import_diagnostic_limits = require('../validation/diagnostic-limits.js');
 var import_idempotency2 = require('./idempotency/index.js');
 var import_webhook_emitter = require('./webhook-emitter.js');
 var import_middleware = require('../signing/middleware.js');
@@ -2287,7 +2288,7 @@ function createAdcpServer(config) {
     const validationMode = effectiveRequestValidationMode(extra);
     const accountIssues = protocolTaskAccountExtensionIssues(params);
     const outcome = validationMode === "off" ? { valid: true, issues: [], schemaId: void 0 } : (0, import_schema_validator.validateRequest)(toolName, params, requestServedRelease(params)?.validationVersion ?? adcpVersion);
-    const issues = [...outcome.valid ? [] : outcome.issues, ...accountIssues];
+    const issues = [...accountIssues, ...outcome.valid ? [] : outcome.issues];
     if (issues.length === 0) return void 0;
     if (validationMode === "strict" || accountIssues.length > 0) {
       return (0, import_errors2.adcpError)(
@@ -2838,7 +2839,9 @@ function createAdcpServer(config) {
                 })
               );
             }
-            let issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter((i) => !(i.keyword === "required" && i.pointer === "/idempotency_key")) : outcome.issues;
+            let issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter(
+              (i) => !(i.keyword === "required" && i.pointer === "/idempotency_key" && !(0, import_diagnostic_limits.validationDiagnosticsTruncated)([i]))
+            ) : outcome.issues;
             if (toolName === "sync_accounts" && effectiveFrameworkRequestValidationMode === "strict") {
               const eventIssues = issues.filter(isAccountNotificationEventIssue);
               if (eventIssues.length > 0 && eventIssues.length === issues.length) {

package/dist/lib/server/create-adcp-server.mjs

@@ -98,6 +98,7 @@ import { STATUS_FREE_SYNC_RESPONSE_TOOLS } from "../utils/envelope-status-compat
 import { validateRequest, validateResponse, formatIssues } from "../validation/schema-validator.mjs";
 import { validateSyncReportingStatusEnvelope } from "../validation/sync-reporting-status-envelope.mjs";
 import { buildAdcpValidationErrorPayload } from "../validation/schema-errors.mjs";
+import { validationDiagnosticsTruncated } from "../validation/diagnostic-limits.mjs";
 import { hashPayload, IdempotencyClaimOwnershipError } from "./idempotency/index.mjs";
 import {
   createWebhookEmitter
@@ -2359,7 +2360,7 @@ function createAdcpServer(config) {
     const validationMode = effectiveRequestValidationMode(extra);
     const accountIssues = protocolTaskAccountExtensionIssues(params);
     const outcome = validationMode === "off" ? { valid: true, issues: [], schemaId: void 0 } : validateRequest(toolName, params, requestServedRelease(params)?.validationVersion ?? adcpVersion);
-    const issues = [...outcome.valid ? [] : outcome.issues, ...accountIssues];
+    const issues = [...accountIssues, ...outcome.valid ? [] : outcome.issues];
     if (issues.length === 0) return void 0;
     if (validationMode === "strict" || accountIssues.length > 0) {
       return adcpError(
@@ -2910,7 +2911,9 @@ function createAdcpServer(config) {
                 })
               );
             }
-            let issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter((i) => !(i.keyword === "required" && i.pointer === "/idempotency_key")) : outcome.issues;
+            let issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter(
+              (i) => !(i.keyword === "required" && i.pointer === "/idempotency_key" && !validationDiagnosticsTruncated([i]))
+            ) : outcome.issues;
             if (toolName === "sync_accounts" && effectiveFrameworkRequestValidationMode === "strict") {
               const eventIssues = issues.filter(isAccountNotificationEventIssue);
               if (eventIssues.length > 0 && eventIssues.length === issues.length) {

package/dist/lib/signing/agent-resolver/errors.d.mts

@@ -46,6 +46,8 @@ export interface AgentResolverErrorDetail {
 export declare class AgentResolverError extends Error {
     readonly code: AgentResolverErrorCode;
     readonly detail: AgentResolverErrorDetail;
+    /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
     readonly [ATTACKER_INFLUENCED]: ReadonlyArray<keyof AgentResolverErrorDetail>;
     constructor(code: AgentResolverErrorCode, message: string, detail?: AgentResolverErrorDetail, attackerInfluencedFields?: ReadonlyArray<keyof AgentResolverErrorDetail>);
 }

package/dist/lib/signing/agent-resolver/errors.d.ts

@@ -46,6 +46,8 @@ export interface AgentResolverErrorDetail {
 export declare class AgentResolverError extends Error {
     readonly code: AgentResolverErrorCode;
     readonly detail: AgentResolverErrorDetail;
+    /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
     readonly [ATTACKER_INFLUENCED]: ReadonlyArray<keyof AgentResolverErrorDetail>;
     constructor(code: AgentResolverErrorCode, message: string, detail?: AgentResolverErrorDetail, attackerInfluencedFields?: ReadonlyArray<keyof AgentResolverErrorDetail>);
 }

package/dist/lib/signing/agent-resolver/errors.js

@@ -23,16 +23,22 @@ __export(errors_exports, {
   attackerInfluencedFields: () => attackerInfluencedFields
 });
 module.exports = __toCommonJS(errors_exports);
+var import_fetch_helpers = require('./fetch-helpers.js');
+var import_enums = require('../../types/enums.generated.js');
 const ATTACKER_INFLUENCED = /* @__PURE__ */ Symbol.for("adcp.attacker-influenced");
 class AgentResolverError extends Error {
   code;
   detail;
+  /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+  recovery;
   [ATTACKER_INFLUENCED];
   constructor(code, message, detail = {}, attackerInfluencedFields2 = []) {
     super(message);
     this.name = "AgentResolverError";
     this.code = code;
     this.detail = detail;
+    const discovery = code === "request_signature_capabilities_unreachable" || code === "request_signature_brand_json_unreachable";
+    this.recovery = discovery && (0, import_fetch_helpers.isPermanentDiscoveryFailure)(detail) ? "terminal" : import_enums.RequestSigningErrorCodeMetadata[code].recovery;
     this[ATTACKER_INFLUENCED] = attackerInfluencedFields2;
   }
 }

package/dist/lib/signing/agent-resolver/errors.mjs

@@ -1,13 +1,19 @@
+import { isPermanentDiscoveryFailure } from "./fetch-helpers.mjs";
+import { RequestSigningErrorCodeMetadata } from "../../types/enums.generated.mjs";
 const ATTACKER_INFLUENCED = /* @__PURE__ */ Symbol.for("adcp.attacker-influenced");
 class AgentResolverError extends Error {
   code;
   detail;
+  /** Local, cause-aware recovery. Wire codes retain the protocol taxonomy. */
+  recovery;
   [ATTACKER_INFLUENCED];
   constructor(code, message, detail = {}, attackerInfluencedFields2 = []) {
     super(message);
     this.name = "AgentResolverError";
     this.code = code;
     this.detail = detail;
+    const discovery = code === "request_signature_capabilities_unreachable" || code === "request_signature_brand_json_unreachable";
+    this.recovery = discovery && isPermanentDiscoveryFailure(detail) ? "terminal" : RequestSigningErrorCodeMetadata[code].recovery;
     this[ATTACKER_INFLUENCED] = attackerInfluencedFields2;
   }
 }

package/dist/lib/signing/agent-resolver/fetch-helpers.d.mts

@@ -40,3 +40,12 @@ export declare function safeFetchJson(url: string, kind: FetchKind, options: {
     maxBodyBytes: number;
     lookup?: SsrfDnsLookup;
 }): Promise<SafeFetchJsonResult>;
+/** Coarse causes only: never expose messages, resolved addresses, or topology. */
+export declare function classifyDiscoveryFailure(error: unknown): {
+    dns_error: SafeFetchError['transport'];
+    http_status?: number;
+};
+export declare function isPermanentDiscoveryFailure(detail: {
+    dns_error?: string;
+    http_status?: number;
+}): boolean;

package/dist/lib/signing/agent-resolver/fetch-helpers.d.ts

@@ -40,3 +40,12 @@ export declare function safeFetchJson(url: string, kind: FetchKind, options: {
     maxBodyBytes: number;
     lookup?: SsrfDnsLookup;
 }): Promise<SafeFetchJsonResult>;
+/** Coarse causes only: never expose messages, resolved addresses, or topology. */
+export declare function classifyDiscoveryFailure(error: unknown): {
+    dns_error: SafeFetchError['transport'];
+    http_status?: number;
+};
+export declare function isPermanentDiscoveryFailure(detail: {
+    dns_error?: string;
+    http_status?: number;
+}): boolean;

package/dist/lib/signing/agent-resolver/fetch-helpers.js

@@ -24,10 +24,13 @@ __export(fetch_helpers_exports, {
   MAX_CAPABILITIES_BYTES: () => MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES: () => MAX_JWKS_BYTES,
   SafeFetchError: () => SafeFetchError,
+  classifyDiscoveryFailure: () => classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure: () => isPermanentDiscoveryFailure,
   safeFetchJson: () => safeFetchJson
 });
 module.exports = __toCommonJS(fetch_helpers_exports);
 var import_net = require('../../net/index.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
 var import_strict_json = require('./strict-json.js');
 const MAX_CAPABILITIES_BYTES = 65536;
 const MAX_BRAND_JSON_BYTES = 262144;
@@ -60,7 +63,11 @@ async function safeFetchJson(url, kind, options) {
     res = await (0, import_net.ssrfSafeFetch)(url, fetchOpts);
   } catch (err) {
     if (err instanceof import_net.SsrfRefusedError) {
-      throw new SafeFetchError(kind, "ssrf_refused", `${kind} fetch refused: ${err.code}`);
+      throw new SafeFetchError(
+        kind,
+        import_net.SSRF_TRANSIENT_CODES.has(err.code) ? err.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused",
+        `${kind} fetch refused: ${err.code}`
+      );
     }
     const message = err instanceof Error ? err.message : String(err);
     if (/abort|timed?\s*out/i.test(message)) {
@@ -88,6 +95,31 @@ async function safeFetchJson(url, kind, options) {
     fetchedAt: Math.floor(Date.now() / 1e3)
   };
 }
+function classifyDiscoveryFailure(error) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; error && typeof error === "object" && depth < 8 && !seen.has(error); depth++) {
+    seen.add(error);
+    if (error instanceof SafeFetchError)
+      return { dns_error: error.transport, ...error.httpStatus !== void 0 && { http_status: error.httpStatus } };
+    if (error instanceof import_agent_transport_fetch.AgentTransportPolicyError) return { dns_error: "ssrf_refused" };
+    if (error instanceof import_net.SsrfRefusedError)
+      return {
+        dns_error: import_net.SSRF_TRANSIENT_CODES.has(error.code) ? error.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused"
+      };
+    const obj = error;
+    const status = obj.httpStatus ?? obj.status ?? obj.statusCode;
+    if (typeof status === "number" && status >= 400 && status <= 599)
+      return { dns_error: "fetch_failed", http_status: status };
+    if (obj.code === "ENOTFOUND" || obj.code === "EAI_AGAIN") return { dns_error: "dns_error" };
+    if (obj.name === "AbortError" || obj.name === "TimeoutError" || obj.code === "ETIMEDOUT" || typeof obj.code === "string" && obj.code.startsWith("UND_ERR_") && obj.code.endsWith("_TIMEOUT"))
+      return { dns_error: "timeout" };
+    error = obj.cause;
+  }
+  return { dns_error: "fetch_failed" };
+}
+function isPermanentDiscoveryFailure(detail) {
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CONNECT_TIMEOUT_MS,
@@ -96,5 +128,7 @@ async function safeFetchJson(url, kind, options) {
   MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES,
   SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure,
   safeFetchJson
 });

package/dist/lib/signing/agent-resolver/fetch-helpers.mjs

@@ -1,4 +1,9 @@
-import { ssrfSafeFetch, SsrfRefusedError } from "../../net/index.mjs";
+import {
+  ssrfSafeFetch,
+  SsrfRefusedError,
+  SSRF_TRANSIENT_CODES
+} from "../../net/index.mjs";
+import { AgentTransportPolicyError } from "../../net/agent-transport-fetch.mjs";
 import { parseStrictJson, StrictJsonError } from "./strict-json.mjs";
 const MAX_CAPABILITIES_BYTES = 65536;
 const MAX_BRAND_JSON_BYTES = 262144;
@@ -31,7 +36,11 @@ async function safeFetchJson(url, kind, options) {
     res = await ssrfSafeFetch(url, fetchOpts);
   } catch (err) {
     if (err instanceof SsrfRefusedError) {
-      throw new SafeFetchError(kind, "ssrf_refused", `${kind} fetch refused: ${err.code}`);
+      throw new SafeFetchError(
+        kind,
+        SSRF_TRANSIENT_CODES.has(err.code) ? err.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused",
+        `${kind} fetch refused: ${err.code}`
+      );
     }
     const message = err instanceof Error ? err.message : String(err);
     if (/abort|timed?\s*out/i.test(message)) {
@@ -59,6 +68,31 @@ async function safeFetchJson(url, kind, options) {
     fetchedAt: Math.floor(Date.now() / 1e3)
   };
 }
+function classifyDiscoveryFailure(error) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; error && typeof error === "object" && depth < 8 && !seen.has(error); depth++) {
+    seen.add(error);
+    if (error instanceof SafeFetchError)
+      return { dns_error: error.transport, ...error.httpStatus !== void 0 && { http_status: error.httpStatus } };
+    if (error instanceof AgentTransportPolicyError) return { dns_error: "ssrf_refused" };
+    if (error instanceof SsrfRefusedError)
+      return {
+        dns_error: SSRF_TRANSIENT_CODES.has(error.code) ? error.code === "body_exceeds_limit" ? "body_cap" : "dns_error" : "ssrf_refused"
+      };
+    const obj = error;
+    const status = obj.httpStatus ?? obj.status ?? obj.statusCode;
+    if (typeof status === "number" && status >= 400 && status <= 599)
+      return { dns_error: "fetch_failed", http_status: status };
+    if (obj.code === "ENOTFOUND" || obj.code === "EAI_AGAIN") return { dns_error: "dns_error" };
+    if (obj.name === "AbortError" || obj.name === "TimeoutError" || obj.code === "ETIMEDOUT" || typeof obj.code === "string" && obj.code.startsWith("UND_ERR_") && obj.code.endsWith("_TIMEOUT"))
+      return { dns_error: "timeout" };
+    error = obj.cause;
+  }
+  return { dns_error: "fetch_failed" };
+}
+function isPermanentDiscoveryFailure(detail) {
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+}
 export {
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_TOTAL_TIMEOUT_MS,
@@ -66,5 +100,7 @@ export {
   MAX_CAPABILITIES_BYTES,
   MAX_JWKS_BYTES,
   SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure,
   safeFetchJson
 };

package/dist/lib/signing/agent-resolver/legacy-brand.js

@@ -42,7 +42,7 @@ async function fetchLegacyBrandJson(agentUrl, options) {
   } catch (err) {
     throw new import_fetch_helpers.SafeFetchError(
       "brand.json",
-      "fetch_failed",
+      (0, import_fetch_helpers.classifyDiscoveryFailure)(err).dns_error,
       err instanceof import_brand_jwks.BrandJsonResolverError && err.code === "invalid_body" ? "brand.json body failed strict-JSON parse" : "Legacy brand.json discovery failed",
       err instanceof import_brand_jwks.BrandJsonResolverError ? err.httpStatus : void 0
     );

package/dist/lib/signing/agent-resolver/legacy-brand.mjs

@@ -1,6 +1,6 @@
 import { fetchBrandJson, BrandJsonResolverError } from "../brand-jwks.mjs";
 import { eTldPlusOne } from "./etld.mjs";
-import { SafeFetchError } from "./fetch-helpers.mjs";
+import { SafeFetchError, classifyDiscoveryFailure } from "./fetch-helpers.mjs";
 async function fetchLegacyBrandJson(agentUrl, options) {
   const agent = new URL(agentUrl);
   let startUrl = `${agent.origin}/.well-known/brand.json`;
@@ -19,7 +19,7 @@ async function fetchLegacyBrandJson(agentUrl, options) {
   } catch (err) {
     throw new SafeFetchError(
       "brand.json",
-      "fetch_failed",
+      classifyDiscoveryFailure(err).dns_error,
       err instanceof BrandJsonResolverError && err.code === "invalid_body" ? "brand.json body failed strict-JSON parse" : "Legacy brand.json discovery failed",
       err instanceof BrandJsonResolverError ? err.httpStatus : void 0
     );

package/dist/lib/signing/agent-resolver/resolve-agent.d.mts

@@ -28,7 +28,7 @@
  *     `SsrfRefusedError` carries.
  */
 import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types.mjs';
-import type { SsrfDnsLookup } from '../../net/index.mjs';
+import { type SsrfDnsLookup } from '../../net/index.mjs';
 import { type ConsistencyResult } from './consistency.mjs';
 import { type AgentResolverErrorDetail } from './errors.mjs';
 import { type AgentEntry } from './select-agent.mjs';

package/dist/lib/signing/agent-resolver/resolve-agent.d.ts

@@ -28,7 +28,7 @@
  *     `SsrfRefusedError` carries.
  */
 import type { IdentityKeyOriginPurpose, IdentityPosture } from './capabilities-types';
-import type { SsrfDnsLookup } from '../../net';
+import { type SsrfDnsLookup } from '../../net';
 import { type ConsistencyResult } from './consistency';
 import { type AgentResolverErrorDetail } from './errors';
 import { type AgentEntry } from './select-agent';

package/dist/lib/signing/agent-resolver/resolve-agent.js

@@ -22,9 +22,12 @@ __export(resolve_agent_exports, {
 });
 module.exports = __toCommonJS(resolve_agent_exports);
 var import_tldts = require("tldts");
+var import_node_net = require("node:net");
 var import_protocols = require('../../protocols/index.js');
 var import_domain = require('../../brand/domain.js');
 var import_capabilities_types = require('./capabilities-types.js');
+var import_net = require('../../net/index.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
 var import_operator_authorization = require('./operator-authorization.js');
 var import_legacy_brand = require('./legacy-brand.js');
 var import_consistency = require('./consistency.js');
@@ -42,7 +45,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? import_fetch_helpers.MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? import_fetch_helpers.MAX_JWKS_BYTES;
-  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp");
+  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp", allowPrivateIp, timeoutMs);
   let capabilitiesPayload;
   let capabilitiesFetchedAt;
   try {
@@ -59,7 +62,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof import_fetch_helpers.SafeFetchError ? err.transport : "fetch_failed",
+      ...(0, import_fetch_helpers.classifyDiscoveryFailure)(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -368,10 +371,49 @@ function checkAllowPrivateIp(requested) {
     "resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an explicit ops acknowledgment if you genuinely need private-IP discovery in this process."
   );
 }
-function defaultFetchCapabilities(agentUrl, protocol) {
+function defaultFetchCapabilities(agentUrl, protocol, allowPrivateIp, timeoutMs) {
   return async () => {
-    const client = protocol === "a2a" ? (0, import_protocols.createA2AClient)(agentUrl) : (0, import_protocols.createMCPClient)(agentUrl);
-    return client.callTool("get_adcp_capabilities", {});
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || (0, import_node_net.isIP)(hostname) && ((0, import_net.isAlwaysBlocked)(hostname) || !allowPrivateIp && (0, import_net.isPrivateIp)(hostname)))
+      throw new import_agent_transport_fetch.AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = (0, import_agent_transport_fetch.createAgentTransportFetch)(agentUrl, {
+      allowPrivateIp,
+      allowPrivateInitialOrigin: false,
+      requireHttps: true
+    });
+    let postSucceeded = false;
+    const trustedFetchFn = async (input, init) => {
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      try {
+        const response = await upstream(input, init);
+        const isGet = method.toUpperCase() === "GET";
+        const observed = response.status >= 400 ? { dns_error: "fetch_failed", http_status: response.status } : void 0;
+        if (protocol === "mcp" && method.toUpperCase() === "POST" && response.ok) postSucceeded = true;
+        if (!(protocol === "mcp" && isGet && (postSucceeded || response.status === 405)) && !(isGet && observed && failure && !(0, import_fetch_helpers.isPermanentDiscoveryFailure)(failure) && (0, import_fetch_helpers.isPermanentDiscoveryFailure)(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = (0, import_fetch_helpers.classifyDiscoveryFailure)(error);
+        throw error;
+      }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? (0, import_protocols.createA2AClient)(agentUrl, void 0, void 0, void 0, void 0, transport) : (0, import_protocols.createMCPClient)(agentUrl, void 0, void 0, void 0, void 0, transport);
+    try {
+      return await client.callTool("get_adcp_capabilities", {});
+    } catch (error) {
+      if (failure)
+        throw new import_fetch_helpers.SafeFetchError(
+          "capabilities",
+          failure.dns_error,
+          "Capabilities fetch failed",
+          failure.http_status
+        );
+      throw error;
+    }
   };
 }
 function findAuthorizedOperator(brandJson, agentEtld1, _now, _options) {

package/dist/lib/signing/agent-resolver/resolve-agent.mjs

@@ -1,7 +1,10 @@
 import { parse as parseTld } from "tldts";
+import { isIP } from "node:net";
 import { createA2AClient, createMCPClient } from "../../protocols/index.mjs";
 import { isDevelopmentBrandDomain } from "../../brand/domain.mjs";
 import { readBrandJsonUrl, readIdentityPosture } from "./capabilities-types.mjs";
+import { isAlwaysBlocked, isPrivateIp } from "../../net/index.mjs";
+import { AgentTransportPolicyError, createAgentTransportFetch } from "../../net/agent-transport-fetch.mjs";
 import { checkDelegatedOperatorAuthorization } from "./operator-authorization.mjs";
 import { fetchLegacyBrandJson } from "./legacy-brand.mjs";
 import {
@@ -11,7 +14,14 @@ import {
 } from "./consistency.mjs";
 import { AgentResolverError } from "./errors.mjs";
 import { eTldPlusOne, sameEtldPlusOne } from "./etld.mjs";
-import { MAX_BRAND_JSON_BYTES, MAX_JWKS_BYTES, safeFetchJson, SafeFetchError } from "./fetch-helpers.mjs";
+import {
+  MAX_BRAND_JSON_BYTES,
+  MAX_JWKS_BYTES,
+  safeFetchJson,
+  SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure
+} from "./fetch-helpers.mjs";
 import { unwrapProtocolResponse } from "../protocol-response.mjs";
 import { selectAgentByUrl, agentJwksUri, AgentSelectorError, canonicalAgentUrl } from "./select-agent.mjs";
 const DEFAULT_TIMEOUT_MS = 1e4;
@@ -23,7 +33,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? MAX_JWKS_BYTES;
-  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp");
+  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp", allowPrivateIp, timeoutMs);
   let capabilitiesPayload;
   let capabilitiesFetchedAt;
   try {
@@ -40,7 +50,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof SafeFetchError ? err.transport : "fetch_failed",
+      ...classifyDiscoveryFailure(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -349,10 +359,49 @@ function checkAllowPrivateIp(requested) {
     "resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an explicit ops acknowledgment if you genuinely need private-IP discovery in this process."
   );
 }
-function defaultFetchCapabilities(agentUrl, protocol) {
+function defaultFetchCapabilities(agentUrl, protocol, allowPrivateIp, timeoutMs) {
   return async () => {
-    const client = protocol === "a2a" ? createA2AClient(agentUrl) : createMCPClient(agentUrl);
-    return client.callTool("get_adcp_capabilities", {});
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || isIP(hostname) && (isAlwaysBlocked(hostname) || !allowPrivateIp && isPrivateIp(hostname)))
+      throw new AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = createAgentTransportFetch(agentUrl, {
+      allowPrivateIp,
+      allowPrivateInitialOrigin: false,
+      requireHttps: true
+    });
+    let postSucceeded = false;
+    const trustedFetchFn = async (input, init) => {
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      try {
+        const response = await upstream(input, init);
+        const isGet = method.toUpperCase() === "GET";
+        const observed = response.status >= 400 ? { dns_error: "fetch_failed", http_status: response.status } : void 0;
+        if (protocol === "mcp" && method.toUpperCase() === "POST" && response.ok) postSucceeded = true;
+        if (!(protocol === "mcp" && isGet && (postSucceeded || response.status === 405)) && !(isGet && observed && failure && !isPermanentDiscoveryFailure(failure) && isPermanentDiscoveryFailure(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = classifyDiscoveryFailure(error);
+        throw error;
+      }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? createA2AClient(agentUrl, void 0, void 0, void 0, void 0, transport) : createMCPClient(agentUrl, void 0, void 0, void 0, void 0, transport);
+    try {
+      return await client.callTool("get_adcp_capabilities", {});
+    } catch (error) {
+      if (failure)
+        throw new SafeFetchError(
+          "capabilities",
+          failure.dns_error,
+          "Capabilities fetch failed",
+          failure.http_status
+        );
+      throw error;
+    }
   };
 }
 function findAuthorizedOperator(brandJson, agentEtld1, _now, _options) {

package/dist/lib/signing/brand-jwks.d.mts

@@ -14,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -79,6 +80,7 @@ export declare class BrandJsonJwksResolver implements JwksResolver {
     private resolver?;
     private onboarding?;
     private lastOnboardingAttempt;
+    private lastOnboardingError?;
     constructor(brandJsonUrl: string, options: BrandJsonJwksResolverOptions);
     private createResolver;
     private confirmedResolver;

package/dist/lib/signing/brand-jwks.d.ts

@@ -14,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -79,6 +80,7 @@ export declare class BrandJsonJwksResolver implements JwksResolver {
     private resolver?;
     private onboarding?;
     private lastOnboardingAttempt;
+    private lastOnboardingError?;
     constructor(brandJsonUrl: string, options: BrandJsonJwksResolverOptions);
     private createResolver;
     private confirmedResolver;

package/dist/lib/signing/brand-jwks.js

@@ -23,12 +23,14 @@ __export(brand_jwks_exports, {
   fetchBrandJson: () => fetchBrandJson
 });
 module.exports = __toCommonJS(brand_jwks_exports);
+var import_fetch_helpers = require('./agent-resolver/fetch-helpers.js');
 var import_net = require('../net/index.js');
 var import_resolved_agent_jwks = require('./agent-resolver/resolved-agent-jwks.js');
 var import_strict_json = require('./agent-resolver/strict-json.js');
 var import_select_agent = require('./agent-resolver/select-agent.js');
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -38,6 +40,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || (0, import_fetch_helpers.isPermanentDiscoveryFailure)((0, import_fetch_helpers.classifyDiscoveryFailure)(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -63,6 +66,7 @@ class BrandJsonJwksResolver {
   resolver;
   onboarding;
   lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
   createResolver(agentUrl, operatorUrl) {
     const options = this.options;
     return new import_resolved_agent_jwks.ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
@@ -86,7 +90,7 @@ class BrandJsonJwksResolver {
     if (this.onboarding) return this.onboarding;
     const now = this.options.now?.() ?? Date.now() / 1e3;
     if (now - this.lastOnboardingAttempt < 30)
-      throw new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
     this.lastOnboardingAttempt = now;
     this.onboarding = (async () => {
       const record = await fetchBrandJson({
@@ -99,8 +103,12 @@ class BrandJsonJwksResolver {
       const resolver = this.createResolver(agentUrl, record.finalUrl);
       await resolver.forceRefresh();
       this.resolver = resolver;
+      this.lastOnboardingError = void 0;
       return resolver;
-    })().finally(() => {
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
       this.onboarding = void 0;
     });
     return this.onboarding;

package/dist/lib/signing/brand-jwks.mjs

@@ -1,9 +1,11 @@
+import { classifyDiscoveryFailure, isPermanentDiscoveryFailure } from "./agent-resolver/fetch-helpers.mjs";
 import { ssrfSafeFetch } from "../net/index.mjs";
 import { ResolvedAgentJwksResolver } from "./agent-resolver/resolved-agent-jwks.mjs";
 import { parseStrictJson } from "./agent-resolver/strict-json.mjs";
 import { canonicalAgentUrl } from "./agent-resolver/select-agent.mjs";
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -13,6 +15,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || isPermanentDiscoveryFailure(classifyDiscoveryFailure(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -38,6 +41,7 @@ class BrandJsonJwksResolver {
   resolver;
   onboarding;
   lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
   createResolver(agentUrl, operatorUrl) {
     const options = this.options;
     return new ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
@@ -61,7 +65,7 @@ class BrandJsonJwksResolver {
     if (this.onboarding) return this.onboarding;
     const now = this.options.now?.() ?? Date.now() / 1e3;
     if (now - this.lastOnboardingAttempt < 30)
-      throw new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
     this.lastOnboardingAttempt = now;
     this.onboarding = (async () => {
       const record = await fetchBrandJson({
@@ -74,8 +78,12 @@ class BrandJsonJwksResolver {
       const resolver = this.createResolver(agentUrl, record.finalUrl);
       await resolver.forceRefresh();
       this.resolver = resolver;
+      this.lastOnboardingError = void 0;
       return resolver;
-    })().finally(() => {
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
       this.onboarding = void 0;
     });
     return this.onboarding;