@adcp/sdk 15.3.0 → 15.5.0

package/dist/lib/advanced.d.mts

@@ -37,5 +37,5 @@
  * - Type-safe tool methods
  * - Error handling and validation
  */
-export { ProtocolClient, callMCPTool, callMCPToolWithOAuth, connectMCP, callA2ATool, createMCPClient, createA2AClient, } from './protocols/index.mjs';
-export type { MCPCallOptions, MCPConnectionResult } from './protocols/index.mjs';
+export { ProtocolClient, callMCPTool, callMCPToolWithOAuth, connectMCP, callA2ATool, createMCPClient, createA2AClient, closeConnections, closeScopedConnections, withMCPConnectionScope, } from './protocols/index.mjs';
+export type { MCPCallOptions, MCPConnectionResult, TransportActivity, TransportActivityType, TransportResponseOutcome, } from './protocols/index.mjs';

package/dist/lib/advanced.d.ts

@@ -37,5 +37,5 @@
  * - Type-safe tool methods
  * - Error handling and validation
  */
-export { ProtocolClient, callMCPTool, callMCPToolWithOAuth, connectMCP, callA2ATool, createMCPClient, createA2AClient, } from './protocols';
-export type { MCPCallOptions, MCPConnectionResult } from './protocols';
+export { ProtocolClient, callMCPTool, callMCPToolWithOAuth, connectMCP, callA2ATool, createMCPClient, createA2AClient, closeConnections, closeScopedConnections, withMCPConnectionScope, } from './protocols';
+export type { MCPCallOptions, MCPConnectionResult, TransportActivity, TransportActivityType, TransportResponseOutcome, } from './protocols';

package/dist/lib/advanced.js

@@ -22,9 +22,12 @@ __export(advanced_exports, {
   callA2ATool: () => import_protocols.callA2ATool,
   callMCPTool: () => import_protocols.callMCPTool,
   callMCPToolWithOAuth: () => import_protocols.callMCPToolWithOAuth,
+  closeConnections: () => import_protocols.closeConnections,
+  closeScopedConnections: () => import_protocols.closeScopedConnections,
   connectMCP: () => import_protocols.connectMCP,
   createA2AClient: () => import_protocols.createA2AClient,
-  createMCPClient: () => import_protocols.createMCPClient
+  createMCPClient: () => import_protocols.createMCPClient,
+  withMCPConnectionScope: () => import_protocols.withMCPConnectionScope
 });
 module.exports = __toCommonJS(advanced_exports);
 var import_protocols = require('./protocols/index.js');
@@ -34,7 +37,10 @@ var import_protocols = require('./protocols/index.js');
   callA2ATool,
   callMCPTool,
   callMCPToolWithOAuth,
+  closeConnections,
+  closeScopedConnections,
   connectMCP,
   createA2AClient,
-  createMCPClient
+  createMCPClient,
+  withMCPConnectionScope
 });

package/dist/lib/advanced.mjs

@@ -5,14 +5,20 @@ import {
   connectMCP,
   callA2ATool,
   createMCPClient,
-  createA2AClient
+  createA2AClient,
+  closeConnections,
+  closeScopedConnections,
+  withMCPConnectionScope
 } from "./protocols/index.mjs";
 export {
   ProtocolClient,
   callA2ATool,
   callMCPTool,
   callMCPToolWithOAuth,
+  closeConnections,
+  closeScopedConnections,
   connectMCP,
   createA2AClient,
-  createMCPClient
+  createMCPClient,
+  withMCPConnectionScope
 };

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

@@ -543,6 +543,10 @@ export declare class AgentClient {
     resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
     /** Scope token for a tenant-bound, application-owned capability preflight. */
     getCapabilityEvidenceScope(): import('./SingleAgentClient.mjs').CapabilityEvidenceScope;
+    /** Drop this client's discovery evidence and its shared `discoveryCache` entry. */
+    invalidateDiscoveryCache(options?: Pick<TaskOptions, 'transport'>): Promise<void>;
+    /** Pre-seed the shared `discoveryCache` so peer clients skip discovery within the TTL. */
+    primeDiscoveryCache(seed: import('./SingleAgentClient.mjs').AgentDiscoverySeed): Promise<boolean>;
     /** Install fresh capability evidence without making a redundant probe. */
     primeCapabilities(snapshot: import('./SingleAgentClient.mjs').CapabilityEvidenceSnapshot): boolean;
     /**

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

@@ -543,6 +543,10 @@ export declare class AgentClient {
     resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
     /** Scope token for a tenant-bound, application-owned capability preflight. */
     getCapabilityEvidenceScope(): import('./SingleAgentClient').CapabilityEvidenceScope;
+    /** Drop this client's discovery evidence and its shared `discoveryCache` entry. */
+    invalidateDiscoveryCache(options?: Pick<TaskOptions, 'transport'>): Promise<void>;
+    /** Pre-seed the shared `discoveryCache` so peer clients skip discovery within the TTL. */
+    primeDiscoveryCache(seed: import('./SingleAgentClient').AgentDiscoverySeed): Promise<boolean>;
     /** Install fresh capability evidence without making a redundant probe. */
     primeCapabilities(snapshot: import('./SingleAgentClient').CapabilityEvidenceSnapshot): boolean;
     /**

package/dist/lib/core/AgentClient.js

@@ -805,6 +805,14 @@ class AgentClient {
   getCapabilityEvidenceScope() {
     return this.client.getCapabilityEvidenceScope();
   }
+  /** Drop this client's discovery evidence and its shared `discoveryCache` entry. */
+  invalidateDiscoveryCache(options) {
+    return this.client.invalidateDiscoveryCache(options);
+  }
+  /** Pre-seed the shared `discoveryCache` so peer clients skip discovery within the TTL. */
+  primeDiscoveryCache(seed) {
+    return this.client.primeDiscoveryCache(seed);
+  }
   /** Install fresh capability evidence without making a redundant probe. */
   primeCapabilities(snapshot) {
     return this.client.primeCapabilities(snapshot);

package/dist/lib/core/AgentClient.mjs

@@ -773,6 +773,14 @@ class AgentClient {
   getCapabilityEvidenceScope() {
     return this.client.getCapabilityEvidenceScope();
   }
+  /** Drop this client's discovery evidence and its shared `discoveryCache` entry. */
+  invalidateDiscoveryCache(options) {
+    return this.client.invalidateDiscoveryCache(options);
+  }
+  /** Pre-seed the shared `discoveryCache` so peer clients skip discovery within the TTL. */
+  primeDiscoveryCache(seed) {
+    return this.client.primeDiscoveryCache(seed);
+  }
   /** Install fresh capability evidence without making a redundant probe. */
   primeCapabilities(snapshot) {
     return this.client.primeCapabilities(snapshot);

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

@@ -14,6 +14,7 @@ import { type WebhookHeaderValue, type WebhookHeadersLike } from '../webhooks/in
 import { type WebhookRegistration, type WebhookRegistrationStore } from './webhook-registration.mjs';
 import { type ReplayStore, type RevocationStore, type JwksResolver, type WebhookSignatureErrorCode, type ResolvedAgentJwksResolverOptions } from '../signing/server.mjs';
 import type { AdcpCapabilities, FeatureName } from '../utils/capabilities.mjs';
+import { type AgentDiscoveryCacheConfig } from './agent-discovery-cache.mjs';
 import { BuyerAccountRegistry, type AccountPolicy, type BuyerAccountStorage } from './buyer-account-registry.mjs';
 import type { ProductCache } from './product-cache.mjs';
 import { type ResolveAccountOptions } from './account-resolution.mjs';
@@ -208,6 +209,21 @@ export interface SingleAgentClientConfig extends ConversationConfig {
     /** Trusted stable caller identity for durable registry partitioning. Default is credential fingerprint. */
     accountRegistryScope?: string;
     productCache?: ProductCache;
+    /**
+     * Share endpoint discovery, the `tools/list` schema map and
+     * `get_adcp_capabilities` across client instances. Opt-in: nothing is shared
+     * unless a cache and a caller-owned `authIdentity` are supplied.
+     *
+     * Entries are keyed by agent URL, `authIdentity`, the pinned AdCP version, the
+     * non-correlation request headers (tenant/routing headers included), the
+     * signing identity and the transport policy (`allowPrivateIp`,
+     * `maxResponseBytes`), and expire after `ttlMs`. Synthetic capabilities
+     * (a seller whose capabilities call failed or that has no
+     * `get_adcp_capabilities`) are never shared, and calls that use a scoped
+     * `trustedFetchFn` bypass the cache entirely.
+     * See `docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md`.
+     */
+    discoveryCache?: AgentDiscoveryCacheConfig;
     /** Durable storage for restart-safe A2A human continuations. */
     deferredStorage?: DeferredTaskStorage;
     /** Resolve current trusted agent configuration for a persisted continuation. */
@@ -489,6 +505,21 @@ export interface CapabilityEvidenceSnapshot {
     /** `tools/list` input-schema properties keyed by tool name; optional when capabilities already carry discoveredTools. */
     toolSchemas?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
+/** Capability evidence to pre-seed into a shared `discoveryCache`. */
+export interface AgentDiscoverySeed {
+    /** Authoritative capabilities (never synthetic). */
+    capabilities: AdcpCapabilities;
+    /** `tools/list` input-schema properties keyed by tool name; optional when capabilities carry discoveredTools. */
+    toolSchemas?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /**
+     * The MCP endpoint serving this agent, to skip endpoint probing. Must be a
+     * credential-free URL on the configured agent's origin, without query or fragment.
+     */
+    endpoint?: {
+        agentUri: string;
+        mcpEra?: 'legacy' | 'modern';
+    };
+}
 export declare class SingleAgentClient {
     private agent;
     private config;
@@ -522,6 +553,13 @@ export declare class SingleAgentClient {
     private primedCapabilitiesExpiresAt?;
     private capabilityEvidenceScopeKey;
     private capabilityEvidenceAuthMaterial?;
+    private capabilitiesFromSharedCache;
+    private discoveryEpoch;
+    private discoveredEndpointKey?;
+    private discoveredEndpointEpoch?;
+    private discoveredEndpointExpiresAt?;
+    private sharedEvidenceEpoch?;
+    private sharedEvidenceKey?;
     private _v2WarningFired;
     private _syntheticV3WarningFired;
     private _syntheticV2WarningFired;
@@ -1443,6 +1481,17 @@ export declare class SingleAgentClient {
      * ```
      */
     getCapabilities(options?: ReadRequestOptions): Promise<AdcpCapabilities>;
+    /**
+     * 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.
+     */
+    private discoverCapabilitiesThroughSharedCache;
+    /** Install capabilities from a shared entry; `undefined` when the entry is not usable evidence. */
+    private installSharedCapabilities;
+    private discoverCapabilitiesLive;
     /**
      * Return the client-bound scope required by {@link primeCapabilities}.
      *
@@ -1463,6 +1512,105 @@ export declare class SingleAgentClient {
      * within their own request scope.
      */
     primeCapabilities(snapshot: CapabilityEvidenceSnapshot): boolean;
+    /** Which kind of credential this client presents (never its value), so an unauthenticated client cannot adopt an authenticated one's evidence. */
+    private discoveryCredentialKind;
+    /** Epoch of this client's evidence for the call's effective shared key; `undefined` without a shared cache. */
+    private discoveryEpochSnapshot;
+    private discoveryEpochIs;
+    /** The latest invalidation that applies to `key`: its own, combined with the cache's floor of forgotten ones. */
+    private sharedInvalidationRecord;
+    private sharedInvalidationEpoch;
+    private bumpSharedInvalidationEpoch;
+    /**
+     * 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.
+     */
+    private recordSharedEvidence;
+    /** Non-secret fingerprint of the request-signing identity, so keys never mix signing identities. */
+    private discoverySigningFingerprint;
+    /**
+     * 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).
+     */
+    private sharedDiscoveryKey;
+    /**
+     * 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.
+     */
+    private boundedCacheOperation;
+    /**
+     * 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.
+     */
+    private serializedCacheMutation;
+    /** Is this stored entry structurally sound and not expired (before any caller-TTL cap)? */
+    private isLiveSharedEntry;
+    /**
+     * 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.
+     */
+    private readSharedDiscovery;
+    /**
+     * 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.
+     */
+    private writeSharedDiscovery;
+    /** Is `agentUri` a credential-free URL on the configured agent's origin (all discovery ever tries)? */
+    private isDiscoverableEndpoint;
+    /** Adopt a previously discovered MCP endpoint instead of re-probing the agent. */
+    private adoptSharedEndpoint;
+    /**
+     * 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.
+     */
+    invalidateDiscoveryCache(options?: Pick<TaskOptions, 'transport'>): Promise<void>;
+    /**
+     * 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.
+     */
+    primeDiscoveryCache(seed: AgentDiscoverySeed): Promise<boolean>;
+    /** Drop shared evidence when a seller answers with an error that says our cached view of it is stale. */
+    private invalidateDiscoveryOnCapabilityError;
     /**
      * Emit a one-time warning when the agent reports v2 capabilities.
      *
@@ -1564,6 +1712,12 @@ export declare class SingleAgentClient {
      * with an actionable error message.
      */
     require(...features: FeatureName[]): Promise<void>;
+    /**
+     * 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.
+     */
+    private assertFeaturesSupported;
     /**
      * Force-refresh cached capabilities from the server.
      * Useful when seller capabilities may have changed.

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

@@ -14,6 +14,7 @@ import { type WebhookHeaderValue, type WebhookHeadersLike } from '../webhooks';
 import { type WebhookRegistration, type WebhookRegistrationStore } from './webhook-registration';
 import { type ReplayStore, type RevocationStore, type JwksResolver, type WebhookSignatureErrorCode, type ResolvedAgentJwksResolverOptions } from '../signing/server';
 import type { AdcpCapabilities, FeatureName } from '../utils/capabilities';
+import { type AgentDiscoveryCacheConfig } from './agent-discovery-cache';
 import { BuyerAccountRegistry, type AccountPolicy, type BuyerAccountStorage } from './buyer-account-registry';
 import type { ProductCache } from './product-cache';
 import { type ResolveAccountOptions } from './account-resolution';
@@ -208,6 +209,21 @@ export interface SingleAgentClientConfig extends ConversationConfig {
     /** Trusted stable caller identity for durable registry partitioning. Default is credential fingerprint. */
     accountRegistryScope?: string;
     productCache?: ProductCache;
+    /**
+     * Share endpoint discovery, the `tools/list` schema map and
+     * `get_adcp_capabilities` across client instances. Opt-in: nothing is shared
+     * unless a cache and a caller-owned `authIdentity` are supplied.
+     *
+     * Entries are keyed by agent URL, `authIdentity`, the pinned AdCP version, the
+     * non-correlation request headers (tenant/routing headers included), the
+     * signing identity and the transport policy (`allowPrivateIp`,
+     * `maxResponseBytes`), and expire after `ttlMs`. Synthetic capabilities
+     * (a seller whose capabilities call failed or that has no
+     * `get_adcp_capabilities`) are never shared, and calls that use a scoped
+     * `trustedFetchFn` bypass the cache entirely.
+     * See `docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md`.
+     */
+    discoveryCache?: AgentDiscoveryCacheConfig;
     /** Durable storage for restart-safe A2A human continuations. */
     deferredStorage?: DeferredTaskStorage;
     /** Resolve current trusted agent configuration for a persisted continuation. */
@@ -489,6 +505,21 @@ export interface CapabilityEvidenceSnapshot {
     /** `tools/list` input-schema properties keyed by tool name; optional when capabilities already carry discoveredTools. */
     toolSchemas?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
+/** Capability evidence to pre-seed into a shared `discoveryCache`. */
+export interface AgentDiscoverySeed {
+    /** Authoritative capabilities (never synthetic). */
+    capabilities: AdcpCapabilities;
+    /** `tools/list` input-schema properties keyed by tool name; optional when capabilities carry discoveredTools. */
+    toolSchemas?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /**
+     * The MCP endpoint serving this agent, to skip endpoint probing. Must be a
+     * credential-free URL on the configured agent's origin, without query or fragment.
+     */
+    endpoint?: {
+        agentUri: string;
+        mcpEra?: 'legacy' | 'modern';
+    };
+}
 export declare class SingleAgentClient {
     private agent;
     private config;
@@ -522,6 +553,13 @@ export declare class SingleAgentClient {
     private primedCapabilitiesExpiresAt?;
     private capabilityEvidenceScopeKey;
     private capabilityEvidenceAuthMaterial?;
+    private capabilitiesFromSharedCache;
+    private discoveryEpoch;
+    private discoveredEndpointKey?;
+    private discoveredEndpointEpoch?;
+    private discoveredEndpointExpiresAt?;
+    private sharedEvidenceEpoch?;
+    private sharedEvidenceKey?;
     private _v2WarningFired;
     private _syntheticV3WarningFired;
     private _syntheticV2WarningFired;
@@ -1443,6 +1481,17 @@ export declare class SingleAgentClient {
      * ```
      */
     getCapabilities(options?: ReadRequestOptions): Promise<AdcpCapabilities>;
+    /**
+     * 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.
+     */
+    private discoverCapabilitiesThroughSharedCache;
+    /** Install capabilities from a shared entry; `undefined` when the entry is not usable evidence. */
+    private installSharedCapabilities;
+    private discoverCapabilitiesLive;
     /**
      * Return the client-bound scope required by {@link primeCapabilities}.
      *
@@ -1463,6 +1512,105 @@ export declare class SingleAgentClient {
      * within their own request scope.
      */
     primeCapabilities(snapshot: CapabilityEvidenceSnapshot): boolean;
+    /** Which kind of credential this client presents (never its value), so an unauthenticated client cannot adopt an authenticated one's evidence. */
+    private discoveryCredentialKind;
+    /** Epoch of this client's evidence for the call's effective shared key; `undefined` without a shared cache. */
+    private discoveryEpochSnapshot;
+    private discoveryEpochIs;
+    /** The latest invalidation that applies to `key`: its own, combined with the cache's floor of forgotten ones. */
+    private sharedInvalidationRecord;
+    private sharedInvalidationEpoch;
+    private bumpSharedInvalidationEpoch;
+    /**
+     * 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.
+     */
+    private recordSharedEvidence;
+    /** Non-secret fingerprint of the request-signing identity, so keys never mix signing identities. */
+    private discoverySigningFingerprint;
+    /**
+     * 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).
+     */
+    private sharedDiscoveryKey;
+    /**
+     * 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.
+     */
+    private boundedCacheOperation;
+    /**
+     * 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.
+     */
+    private serializedCacheMutation;
+    /** Is this stored entry structurally sound and not expired (before any caller-TTL cap)? */
+    private isLiveSharedEntry;
+    /**
+     * 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.
+     */
+    private readSharedDiscovery;
+    /**
+     * 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.
+     */
+    private writeSharedDiscovery;
+    /** Is `agentUri` a credential-free URL on the configured agent's origin (all discovery ever tries)? */
+    private isDiscoverableEndpoint;
+    /** Adopt a previously discovered MCP endpoint instead of re-probing the agent. */
+    private adoptSharedEndpoint;
+    /**
+     * 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.
+     */
+    invalidateDiscoveryCache(options?: Pick<TaskOptions, 'transport'>): Promise<void>;
+    /**
+     * 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.
+     */
+    primeDiscoveryCache(seed: AgentDiscoverySeed): Promise<boolean>;
+    /** Drop shared evidence when a seller answers with an error that says our cached view of it is stale. */
+    private invalidateDiscoveryOnCapabilityError;
     /**
      * Emit a one-time warning when the agent reports v2 capabilities.
      *
@@ -1564,6 +1712,12 @@ export declare class SingleAgentClient {
      * with an actionable error message.
      */
     require(...features: FeatureName[]): Promise<void>;
+    /**
+     * 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.
+     */
+    private assertFeaturesSupported;
     /**
      * Force-refresh cached capabilities from the server.
      * Useful when seller capabilities may have changed.