@adcp/sdk 15.4.0 → 15.6.0

package/README.md

@@ -57,8 +57,23 @@ Large workspaces should keep the generated schema surface out of the default typ
 | Client, server, signing, and response helpers | `@adcp/sdk`, `@adcp/sdk/client`, `@adcp/sdk/server`, or another focused runtime subpath |
 | One tool's request/response types             | `@adcp/sdk/types/<tool>` such as `@adcp/sdk/types/sync-accounts`                        |
 | Runtime Zod schemas and tool schema maps      | `@adcp/sdk/schemas`                                                                     |
+| Runtime Zod schemas in browser UIs            | `@adcp/sdk/schemas/browser`                                                             |
 | Broad generated protocol type barrel          | `@adcp/sdk/types`                                                                       |
 
+Browser widgets and dashboards can validate AdCP objects with the generated Zod schemas:
+
+```ts
+import {
+  EventSourceHealthSchema,
+  SyncAudiencesResponseSchema,
+  SyncEventSourcesResponseSchema,
+} from '@adcp/sdk/schemas/browser';
+
+const health = EventSourceHealthSchema.parse(rawHealth);
+```
+
+The browser entry also exports `GetProductsRequestSchema` and `LegacyGetProductsRequestSchema`, `BiddingPolicySchema`, `CanonicalBudgetAllocationSchema`, and the strict `SyncCreatives*` validators, with the same validation behavior as the Node entry. It has no Node built-ins in its import graph. JSON Schema loading and tool registration helpers remain available from `@adcp/sdk/schemas`. The generated schemas still initialize together, so importing one schema can retain the full generated module in a browser bundle; per-schema tree-shaking is tracked in [#3178](https://github.com/adcontextprotocol/adcp-client/issues/3178).
+
 ### Focused client runtime (`@adcp/sdk/client/core`)
 
 Applications that only call AdCP agents can avoid evaluating the SDK's server,

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/auth/oauth/index.d.mts

@@ -37,6 +37,7 @@ export { DEFAULT_CLIENT_METADATA, OAuthError, OAuthCancelledError, OAuthTimeoutE
 export { CLIFlowHandler, type CLIFlowHandlerConfig } from './CLIFlowHandler.mjs';
 export { NonInteractiveFlowHandler, type NonInteractiveFlowHandlerConfig } from './NonInteractiveFlowHandler.mjs';
 export { startWebOAuthFlow, completeWebOAuthFlow, safeReturnTo, InMemoryPendingFlowStore, InvalidOrExpiredFlowError, StateMismatchError, BrowserBindingRequiredError, TokenExchangeError, ProtectedResourceMetadataError, AgentVanishedDuringFlowError, AgentChangedDuringFlowError, ConfidentialClientNotAllowedError, DEFAULT_WEB_FLOW_TTL_MS, type PendingWebFlow, type PendingWebFlowStore, type PendingFlowStore, type StartWebFlowOptions, type StartWebFlowResult, type CompleteWebFlowOptions, type CompleteWebFlowResult, } from './web-flow.mjs';
+export { serializePendingWebFlow, parsePendingWebFlow } from './pending-web-flow.mjs';
 export { MCPOAuthProvider } from './MCPOAuthProvider.mjs';
 import { MCPOAuthProvider } from './MCPOAuthProvider.mjs';
 import type { OAuthClientMetadata, OAuthConfigStorage, AgentConfig } from './types.mjs';

package/dist/lib/auth/oauth/index.d.ts

@@ -37,6 +37,7 @@ export { DEFAULT_CLIENT_METADATA, OAuthError, OAuthCancelledError, OAuthTimeoutE
 export { CLIFlowHandler, type CLIFlowHandlerConfig } from './CLIFlowHandler';
 export { NonInteractiveFlowHandler, type NonInteractiveFlowHandlerConfig } from './NonInteractiveFlowHandler';
 export { startWebOAuthFlow, completeWebOAuthFlow, safeReturnTo, InMemoryPendingFlowStore, InvalidOrExpiredFlowError, StateMismatchError, BrowserBindingRequiredError, TokenExchangeError, ProtectedResourceMetadataError, AgentVanishedDuringFlowError, AgentChangedDuringFlowError, ConfidentialClientNotAllowedError, DEFAULT_WEB_FLOW_TTL_MS, type PendingWebFlow, type PendingWebFlowStore, type PendingFlowStore, type StartWebFlowOptions, type StartWebFlowResult, type CompleteWebFlowOptions, type CompleteWebFlowResult, } from './web-flow';
+export { serializePendingWebFlow, parsePendingWebFlow } from './pending-web-flow';
 export { MCPOAuthProvider } from './MCPOAuthProvider';
 import { MCPOAuthProvider } from './MCPOAuthProvider';
 import type { OAuthClientMetadata, OAuthConfigStorage, AgentConfig } from './types';

package/dist/lib/auth/oauth/index.js

@@ -62,11 +62,13 @@ __export(oauth_exports, {
   hasValidatedMcpAuthorizationRequirements: () => import_authorization_required.hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference: () => import_secret_resolver.isEnvSecretReference,
   isOAuthRequired: () => isOAuthRequired,
+  parsePendingWebFlow: () => import_pending_web_flow.parsePendingWebFlow,
   parseWWWAuthenticate: () => import_diagnostics.parseWWWAuthenticate,
   probeAuthChallenge: () => import_authorization_required.probeAuthChallenge,
   resolveSecret: () => import_secret_resolver.resolveSecret,
   runAuthDiagnosis: () => import_diagnose.runAuthDiagnosis,
   safeReturnTo: () => import_web_flow.safeReturnTo,
+  serializePendingWebFlow: () => import_pending_web_flow.serializePendingWebFlow,
   startWebOAuthFlow: () => import_web_flow.startWebOAuthFlow,
   supportsDynamicRegistration: () => import_discovery.supportsDynamicRegistration,
   supportsOAuth: () => import_discovery.supportsOAuth,
@@ -81,6 +83,7 @@ var import_types = require('./types.js');
 var import_CLIFlowHandler = require('./CLIFlowHandler.js');
 var import_NonInteractiveFlowHandler = require('./NonInteractiveFlowHandler.js');
 var import_web_flow = require('./web-flow.js');
+var import_pending_web_flow = require('./pending-web-flow.js');
 var import_MCPOAuthProvider = require('./MCPOAuthProvider.js');
 var import_MCPOAuthProvider2 = require('./MCPOAuthProvider.js');
 var import_CLIFlowHandler2 = require('./CLIFlowHandler.js');
@@ -214,11 +217,13 @@ function getEffectiveAuthToken(agent) {
   hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference,
   isOAuthRequired,
+  parsePendingWebFlow,
   parseWWWAuthenticate,
   probeAuthChallenge,
   resolveSecret,
   runAuthDiagnosis,
   safeReturnTo,
+  serializePendingWebFlow,
   startWebOAuthFlow,
   supportsDynamicRegistration,
   supportsOAuth,

package/dist/lib/auth/oauth/index.mjs

@@ -25,6 +25,7 @@ import {
   ConfidentialClientNotAllowedError,
   DEFAULT_WEB_FLOW_TTL_MS
 } from "./web-flow.mjs";
+import { serializePendingWebFlow, parsePendingWebFlow } from "./pending-web-flow.mjs";
 import { MCPOAuthProvider } from "./MCPOAuthProvider.mjs";
 import { MCPOAuthProvider as MCPOAuthProvider2 } from "./MCPOAuthProvider.mjs";
 import { CLIFlowHandler as CLIFlowHandler2 } from "./CLIFlowHandler.mjs";
@@ -183,11 +184,13 @@ export {
   hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference,
   isOAuthRequired,
+  parsePendingWebFlow,
   parseWWWAuthenticate,
   probeAuthChallenge,
   resolveSecret,
   runAuthDiagnosis,
   safeReturnTo,
+  serializePendingWebFlow,
   startWebOAuthFlow,
   supportsDynamicRegistration,
   supportsOAuth,

package/dist/lib/auth/oauth/pending-web-flow.d.mts

@@ -0,0 +1,16 @@
+import type { PendingWebFlow } from './web-flow.mjs';
+/**
+ * Serialize a pending flow for a durable store, preserving unknown fields.
+ * Throws for malformed SDK fields or JSON.stringify failures. The payload
+ * contains PKCE/client secrets; the store owns encryption, TTL and atomic consume.
+ */
+export declare function serializePendingWebFlow(flow: PendingWebFlow): string;
+/**
+ * Validate a JSON string or decoded JSON value (e.g. PostgreSQL jsonb), and revive
+ * createdAt/expiresAt as Dates. Unknown fields (including client metadata)
+ * pass through unchanged. Malformed input
+ * returns null. Expiry and issuer trust are enforced by the store/callback,
+ * not by this parser; legacy rows without a frozen issuer remain parseable.
+ * The store must also bind the parsed state to the key it consumed.
+ */
+export declare function parsePendingWebFlow(json: unknown): PendingWebFlow | null;

package/dist/lib/auth/oauth/pending-web-flow.d.ts

@@ -0,0 +1,16 @@
+import type { PendingWebFlow } from './web-flow';
+/**
+ * Serialize a pending flow for a durable store, preserving unknown fields.
+ * Throws for malformed SDK fields or JSON.stringify failures. The payload
+ * contains PKCE/client secrets; the store owns encryption, TTL and atomic consume.
+ */
+export declare function serializePendingWebFlow(flow: PendingWebFlow): string;
+/**
+ * Validate a JSON string or decoded JSON value (e.g. PostgreSQL jsonb), and revive
+ * createdAt/expiresAt as Dates. Unknown fields (including client metadata)
+ * pass through unchanged. Malformed input
+ * returns null. Expiry and issuer trust are enforced by the store/callback,
+ * not by this parser; legacy rows without a frozen issuer remain parseable.
+ * The store must also bind the parsed state to the key it consumed.
+ */
+export declare function parsePendingWebFlow(json: unknown): PendingWebFlow | null;

package/dist/lib/auth/oauth/pending-web-flow.js

@@ -0,0 +1,66 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var pending_web_flow_exports = {};
+__export(pending_web_flow_exports, {
+  parsePendingWebFlow: () => parsePendingWebFlow,
+  serializePendingWebFlow: () => serializePendingWebFlow
+});
+module.exports = __toCommonJS(pending_web_flow_exports);
+var import_auth = require("@modelcontextprotocol/sdk/shared/auth.js");
+var import_zod = require("zod");
+const persistedDate = import_zod.z.iso.datetime({ offset: true }).transform((value) => new Date(value)).pipe(import_zod.z.date());
+const pendingWebFlowShape = {
+  state: import_zod.z.string(),
+  agentId: import_zod.z.string(),
+  agentUrl: import_zod.z.string(),
+  codeVerifier: import_zod.z.string(),
+  redirectUri: import_zod.z.string(),
+  resource: import_zod.z.string().optional(),
+  resourceOverride: import_zod.z.string().optional(),
+  resourceOverrideAction: import_zod.z.enum(["set", "clear"]).optional(),
+  resourceOverrideSnapshot: import_zod.z.string().nullable().optional(),
+  scope: import_zod.z.string().optional(),
+  authorizationServerUrl: import_zod.z.string(),
+  authorizationServerIssuer: import_zod.z.string().optional(),
+  // The MCP schema strips extensions and catches invalid issuer values. Stored
+  // credentials must retain extensions and reject a malformed issuer instead.
+  clientInformation: import_auth.OAuthClientInformationSchema.extend({ issuer: import_zod.z.string().optional() }).loose(),
+  createdAt: persistedDate,
+  expiresAt: persistedDate,
+  carry: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+};
+const persistedPendingWebFlowSchema = import_zod.z.looseObject(pendingWebFlowShape);
+function serializePendingWebFlow(flow) {
+  const json = JSON.stringify(flow);
+  if (!parsePendingWebFlow(json)) throw new TypeError("Invalid PendingWebFlow payload");
+  return json;
+}
+function parsePendingWebFlow(json) {
+  try {
+    const parsed = persistedPendingWebFlowSchema.safeParse(typeof json === "string" ? JSON.parse(json) : json);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parsePendingWebFlow,
+  serializePendingWebFlow
+});

package/dist/lib/auth/oauth/pending-web-flow.mjs

@@ -0,0 +1,41 @@
+import { OAuthClientInformationSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { z } from "zod";
+const persistedDate = z.iso.datetime({ offset: true }).transform((value) => new Date(value)).pipe(z.date());
+const pendingWebFlowShape = {
+  state: z.string(),
+  agentId: z.string(),
+  agentUrl: z.string(),
+  codeVerifier: z.string(),
+  redirectUri: z.string(),
+  resource: z.string().optional(),
+  resourceOverride: z.string().optional(),
+  resourceOverrideAction: z.enum(["set", "clear"]).optional(),
+  resourceOverrideSnapshot: z.string().nullable().optional(),
+  scope: z.string().optional(),
+  authorizationServerUrl: z.string(),
+  authorizationServerIssuer: z.string().optional(),
+  // The MCP schema strips extensions and catches invalid issuer values. Stored
+  // credentials must retain extensions and reject a malformed issuer instead.
+  clientInformation: OAuthClientInformationSchema.extend({ issuer: z.string().optional() }).loose(),
+  createdAt: persistedDate,
+  expiresAt: persistedDate,
+  carry: z.record(z.string(), z.unknown()).optional()
+};
+const persistedPendingWebFlowSchema = z.looseObject(pendingWebFlowShape);
+function serializePendingWebFlow(flow) {
+  const json = JSON.stringify(flow);
+  if (!parsePendingWebFlow(json)) throw new TypeError("Invalid PendingWebFlow payload");
+  return json;
+}
+function parsePendingWebFlow(json) {
+  try {
+    const parsed = persistedPendingWebFlowSchema.safeParse(typeof json === "string" ? JSON.parse(json) : json);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  parsePendingWebFlow,
+  serializePendingWebFlow
+};

package/dist/lib/auth/oauth/web-flow.js

@@ -223,7 +223,7 @@ async function completeWebOAuthFlow(opts) {
     throw new StateMismatchError();
   }
   const flow = await pendingFlowStore.consume(state);
-  if (!flow || flow.expiresAt.getTime() < Date.now()) {
+  if (!flow || flow.expiresAt.getTime() <= Date.now()) {
     throw new InvalidOrExpiredFlowError(state);
   }
   const guardedFetch = createSsrfSafeOAuthFetch(fetchFn, allowHttp);
@@ -345,14 +345,14 @@ class InMemoryPendingFlowStore {
     const flow = this.flows.get(state);
     if (!flow) return null;
     this.flows.delete(state);
-    if (flow.expiresAt.getTime() < Date.now()) return null;
+    if (flow.expiresAt.getTime() <= Date.now()) return null;
     return flow;
   }
   async cleanupExpired() {
     const now = Date.now();
     let removed = 0;
     for (const [state, flow] of this.flows) {
-      if (flow.expiresAt.getTime() < now) {
+      if (flow.expiresAt.getTime() <= now) {
         this.flows.delete(state);
         removed++;
       }

package/dist/lib/auth/oauth/web-flow.mjs

@@ -202,7 +202,7 @@ async function completeWebOAuthFlow(opts) {
     throw new StateMismatchError();
   }
   const flow = await pendingFlowStore.consume(state);
-  if (!flow || flow.expiresAt.getTime() < Date.now()) {
+  if (!flow || flow.expiresAt.getTime() <= Date.now()) {
     throw new InvalidOrExpiredFlowError(state);
   }
   const guardedFetch = createSsrfSafeOAuthFetch(fetchFn, allowHttp);
@@ -324,14 +324,14 @@ class InMemoryPendingFlowStore {
     const flow = this.flows.get(state);
     if (!flow) return null;
     this.flows.delete(state);
-    if (flow.expiresAt.getTime() < Date.now()) return null;
+    if (flow.expiresAt.getTime() <= Date.now()) return null;
     return flow;
   }
   async cleanupExpired() {
     const now = Date.now();
     let removed = 0;
     for (const [state, flow] of this.flows) {
-      if (flow.expiresAt.getTime() < now) {
+      if (flow.expiresAt.getTime() <= now) {
         this.flows.delete(state);
         removed++;
       }

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.