@adcp/sdk 15.4.0 → 15.5.0

package/dist/lib/core/SingleAgentClient.mjs

@@ -43,6 +43,7 @@ import { withTaskDeadline } from "./task-deadline.mjs";
 import { createMCPRequestHeaders } from "../auth/index.mjs";
 import { isAbortOrTimeoutError } from "../protocols/abort.mjs";
 import { getSignedRequestRejection } from "../protocols/signedRequestRejection.mjs";
+import { withAmbientIdentityHeaders } from "../protocols/mcp-call-context.mjs";
 import { ProtocolClient, normalizeTransportOptions } from "../protocols/index.mjs";
 import {
   AuthenticationCredentialsRejectedError,
@@ -113,6 +114,12 @@ function presentedStaticTransportCredential(authToken, headers, authProvider) {
     return normalized === "authorization" || normalized === "x-adcp-auth";
   });
 }
+import {
+  agentDiscoveryCacheKey,
+  MAX_AGENT_DISCOVERY_TTL_MS,
+  resolveAgentDiscoveryTtlMs,
+  validateAgentDiscoveryCacheConfig
+} from "./agent-discovery-cache.mjs";
 import {
   buildSyntheticCapabilities,
   buildSyntheticV3Capabilities,
@@ -726,6 +733,30 @@ const DURABLE_SETTLEMENT_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "aborted"
 ]);
 const MCP_WEBHOOK_REQUIRED_FIELDS = ["idempotency_key", "task_id", "task_type", "status", "timestamp"];
+const sharedInvalidations = /* @__PURE__ */ new WeakMap();
+const sharedInvalidationFloors = /* @__PURE__ */ new WeakMap();
+let sharedInvalidationCounter = 0;
+const MAX_SHARED_INVALIDATION_RECORDS = 1024;
+const sharedMutationChains = /* @__PURE__ */ new WeakMap();
+const MAX_PENDING_SHARED_MUTATIONS_PER_KEY = 16;
+const MAX_SHARED_MUTATION_KEYS = 1024;
+const sharedDiscoveryFlights = /* @__PURE__ */ new WeakMap();
+const MAX_SHARED_DISCOVERY_WAITS = 3;
+const SHARED_DISCOVERY_CACHE_TIMEOUT_MS = 2e3;
+const SHARED_DISCOVERY_CLOCK_SKEW_MS = 5e3;
+const CAPABILITY_STALE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "VERSION_UNSUPPORTED",
+  "UNSUPPORTED_FEATURE",
+  "FEATURE_UNSUPPORTED",
+  "TOOL_NOT_FOUND",
+  "METHOD_NOT_FOUND",
+  "UNKNOWN_TOOL"
+]);
+function isToolSchemaRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every(
+    (properties) => typeof properties === "object" && properties !== null && !Array.isArray(properties)
+  );
+}
 function isCapabilityEvidence(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const candidate = value;
@@ -823,6 +854,7 @@ class SingleAgentClient {
       ...configuredWebhookVerification !== void 0 && { webhookVerification: configuredWebhookVerification }
     };
     config = this.config;
+    validateAgentDiscoveryCacheConfig(config.discoveryCache);
     this.resolvedAdcpVersion = resolveAdcpVersion(config.adcpVersion);
     this.webhookRegistrationStore = config.webhookRegistrationStore ?? new InMemoryWebhookRegistrationStore();
     this.webhookReplayStore = config.webhookVerification?.replayStore ?? new InMemoryReplayStore();
@@ -1101,6 +1133,20 @@ class SingleAgentClient {
   // Freshness bound for application-owned evidence only
   capabilityEvidenceScopeKey = randomUUID();
   capabilityEvidenceAuthMaterial;
+  capabilitiesFromSharedCache = false;
+  // Installed from config.discoveryCache rather than discovered live
+  discoveryEpoch = 0;
+  // bumped by invalidation so an older in-flight discovery cannot re-install what was dropped
+  discoveredEndpointKey;
+  // discoveryCache key the local endpoint was obtained under
+  discoveredEndpointEpoch;
+  // shared invalidation epoch of that key when the endpoint was obtained
+  discoveredEndpointExpiresAt;
+  // freshness bound for that endpoint (shared-cache mode only)
+  sharedEvidenceEpoch;
+  // shared invalidation epoch of that key when the evidence was obtained
+  sharedEvidenceKey;
+  // discoveryCache key the local capability cache was obtained under
   _v2WarningFired = false;
   // Gate: emit the v2-sunset warning once per client instance
   _syntheticV3WarningFired = false;
@@ -1772,19 +1818,34 @@ class SingleAgentClient {
     if (!needsDiscovery) {
       return this.normalizedAgent;
     }
+    const effectiveEndpointKey = this.config.discoveryCache && !usesScopedFetch && this.discoveredEndpoint ? this.sharedDiscoveryKey(options) : void 0;
+    if (this.config.discoveryCache && !usesScopedFetch && this.discoveredEndpoint && (this.discoveredEndpointKey !== effectiveEndpointKey || effectiveEndpointKey !== void 0 && this.discoveredEndpointEpoch !== this.sharedInvalidationEpoch(effectiveEndpointKey) || (this.discoveredEndpointExpiresAt ?? 0) <= Date.now())) {
+      this.discoveredEndpoint = void 0;
+      this.discoveredAgent = void 0;
+      this.discoveredMcpEra = void 0;
+    }
     if (!usesScopedFetch && this.discoveredAgent) {
       return this.discoveredAgent;
     }
+    if (!usesScopedFetch && !this.discoveredEndpoint && this.config.discoveryCache) {
+      await this.adoptSharedEndpoint(options);
+      if (this.discoveredEndpoint && (this.discoveredEndpointEpoch !== this.sharedInvalidationEpoch(this.sharedDiscoveryKey(options)) || (this.discoveredEndpointExpiresAt ?? 0) <= Date.now())) {
+        this.discoveredEndpoint = void 0;
+        this.discoveredAgent = void 0;
+        this.discoveredMcpEra = void 0;
+      }
+    }
     if (!usesScopedFetch && this.discoveredEndpoint) {
-      this.discoveredAgent = {
+      const adoptedAgent = {
         ...this.normalizedAgent,
         agent_uri: this.discoveredEndpoint
       };
+      this.discoveredAgent = adoptedAgent;
       if (this.normalizedAgent.oauth_tokens && !this.normalizedAgent.oauth_client_credentials) {
         const { shareNonInteractiveOAuthProvider } = await import("../auth/oauth/provider-cache.mjs");
-        shareNonInteractiveOAuthProvider(this.normalizedAgent, this.discoveredAgent);
+        shareNonInteractiveOAuthProvider(this.normalizedAgent, adoptedAgent);
       }
-      return this.discoveredAgent;
+      return adoptedAgent;
     }
     if (this.normalizedAgent.oauth_client_credentials) {
       const { ensureClientCredentialsTokens, getAgentStorage } = await import("../auth/oauth/index.mjs");
@@ -1795,26 +1856,59 @@ class SingleAgentClient {
         signal: options?.signal
       });
     }
+    const endpointEpoch = this.discoveryEpochSnapshot(options);
     const discoveredEndpoint = await this.discoverMCPEndpoint(this.normalizedAgent.agent_uri, options);
     if (usesScopedFetch) {
-      const discoveredAgent = { ...this.normalizedAgent, agent_uri: discoveredEndpoint };
+      const discoveredAgent2 = { ...this.normalizedAgent, agent_uri: discoveredEndpoint };
       if (this.normalizedAgent.oauth_tokens && !this.normalizedAgent.oauth_client_credentials) {
         const { shareNonInteractiveOAuthProvider } = await import("../auth/oauth/provider-cache.mjs");
-        shareNonInteractiveOAuthProvider(this.normalizedAgent, discoveredAgent);
+        shareNonInteractiveOAuthProvider(this.normalizedAgent, discoveredAgent2);
       }
-      return discoveredAgent;
+      return discoveredAgent2;
+    }
+    if (endpointEpoch && !this.discoveryEpochIs(endpointEpoch)) {
+      return { ...this.normalizedAgent, agent_uri: discoveredEndpoint };
     }
     this.discoveredEndpoint = discoveredEndpoint;
-    this.canonicalBaseUrl = this.computeBaseUrl(this.discoveredEndpoint);
-    this.discoveredAgent = {
+    if (this.config.discoveryCache) {
+      this.discoveredEndpointKey = this.sharedDiscoveryKey(options);
+      this.discoveredEndpointEpoch = endpointEpoch?.shared;
+      this.discoveredEndpointExpiresAt = Date.now() + resolveAgentDiscoveryTtlMs(this.config.discoveryCache.ttlMs);
+      const stored = await this.writeSharedDiscovery(
+        options,
+        {
+          endpoint: {
+            agentUri: discoveredEndpoint,
+            ...this.discoveredMcpEra && { mcpEra: this.discoveredMcpEra }
+          }
+        },
+        false,
+        endpointEpoch
+      );
+      if (endpointEpoch && !this.discoveryEpochIs(endpointEpoch)) {
+        if (this.discoveredEndpoint === discoveredEndpoint && this.discoveredEndpointEpoch === endpointEpoch.shared) {
+          this.discoveredEndpoint = void 0;
+          this.discoveredEndpointKey = void 0;
+          this.discoveredEndpointEpoch = void 0;
+          this.discoveredEndpointExpiresAt = void 0;
+          if (this.discoveredAgent?.agent_uri === discoveredEndpoint) this.discoveredAgent = void 0;
+          this.discoveredMcpEra = void 0;
+        }
+        return { ...this.normalizedAgent, agent_uri: discoveredEndpoint };
+      }
+      if (stored && this.discoveredEndpoint === discoveredEndpoint) this.discoveredEndpointExpiresAt = stored.expiresAt;
+    }
+    this.canonicalBaseUrl = this.computeBaseUrl(discoveredEndpoint);
+    const discoveredAgent = {
       ...this.normalizedAgent,
-      agent_uri: this.discoveredEndpoint
+      agent_uri: discoveredEndpoint
     };
+    this.discoveredAgent = discoveredAgent;
     if (this.normalizedAgent.oauth_tokens && !this.normalizedAgent.oauth_client_credentials) {
       const { shareNonInteractiveOAuthProvider } = await import("../auth/oauth/provider-cache.mjs");
-      shareNonInteractiveOAuthProvider(this.normalizedAgent, this.discoveredAgent);
+      shareNonInteractiveOAuthProvider(this.normalizedAgent, discoveredAgent);
     }
-    return this.discoveredAgent;
+    return discoveredAgent;
   }
   /**
    * Ensure A2A canonical URL is resolved (lazy initialization)
@@ -3284,6 +3378,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       )
     );
     throwIfAborted(effectiveOptions?.signal);
+    if (!result.success) await this.invalidateDiscoveryOnCapabilityError(result.adcpError?.code, effectiveOptions);
     const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
     if (postAdapterLogs.length > 0) {
       result.debug_logs = [...result.debug_logs ?? [], ...postAdapterLogs];
@@ -5792,6 +5887,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         beforeDispatch,
         deferredClientContext
       );
+      if (!result.success) await this.invalidateDiscoveryOnCapabilityError(result.adcpError?.code, effectiveOptions);
       const postAdapterLogs = [...inputSchemaStripLogs, ...v25DriftLogs];
       if (postAdapterLogs.length > 0) {
         result.debug_logs = [...result.debug_logs ?? [], ...postAdapterLogs];
@@ -6357,6 +6453,26 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           tools
         };
       }
+      const { withScopedLegacyConnection } = await import("../protocols/mcp.mjs");
+      const scopedList = await withScopedLegacyConnection(
+        connectOptions,
+        "tools/list",
+        (client) => withResponseSizeLimit(maxResponseBytes, () => client.listTools(mcpListParams, mcpRequestOptions))
+      );
+      if (scopedList) {
+        return {
+          name: this.normalizedAgent.name,
+          description: void 0,
+          protocol: this.normalizedAgent.protocol,
+          url: agent.agent_uri,
+          tools: scopedList.value.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            parameters: tool.inputSchema?.properties ? Object.keys(tool.inputSchema.properties) : []
+          }))
+        };
+      }
       const { client: mcpClient } = await connectMCP(connectOptions);
       try {
         const toolsList = await withResponseSizeLimit(
@@ -6470,12 +6586,98 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       this.cachedCapabilities = void 0;
       this.cachedToolSchemas = void 0;
       this.primedCapabilitiesExpiresAt = void 0;
+      this.capabilitiesFromSharedCache = false;
+    }
+    const effectiveSharedKey = this.config.discoveryCache && !usesScopedFetch && this.cachedCapabilities ? this.sharedDiscoveryKey(options) : void 0;
+    if (this.config.discoveryCache && !usesScopedFetch && this.cachedCapabilities && (this.sharedEvidenceKey !== effectiveSharedKey || effectiveSharedKey !== void 0 && this.sharedEvidenceEpoch !== void 0 && this.sharedEvidenceEpoch !== this.sharedInvalidationEpoch(effectiveSharedKey))) {
+      this.cachedCapabilities = void 0;
+      this.cachedToolSchemas = void 0;
+      this.primedCapabilitiesExpiresAt = void 0;
+      this.capabilitiesFromSharedCache = false;
     }
     if (!usesScopedFetch && this.cachedCapabilities) {
       if (discoveryContext) discoveryContext.toolSchemas = this.cachedToolSchemas;
       this.maybeWarnV2Sunset(this.cachedCapabilities);
       return this.cachedCapabilities;
     }
+    if (!usesScopedFetch && this.config.discoveryCache) {
+      return this.discoverCapabilitiesThroughSharedCache(options, usesScopedFetch, discoveryContext);
+    }
+    return this.discoverCapabilitiesLive(options, usesScopedFetch, discoveryContext);
+  }
+  /**
+   * Serve capabilities from the shared `discoveryCache`, or discover them live
+   * as the single in-process "leader" for this cache key. Concurrent clients
+   * for the same key wait for the leader under their *own* signal and deadline;
+   * a leader that fails or is cancelled never fails its followers, which then
+   * discover for themselves.
+   */
+  async discoverCapabilitiesThroughSharedCache(options, usesScopedFetch, discoveryContext) {
+    const config = this.config.discoveryCache;
+    const key = this.sharedDiscoveryKey(options);
+    if (!key) return this.discoverCapabilitiesLive(options, usesScopedFetch, discoveryContext);
+    let flights = sharedDiscoveryFlights.get(config.cache);
+    if (!flights) {
+      flights = /* @__PURE__ */ new Map();
+      sharedDiscoveryFlights.set(config.cache, flights);
+    }
+    for (let attempt = 0; ; attempt++) {
+      const readEpoch = this.discoveryEpochSnapshot(options);
+      const entry = await this.readSharedDiscovery(options);
+      const installed = entry && (!readEpoch || this.discoveryEpochIs(readEpoch)) && this.installSharedCapabilities(entry, key, discoveryContext);
+      if (installed) return installed;
+      const flight = flights.get(key);
+      if (flight && attempt < MAX_SHARED_DISCOVERY_WAITS) {
+        const requestTimeoutMs = resolveRequestTimeoutMs(
+          options?.transport?.requestTimeoutMs ?? this.config.transport?.requestTimeoutMs
+        );
+        await withAbortSignal([options?.signal], requestTimeoutMs, () => flight);
+        continue;
+      }
+      let finish;
+      const mine = new Promise((resolve) => finish = resolve);
+      const ownsFlight = !flights.has(key);
+      if (ownsFlight) flights.set(key, mine);
+      try {
+        return await this.discoverCapabilitiesLive(options, usesScopedFetch, discoveryContext);
+      } finally {
+        if (ownsFlight) {
+          flights.delete(key);
+        }
+        finish();
+      }
+    }
+  }
+  /** Install capabilities from a shared entry; `undefined` when the entry is not usable evidence. */
+  installSharedCapabilities(entry, key, discoveryContext) {
+    const capabilities = entry.capabilities;
+    if (!isCapabilityEvidence(capabilities) || capabilities._synthetic) return void 0;
+    const toolSchemas = entry.toolSchemas;
+    const hasToolEvidence = toolSchemas !== void 0 || Array.isArray(capabilities.discoveredTools);
+    if (!hasToolEvidence) return void 0;
+    if (toolSchemas !== void 0 && !isToolSchemaRecord(toolSchemas)) {
+      return void 0;
+    }
+    let installed;
+    let schemas;
+    try {
+      installed = structuredClone(capabilities);
+      schemas = toolSchemas ? new Map(Object.entries(toolSchemas).map(([tool, properties]) => [tool, structuredClone(properties)])) : void 0;
+    } catch {
+      return void 0;
+    }
+    this.cachedCapabilities = installed;
+    this.cachedToolSchemas = schemas;
+    this.primedCapabilitiesExpiresAt = entry.expiresAt;
+    this.capabilitiesFromSharedCache = true;
+    this.recordSharedEvidence(key);
+    if (discoveryContext) discoveryContext.toolSchemas = this.cachedToolSchemas;
+    this.maybeWarnV2Sunset(installed);
+    return installed;
+  }
+  async discoverCapabilitiesLive(options, usesScopedFetch, discoveryContext) {
+    const startedAtEpoch = this.discoveryEpochSnapshot(options);
+    const superseded = () => startedAtEpoch !== void 0 && !this.discoveryEpochIs(startedAtEpoch);
     const agentInfo = await this.getAgentInfo(options);
     const tools = agentInfo.tools.map((t) => ({
       name: t.name,
@@ -6485,7 +6687,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       agentInfo.tools.filter((t) => t.inputSchema?.properties).map((t) => [t.name, t.inputSchema.properties])
     );
     if (discoveryContext) discoveryContext.toolSchemas = discoveredToolSchemas;
-    if (!usesScopedFetch) this.cachedToolSchemas = discoveredToolSchemas;
+    if (!usesScopedFetch && !superseded()) this.cachedToolSchemas = discoveredToolSchemas;
     const advertisesCapabilitiesTool = tools.some((t) => t.name === "get_adcp_capabilities");
     const officialA2ALifecycle = this.normalizedAgent.protocol === "a2a" && tools.some((tool) => ["tasks/get", "get_task_status", "list_tasks"].includes(tool.name));
     const hasCapabilitiesTool = advertisesCapabilitiesTool || officialA2ALifecycle;
@@ -6517,7 +6719,31 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         }
         if (result.success && result.data) {
           const capabilities2 = augmentCapabilitiesFromTools(parseCapabilitiesResponse(result.data), tools);
-          if (!usesScopedFetch) this.cachedCapabilities = capabilities2;
+          if (!usesScopedFetch && !superseded()) {
+            this.cachedCapabilities = capabilities2;
+            this.capabilitiesFromSharedCache = false;
+            if (!capabilities2._synthetic && this.config.discoveryCache) {
+              this.recordSharedEvidence(this.sharedDiscoveryKey(options));
+              const stored = await this.writeSharedDiscovery(
+                options,
+                {
+                  capabilities: structuredClone(capabilities2),
+                  toolSchemas: Object.fromEntries(discoveredToolSchemas)
+                },
+                false,
+                startedAtEpoch
+              );
+              if (superseded()) {
+                if (this.cachedCapabilities === capabilities2) {
+                  this.cachedCapabilities = void 0;
+                  this.cachedToolSchemas = void 0;
+                  this.primedCapabilitiesExpiresAt = void 0;
+                }
+              } else {
+                this.primedCapabilitiesExpiresAt = stored?.expiresAt ?? Date.now() + resolveAgentDiscoveryTtlMs(this.config.discoveryCache.ttlMs);
+              }
+            }
+          }
           this.maybeWarnV2Sunset(capabilities2);
           return capabilities2;
         }
@@ -6536,7 +6762,11 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             majorVersions: parsed.majorVersions.includes(3) ? parsed.majorVersions : [3]
           };
           const capabilities2 = augmentCapabilitiesFromTools(v3Capabilities, tools);
-          if (!usesScopedFetch) this.cachedCapabilities = capabilities2;
+          if (!usesScopedFetch && !superseded()) {
+            this.cachedCapabilities = capabilities2;
+            this.capabilitiesFromSharedCache = false;
+            this.recordSharedEvidence(this.sharedDiscoveryKey(options));
+          }
           this.maybeWarnV2Sunset(capabilities2);
           return capabilities2;
         }
@@ -6560,7 +6790,11 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       }
       if (advertisesCapabilitiesTool) {
         const capabilities2 = augmentCapabilitiesFromTools(buildSyntheticV3Capabilities(tools), tools);
-        if (!usesScopedFetch) this.cachedCapabilities = capabilities2;
+        if (!usesScopedFetch && !superseded()) {
+          this.cachedCapabilities = capabilities2;
+          this.capabilitiesFromSharedCache = false;
+          this.recordSharedEvidence(this.sharedDiscoveryKey(options));
+        }
         this.maybeWarnV2Sunset(capabilities2);
         return capabilities2;
       }
@@ -6569,7 +6803,11 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       `[AdCP] Agent "${this.agent.id}" detected as v2 (no get_adcp_capabilities tool). Tools: [${tools.map((t) => t.name).join(", ")}]`
     );
     const capabilities = buildSyntheticCapabilities(tools);
-    if (!usesScopedFetch) this.cachedCapabilities = capabilities;
+    if (!usesScopedFetch && !superseded()) {
+      this.cachedCapabilities = capabilities;
+      this.capabilitiesFromSharedCache = false;
+      this.recordSharedEvidence(this.sharedDiscoveryKey(options));
+    }
     return capabilities;
   }
   /**
@@ -6640,6 +6878,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       this.cachedCapabilities = void 0;
       this.cachedToolSchemas = void 0;
       this.primedCapabilitiesExpiresAt = void 0;
+      this.capabilitiesFromSharedCache = false;
       return false;
     }
     try {
@@ -6648,6 +6887,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ].map((name) => ({ name }));
       this.cachedCapabilities = augmentCapabilitiesFromTools(structuredClone(capabilities), observedTools);
       this.primedCapabilitiesExpiresAt = expiresAt;
+      this.capabilitiesFromSharedCache = false;
+      this.recordSharedEvidence(this.sharedDiscoveryKey(), true);
       this.cachedToolSchemas = snapshot.toolSchemas ? new Map(
         Object.entries(snapshot.toolSchemas).map(([tool, properties]) => [
           tool,
@@ -6662,6 +6903,396 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       return false;
     }
   }
+  /** Which kind of credential this client presents (never its value), so an unauthenticated client cannot adopt an authenticated one's evidence. */
+  discoveryCredentialKind() {
+    const agent = this.normalizedAgent;
+    if (agent.oauth_client_credentials) return "oauth-client-credentials";
+    if (agent.oauth_tokens) return "oauth";
+    if (agent.auth_token) return "bearer";
+    const headerNames = Object.keys(agent.headers ?? {}).map((name) => name.toLowerCase());
+    return headerNames.includes("authorization") || headerNames.includes("x-adcp-auth") ? "header" : "none";
+  }
+  /** Epoch of this client's evidence for the call's effective shared key; `undefined` without a shared cache. */
+  discoveryEpochSnapshot(options) {
+    const key = this.sharedDiscoveryKey(options);
+    if (!key || !this.config.discoveryCache) return void 0;
+    return { local: this.discoveryEpoch, shared: this.sharedInvalidationEpoch(key), key };
+  }
+  discoveryEpochIs(epoch) {
+    return epoch.local === this.discoveryEpoch && epoch.shared === this.sharedInvalidationEpoch(epoch.key);
+  }
+  /** The latest invalidation that applies to `key`: its own, combined with the cache's floor of forgotten ones. */
+  sharedInvalidationRecord(key) {
+    const cache = this.config.discoveryCache.cache;
+    const record = sharedInvalidations.get(cache)?.get(key);
+    const floor = sharedInvalidationFloors.get(cache);
+    if (!floor) return record;
+    if (!record) return floor;
+    return { epoch: Math.max(record.epoch, floor.epoch), at: Math.max(record.at, floor.at) };
+  }
+  sharedInvalidationEpoch(key) {
+    return this.sharedInvalidationRecord(key)?.epoch ?? 0;
+  }
+  bumpSharedInvalidationEpoch(key) {
+    const cache = this.config.discoveryCache.cache;
+    let records = sharedInvalidations.get(cache);
+    if (!records) {
+      records = /* @__PURE__ */ new Map();
+      sharedInvalidations.set(cache, records);
+    }
+    const now = Date.now();
+    records.delete(key);
+    records.set(key, { epoch: ++sharedInvalidationCounter, at: now });
+    for (const [oldKey, record] of records) {
+      if (records.size <= MAX_SHARED_INVALIDATION_RECORDS && record.at + MAX_AGENT_DISCOVERY_TTL_MS > now) break;
+      const floor = sharedInvalidationFloors.get(cache);
+      sharedInvalidationFloors.set(cache, {
+        epoch: Math.max(record.epoch, floor?.epoch ?? 0),
+        at: Math.max(record.at, floor?.at ?? 0)
+      });
+      records.delete(oldKey);
+    }
+  }
+  /**
+   * Remember which key the local capability evidence belongs to and, unless it
+   * is application-owned (`primeCapabilities`), the shared invalidation epoch it
+   * was obtained under. Application-owned evidence keeps its caller-declared
+   * freshness and is not discarded by another instance's invalidation.
+   */
+  recordSharedEvidence(key, applicationOwned = false) {
+    this.sharedEvidenceKey = key;
+    this.sharedEvidenceEpoch = key && this.config.discoveryCache && !applicationOwned ? this.sharedInvalidationEpoch(key) : void 0;
+  }
+  /** Non-secret fingerprint of the request-signing identity, so keys never mix signing identities. */
+  discoverySigningFingerprint() {
+    const signing = this.normalizedAgent.request_signing;
+    if (!signing) return void 0;
+    const provider = signing.kind === "provider" ? signing.provider : void 0;
+    return {
+      kind: signing.kind ?? "inline",
+      agentUrl: signing.agent_url ?? null,
+      kid: (provider ? provider.keyid : signing.kid) ?? null,
+      alg: (provider ? provider.algorithm : signing.alg) ?? null,
+      alwaysSign: signing.always_sign ?? null,
+      signSupported: signing.sign_supported ?? null
+    };
+  }
+  /**
+   * Shared-discovery key for the effective transport policy of this call, or
+   * `undefined` when sharing is off or the call uses a scoped `trustedFetchFn`
+   * (whose network boundary is per-call, so its evidence is never shared).
+   */
+  sharedDiscoveryKey(options) {
+    const config = this.config.discoveryCache;
+    if (!config) return void 0;
+    const transport = normalizeTransportOptions(options?.transport ?? this.config.transport);
+    if (transport?.trustedFetchFn !== void 0) return void 0;
+    return agentDiscoveryCacheKey({
+      protocol: this.normalizedAgent.protocol,
+      agentUri: this.normalizedAgent.agent_uri,
+      adcpVersion: this.resolvedAdcpVersion,
+      wireAdcpVersion: this.config.wireAdcpVersion,
+      authIdentity: config.authIdentity,
+      credentialKind: this.discoveryCredentialKind(),
+      headers: withAmbientIdentityHeaders(this.normalizedAgent.headers),
+      signing: this.discoverySigningFingerprint(),
+      allowPrivateIp: transport?.allowPrivateIp,
+      maxResponseBytes: transport?.maxResponseBytes
+    });
+  }
+  /**
+   * Run a shared-cache operation under the caller's signal and a fixed backend
+   * deadline, so an unresponsive store can neither make a call uncancellable nor
+   * stall it beyond {@link SHARED_DISCOVERY_CACHE_TIMEOUT_MS}. Rejects on the
+   * caller's abort or when the backend fails or times out; callers decide which
+   * of those is a miss.
+   */
+  boundedCacheOperation(operation, signal) {
+    return withAbortSignal([signal], SHARED_DISCOVERY_CACHE_TIMEOUT_MS, () => Promise.resolve().then(operation));
+  }
+  /**
+   * Run one backend mutation (or read-modify-write) for a shared key strictly
+   * after every earlier mutation of that key in this process has actually
+   * settled. The caller's wait is still bounded: an unresponsive backend makes
+   * the caller see a miss, but later mutations stay queued behind the hung
+   * operation, so an old callback can never land after a newer one.
+   *
+   * The queue is bounded. A `droppable` mutation (a write or cleanup) is
+   * abandoned when its caller stopped waiting before it started, and is refused
+   * when the key's queue is full; refusal is a failed write, never a call
+   * failure. A `delete` is never refused for a known key: while one is queued
+   * and not yet started, a newer invalidation joins it. Only for a new key beyond
+   * the key cap is a delete refused — the invalidation tombstone still hides the
+   * entry from this process's readers.
+   */
+  serializedCacheMutation(key, operation, signal, kind = "droppable") {
+    const cache = this.config.discoveryCache.cache;
+    let chains = sharedMutationChains.get(cache);
+    if (!chains) {
+      chains = /* @__PURE__ */ new Map();
+      sharedMutationChains.set(cache, chains);
+    }
+    let queue = chains.get(key);
+    if (!queue && chains.size >= MAX_SHARED_MUTATION_KEYS) {
+      return Promise.reject(new Error("Shared discovery cache mutation queue is full."));
+    }
+    if (kind === "delete" && queue?.waitingDelete && !queue.waitingDelete.started) {
+      const joined = queue.waitingDelete.promise;
+      return this.boundedCacheOperation(() => joined, signal);
+    }
+    if (kind === "droppable" && queue && queue.pending >= MAX_PENDING_SHARED_MUTATIONS_PER_KEY) {
+      return Promise.reject(new Error("Shared discovery cache mutation queue is full."));
+    }
+    if (!queue) {
+      queue = { tail: Promise.resolve(), pending: 0 };
+      chains.set(key, queue);
+    }
+    const current = queue;
+    const state = { abandoned: false, started: false };
+    const run = current.tail.then(() => {
+      if (kind === "droppable" && state.abandoned) throw new Error("Shared discovery cache mutation abandoned.");
+      state.started = true;
+      if (current.waitingDelete?.promise === run) current.waitingDelete.started = true;
+      return operation();
+    });
+    current.pending++;
+    if (kind === "delete") current.waitingDelete = { promise: run, started: false };
+    const tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    current.tail = tail;
+    void tail.then(() => {
+      current.pending--;
+      if (current.waitingDelete?.promise === run) current.waitingDelete = void 0;
+      if (current.pending === 0) {
+        if (chains.get(key) === current) chains.delete(key);
+        if (chains.size === 0 && sharedMutationChains.get(cache) === chains) sharedMutationChains.delete(cache);
+      }
+    });
+    return this.boundedCacheOperation(() => run, signal).catch((error) => {
+      state.abandoned = true;
+      throw error;
+    });
+  }
+  /** Is this stored entry structurally sound and not expired (before any caller-TTL cap)? */
+  isLiveSharedEntry(entry, now) {
+    return Number.isFinite(entry.expiresAt) && Number.isFinite(entry.observedAt) && entry.expiresAt >= entry.observedAt && entry.expiresAt > now;
+  }
+  /**
+   * Read a fresh, structurally valid shared entry. A backend failure or
+   * timeout is a miss, never a call failure; the caller's own abort propagates.
+   */
+  async readSharedDiscovery(options) {
+    const key = this.sharedDiscoveryKey(options);
+    if (!key) return void 0;
+    const cache = this.config.discoveryCache.cache;
+    const epoch = this.discoveryEpochSnapshot(options);
+    try {
+      const entry = await this.boundedCacheOperation(() => cache.get(key), options?.signal);
+      if (epoch && !this.discoveryEpochIs(epoch)) return void 0;
+      if (!entry) return void 0;
+      const invalidation = this.sharedInvalidationRecord(key);
+      if (invalidation && entry.observedAt <= invalidation.at) return void 0;
+      const now = Date.now();
+      if (!this.isLiveSharedEntry(entry, now)) {
+        await this.serializedCacheMutation(
+          key,
+          async () => {
+            const current = await cache.get(key);
+            if (current && !this.isLiveSharedEntry(current, Date.now())) await cache.delete(key);
+          },
+          options?.signal
+        );
+        return void 0;
+      }
+      if (entry.observedAt > now + SHARED_DISCOVERY_CLOCK_SKEW_MS) return void 0;
+      const callerExpiresAt = entry.observedAt + resolveAgentDiscoveryTtlMs(this.config.discoveryCache.ttlMs);
+      if (!(callerExpiresAt > now)) return void 0;
+      return callerExpiresAt < entry.expiresAt ? { ...entry, expiresAt: callerExpiresAt } : entry;
+    } catch {
+      throwIfAborted(options?.signal);
+      return void 0;
+    }
+  }
+  /**
+   * Merge fresh evidence into the shared entry; the merged entry never outlives
+   * its oldest part. Returns the stored entry, or `undefined` when it was not
+   * stored: automatic writes
+   * ignore a `false` (a failed write only costs a later rediscovery), while
+   * {@link primeDiscoveryCache} reports it.
+   */
+  async writeSharedDiscovery(options, patch, replace = false, epoch = this.discoveryEpochSnapshot(options)) {
+    const key = this.sharedDiscoveryKey(options);
+    if (!key) return void 0;
+    if (patch.endpoint && !this.isDiscoverableEndpoint(patch.endpoint.agentUri)) {
+      patch = { capabilities: patch.capabilities, toolSchemas: patch.toolSchemas };
+      if (!patch.capabilities && !patch.toolSchemas) return void 0;
+    }
+    const config = this.config.discoveryCache;
+    const stale = () => epoch !== void 0 && !this.discoveryEpochIs(epoch);
+    try {
+      return await this.serializedCacheMutation(
+        key,
+        async () => {
+          if (stale()) return void 0;
+          const invalidation = this.sharedInvalidationRecord(key);
+          const now = Math.max(Date.now(), (invalidation?.at ?? 0) + 1);
+          let existing;
+          if (!replace) {
+            const raw = await config.cache.get(key);
+            if (raw && this.isLiveSharedEntry(raw, now) && raw.observedAt <= now + SHARED_DISCOVERY_CLOCK_SKEW_MS && !(invalidation && raw.observedAt <= invalidation.at)) {
+              const endpointObservedAt = raw.endpoint?.observedAt ?? raw.observedAt;
+              existing = { ...raw };
+              if (existing.endpoint && (!this.isDiscoverableEndpoint(existing.endpoint.agentUri) || invalidation && endpointObservedAt <= invalidation.at))
+                delete existing.endpoint;
+            }
+            if (stale()) return void 0;
+          }
+          const restartsClock = !existing || patch.capabilities !== void 0;
+          const ttl = resolveAgentDiscoveryTtlMs(config.ttlMs);
+          const entry = {
+            ...existing?.capabilities && { capabilities: existing.capabilities },
+            ...existing?.toolSchemas && { toolSchemas: existing.toolSchemas },
+            ...existing?.endpoint && { endpoint: existing.endpoint },
+            ...patch.endpoint && { endpoint: { ...patch.endpoint, observedAt: now } },
+            ...patch.capabilities && { capabilities: patch.capabilities },
+            ...patch.toolSchemas && { toolSchemas: patch.toolSchemas },
+            observedAt: restartsClock || !existing ? now : Math.min(existing.observedAt, now),
+            expiresAt: restartsClock || !existing ? now + ttl : Math.min(existing.expiresAt, now + ttl)
+          };
+          await config.cache.set(key, structuredClone(entry));
+          return stale() ? void 0 : entry;
+        },
+        options?.signal
+      );
+    } catch {
+      return void 0;
+    }
+  }
+  /** Is `agentUri` a credential-free URL on the configured agent's origin (all discovery ever tries)? */
+  isDiscoverableEndpoint(agentUri) {
+    if (typeof agentUri !== "string") return false;
+    try {
+      const candidate = new URL(agentUri);
+      return candidate.username === "" && candidate.password === "" && candidate.search === "" && candidate.hash === "" && candidate.origin === new URL(this.normalizedAgent.agent_uri).origin;
+    } catch {
+      return false;
+    }
+  }
+  /** Adopt a previously discovered MCP endpoint instead of re-probing the agent. */
+  async adoptSharedEndpoint(options) {
+    const readEpoch = this.discoveryEpochSnapshot(options);
+    const entry = await this.readSharedDiscovery(options);
+    if (readEpoch && !this.discoveryEpochIs(readEpoch)) return;
+    const endpoint = entry?.endpoint;
+    if (!entry || !endpoint || !this.isDiscoverableEndpoint(endpoint.agentUri)) return;
+    const observedAt = Number.isFinite(endpoint.observedAt) ? endpoint.observedAt : entry.observedAt;
+    const sharedKey = this.sharedDiscoveryKey(options);
+    const tombstone = sharedKey ? this.sharedInvalidationRecord(sharedKey) : void 0;
+    if (tombstone && observedAt <= tombstone.at) return;
+    const expiresAt = Math.min(
+      entry.expiresAt,
+      observedAt + resolveAgentDiscoveryTtlMs(this.config.discoveryCache.ttlMs)
+    );
+    if (!(expiresAt > Date.now()) || observedAt > Date.now() + SHARED_DISCOVERY_CLOCK_SKEW_MS) return;
+    this.discoveredEndpoint = endpoint.agentUri;
+    this.discoveredEndpointKey = this.sharedDiscoveryKey(options);
+    this.discoveredEndpointEpoch = this.discoveredEndpointKey ? this.sharedInvalidationEpoch(this.discoveredEndpointKey) : void 0;
+    this.discoveredEndpointExpiresAt = expiresAt;
+    this.canonicalBaseUrl = this.computeBaseUrl(endpoint.agentUri);
+    if (endpoint.mcpEra === "legacy" || endpoint.mcpEra === "modern") {
+      this.discoveredMcpEra = endpoint.mcpEra;
+      this.discoveredMcpEraAt = observedAt;
+    }
+  }
+  /**
+   * Drop discovery evidence for this client: its in-memory capability and
+   * tool-schema caches, the discovered endpoint, and the shared
+   * `discoveryCache` entry (when configured). The next call rediscovers.
+   *
+   * Call this when you learn the seller changed (a deploy, a version bump, a
+   * capability-dependent error you observed). The SDK also invalidates by
+   * itself when a feature check fails against shared evidence, and when a
+   * seller answers with a version or capability error.
+   */
+  async invalidateDiscoveryCache(options) {
+    this.cachedCapabilities = void 0;
+    this.cachedToolSchemas = void 0;
+    this.primedCapabilitiesExpiresAt = void 0;
+    this.capabilitiesFromSharedCache = false;
+    this.capabilityEvidenceScopeKey = randomUUID();
+    this.discoveryEpoch++;
+    if (this.normalizedAgent._needsDiscovery) {
+      this.discoveredEndpoint = void 0;
+      this.discoveredAgent = void 0;
+      this.discoveredMcpEra = void 0;
+      this.discoveredEndpointKey = void 0;
+      this.discoveredEndpointEpoch = void 0;
+      this.discoveredEndpointExpiresAt = void 0;
+    }
+    const key = this.sharedDiscoveryKey(options);
+    if (!key) return;
+    this.bumpSharedInvalidationEpoch(key);
+    try {
+      const cache = this.config.discoveryCache.cache;
+      await this.serializedCacheMutation(key, () => cache.delete(key), void 0, "delete");
+    } catch {
+    }
+  }
+  /**
+   * Pre-seed the shared `discoveryCache` with capability evidence the caller
+   * already holds (for example from a registry sync), so no client sharing
+   * this identity probes the seller within the TTL. Unlike
+   * {@link primeCapabilities} the seeded evidence outlives this instance.
+   *
+   * Returns `true` only once the backing cache has accepted the entry. Returns
+   * `false` — having seeded nothing — when sharing is not configured, the
+   * client uses a scoped `trustedFetchFn`, or the evidence is synthetic,
+   * malformed or not cloneable. When the cache rejects the write or does not
+   * answer within the backend deadline, the result is also `false`, but the
+   * outcome is indeterminate: a write already handed to the backend may still
+   * land, whereas one still queued behind earlier operations is dropped. Treat
+   * `false` as "not confirmed", and seed again (or invalidate) rather than
+   * assuming the cache is empty. Seed `endpoint` as well
+   * to skip the endpoint probe on the first call; without it that probe still
+   * runs once per cold client.
+   */
+  async primeDiscoveryCache(seed) {
+    const key = this.sharedDiscoveryKey();
+    const capabilities = seed?.capabilities;
+    if (!key || !isCapabilityEvidence(capabilities) || capabilities._synthetic) return false;
+    const toolSchemas = seed.toolSchemas;
+    if (toolSchemas !== void 0 && !isToolSchemaRecord(toolSchemas)) {
+      return false;
+    }
+    if (toolSchemas === void 0 && !Array.isArray(capabilities.discoveredTools)) return false;
+    if (seed.endpoint !== void 0 && !this.isDiscoverableEndpoint(seed.endpoint.agentUri)) return false;
+    try {
+      const stored = await this.writeSharedDiscovery(
+        void 0,
+        {
+          capabilities: structuredClone(capabilities),
+          ...toolSchemas && { toolSchemas: structuredClone(toolSchemas) },
+          ...seed.endpoint && {
+            endpoint: {
+              agentUri: seed.endpoint.agentUri,
+              ...seed.endpoint.mcpEra && { mcpEra: seed.endpoint.mcpEra }
+            }
+          }
+        },
+        true
+      );
+      return stored !== void 0;
+    } catch {
+      return false;
+    }
+  }
+  /** Drop shared evidence when a seller answers with an error that says our cached view of it is stale. */
+  async invalidateDiscoveryOnCapabilityError(code, options) {
+    if (!this.config.discoveryCache || !code || !CAPABILITY_STALE_ERROR_CODES.has(code)) return;
+    await this.invalidateDiscoveryCache(options);
+  }
   /**
    * Emit a one-time warning when the agent reports v2 capabilities.
    *
@@ -6810,8 +7441,21 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * with an actionable error message.
    */
   async require(...features) {
-    const capabilities = await this.getCapabilities();
-    const missing = features.filter((f) => !resolveFeature(capabilities, f));
+    await this.assertFeaturesSupported(features);
+  }
+  /**
+   * Throw {@link FeatureUnsupportedError} when a feature is missing, deciding on
+   * live capabilities when the refusal would rest on shared evidence that may
+   * predate a seller upgrade.
+   */
+  async assertFeaturesSupported(requiredFeatures, options) {
+    let capabilities = await this.getCapabilities(options);
+    let missing = requiredFeatures.filter((f) => !resolveFeature(capabilities, f));
+    if (missing.length > 0 && this.capabilitiesFromSharedCache) {
+      await this.invalidateDiscoveryCache(options);
+      capabilities = await this.getCapabilities(options);
+      missing = requiredFeatures.filter((f) => !resolveFeature(capabilities, f));
+    }
     if (missing.length > 0) {
       throw new FeatureUnsupportedError(missing, listDeclaredFeatures(capabilities), this.agent.agent_uri);
     }
@@ -6824,7 +7468,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     this.cachedCapabilities = void 0;
     this.cachedToolSchemas = void 0;
     this.primedCapabilitiesExpiresAt = void 0;
+    this.capabilitiesFromSharedCache = false;
     this.capabilityEvidenceScopeKey = randomUUID();
+    this.discoveryEpoch++;
+    if (this.config.discoveryCache) await this.invalidateDiscoveryCache();
     return this.getCapabilities();
   }
   /**
@@ -6837,11 +7484,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (this.config.validateFeatures === false) return;
     const requiredFeatures = TASK_FEATURE_MAP[taskName];
     if (!requiredFeatures || requiredFeatures.length === 0) return;
-    const capabilities = await this.getCapabilities(options);
-    const missing = requiredFeatures.filter((f) => !resolveFeature(capabilities, f));
-    if (missing.length > 0) {
-      throw new FeatureUnsupportedError(missing, listDeclaredFeatures(capabilities), this.agent.agent_uri);
-    }
+    await this.assertFeaturesSupported(requiredFeatures, options);
   }
   /**
    * Fail version-incompatible request shapes before schema validation.