@adcp/sdk 16.0.0-beta.8 → 16.0.0-beta.9

package/AGENTS.md

@@ -19,7 +19,7 @@ This document contains essential guidelines for AI coding assistants (Claude, Co
 
 **Testing an agent for conformance?** — Read `docs/guides/CONFORMANCE.md` and call `runConformance(agentUrl, opts)` from `@adcp/sdk/conformance`. Property-based fuzzing against the bundled JSON schemas; stateless tier covers 11 discovery tools across every protocol.
 
-**Migration guides** — [Account change feed](docs/migration-account-change-feed.md) (wake-up parsing, guarded bootstrap/drain, subscriber registration and ownership boundaries); `docs/migration-6.6-to-6.7.md` (fifteen adopter recipes; two breaking changes — `'implicit'` enforces inline-`account_id` refusal and `SalesPlatform` split into `SalesCorePlatform & SalesIngestionPlatform`; plus `definePlatform` helpers, `composeMethod`, `accounts.resolve` security presets, `accounts.upsert/list/syncGovernance(ctx)`, typed errors, `issues[].hint`, `BuyerAgentRegistry`, `createTenantRegistry`, `createOAuthPassthroughResolver`, `createRosterAccountStore`, `createTenantStore` w/ built-in tenant gate, `MEDIA_BUY_TRANSITIONS` lifecycle helpers, `createMediaBuyStore` for `targeting_overlay` echo, `NoAccountCtx` narrow, `refAccountId(ref)`); `docs/migration-5.x-to-6.x.md` (5 → 6 framework shape); `docs/migration-4.x-to-5.x.md` (4 → 5); `docs/migration-buyer-agent-registry.md` (registry deep-dive).
+**Migration guides** — [AdCP 2 retirement](docs/migration-drop-adcp-2.md) (AdCP 3-only discovery, removed compatibility APIs, and last supporting SDK pins); [Account change feed](docs/migration-account-change-feed.md) (wake-up parsing, guarded bootstrap/drain, subscriber registration and ownership boundaries); `docs/migration-6.6-to-6.7.md` (fifteen adopter recipes; two breaking changes — `'implicit'` enforces inline-`account_id` refusal and `SalesPlatform` split into `SalesCorePlatform & SalesIngestionPlatform`; plus `definePlatform` helpers, `composeMethod`, `accounts.resolve` security presets, `accounts.upsert/list/syncGovernance(ctx)`, typed errors, `issues[].hint`, `BuyerAgentRegistry`, `createTenantRegistry`, `createOAuthPassthroughResolver`, `createRosterAccountStore`, `createTenantStore` w/ built-in tenant gate, `MEDIA_BUY_TRANSITIONS` lifecycle helpers, `createMediaBuyStore` for `targeting_overlay` echo, `NoAccountCtx` narrow, `refAccountId(ref)`); `docs/migration-5.x-to-6.x.md` (5 → 6 framework shape); `docs/migration-4.x-to-5.x.md` (4 → 5); `docs/migration-buyer-agent-registry.md` (registry deep-dive).
 
 **Putting credentials in `ctx_metadata`?** — Don't. Read `docs/guides/CTX-METADATA-SAFETY.md` — wire-strip protects buyer responses but not log lines / error envelopes / heap dumps / adopter strings. Re-derive bearers per request; embed only non-secret upstream IDs.
 
@@ -263,7 +263,7 @@ npm run generate-zod-schemas  # Generate runtime validation
 
 ### Wire-version compat (v3 SDK ↔ legacy sellers)
 
-The SDK speaks one AdCP major (`ADCP_VERSION` in `src/lib/version.ts`, currently `3.2.5`) on its public surface and adapts to legacy sellers underneath. v2.5 is the only active legacy shim; the recipe for adding a new one (e.g. v3 when the SDK pin moves to v4) lives in [`docs/development/WIRE-VERSION-COMPAT.md`](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/development/WIRE-VERSION-COMPAT.md). Touch that doc whenever you add to `src/lib/adapters/legacy/`, `src/lib/types/v*-*/`, or `schemas/cache/<version>/`.
+The SDK speaks one AdCP major (`ADCP_VERSION` in `src/lib/version.ts`, currently `3.2.5`) on its public surface and adapts to legacy sellers underneath. AdCP 2 support has been removed following its August 1, 2026 end of life. Maintained AdCP 3 compatibility and the policy for future major-version support are documented in [`docs/development/WIRE-VERSION-COMPAT.md`](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/development/WIRE-VERSION-COMPAT.md). Touch that doc whenever you add to `src/lib/adapters/legacy/`, `src/lib/types/v*-*/`, or `schemas/cache/<version>/`.
 
 ## Testing Strategies
 
@@ -317,7 +317,7 @@ The pattern:
 
 - `normalizeRequestParams()` runs before validation, filling in derivable fields
 - `validateRequest()` runs Zod schemas after normalization
-- `adaptRequestForServerVersion()` handles v3→v2 downgrades for older servers
+- `adaptRequestForServerVersion()` adapts requests to maintained AdCP 3 releases; AdCP 2 targets are rejected
 
 **Never add a required field without a backwards-compatible default or inference path.**
 

package/README.md

@@ -34,6 +34,8 @@ npm install @adcp/sdk@adcp-3.1     # 13.x, maintained AdCP 3.1 line
 npm install @adcp/sdk@adcp-3.0     # 7.11.x, AdCP 3.0
 ```
 
+AdCP 2 reached end of life on August 1, 2026. This checkout supports AdCP 3 agents only; review the [AdCP 2 retirement guide](./docs/migration-drop-adcp-2.md) before upgrading an integration that still calls AdCP 2 sellers.
+
 Upgrading to SDK 14? Read the [release-bound upgrade worksheet](./docs/migration-14.x-rc-worksheet.md), then use the [13-to-14](./docs/migration-13-to-14.md) or [12-to-14](./docs/migration-12-to-14.md) migration guide. The [prerelease history](./docs/releases/14.0.0-beta.0.md) covers changes made during the 14.0 beta cycle. The npm `latest` tag tracks SDK 14 (AdCP 3.2); SDK 13 stays available on `adcp-3.1` as the maintained AdCP 3.1 line. SDK 14 requires Node.js `^20.19.0 || >=22.12.0`. Older paths: [12-to-13](./docs/migration-12-to-13.md), **[MIGRATION-v8.md](./MIGRATION-v8.md)**, and [8.0-to-8.1](./docs/migration-8.0-to-8.1.md).
 
 ### Narrow type imports (`@adcp/sdk/types/<tool>`)
@@ -103,6 +105,7 @@ Start with the persona guide that matches your job:
 - [Build a seller](./docs/guides/SELLER-QUICKSTART-3.2.md)
 - [Call a seller](./docs/guides/BUYER-QUICKSTART-3.2.md)
 - [Adopt the account change feed](./docs/migration-account-change-feed.md)
+- [Upgrade an integration that still uses AdCP 2](./docs/migration-drop-adcp-2.md)
 - [Upgrade from SDK 13](./docs/migration-13-to-14.md)
 - [Add AdCP to an existing platform](./docs/guides/EXISTING-PLATFORM.md)
 - [Run in production](./docs/guides/PRODUCTION-DURABILITY.md)

package/bin/adcp.js

@@ -2023,7 +2023,6 @@ OPTIONS:
   --wait            Wait for async/webhook responses
   --json            Raw JSON output
   --debug           Debug output
-  --allow-v2        Suppress the v2-sunset warning (unsupported since 2026-04-20)
   --help, -h        Show help
 
 BUILT-IN AGENTS:
@@ -2121,7 +2120,7 @@ RUN OPTIONS (full assessment):
   --media-buy-lifecycle-compat
                       Route compact media-buy storyboard steps through the
                       SDK compatibility coordinator so the same storyboard can
-                      exercise established v2.5–3.2 sellers.
+                      exercise established AdCP 3.0–3.2 sellers.
   --media-buy-compat-losses LOSSES
                       Comma-separated guarantee losses explicitly accepted by
                       that coordinator (for example feed_version_not_atomic).
@@ -4222,7 +4221,7 @@ function printFixtureResolution(records, coverageGaps) {
     const scope = record.product_handle ? `${record.product_handle}/` : '';
     if (record.status === 'resolved') {
       const ids = record.seller_ids || {};
-      const sellerId = ids.pricing_option_id || ids.product_id || '?';
+      const sellerId = ids.pricing_option_id || ids.product_id || ids.capability_id || ids.format_id?.id || '?';
       console.log(`  ✅ ${record.fixture_type} ${scope}${record.handle} → ${sellerId} (${record.strategy})`);
     } else if (record.status === 'unsatisfied') {
       continue;
@@ -5841,6 +5840,12 @@ function formatVerdict(verdict) {
 
 async function main() {
   const args = process.argv.slice(2);
+  if (args.some(arg => arg === '--allow-v2' || arg.startsWith('--allow-v2='))) {
+    console.error(
+      'ERROR: --allow-v2 has been removed. AdCP 2 reached end of life on 2026-08-01; upgrade the agent to AdCP 3. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-drop-adcp-2.md'
+    );
+    process.exit(2);
+  }
   if (args[0] === 'identity') return require('./adcp-identity.js').handleIdentityCommand(args.slice(1));
 
   // `--version` / `-v` is handled before subcommands and before the
@@ -5859,14 +5864,6 @@ async function main() {
   // skipped in CI, non-TTY, --json, and when ADCP_SKIP_VERSION_CHECK=1.
   scheduleVersionCheck(LIBRARY_VERSION);
 
-  // Global: suppress the v2-sunset warning before any subcommand runs.
-  // v2 went unsupported on 2026-04-20 (AdCP 3.0 GA, adcp#2220) — the library
-  // warns whenever an agent advertises v2 capabilities. The flag is for
-  // legacy holdouts who know what they're doing.
-  if (args.includes('--allow-v2')) {
-    process.env.ADCP_ALLOW_V2 = '1';
-  }
-
   // Handle subcommands before global --help so their own --help works
   if (args[0] === 'registry') {
     const code = await handleRegistryCommand(args.slice(1));
@@ -5877,7 +5874,7 @@ async function main() {
   if (args[0] === 'init') {
     const { handleInitCommand } = require('./adcp-project.js');
     await handleInitCommand(
-      args.slice(1).filter(arg => arg !== '--allow-v2' && arg !== '--allow-http'),
+      args.slice(1).filter(arg => arg !== '--allow-http'),
       { libraryVersion: LIBRARY_VERSION }
     );
     return;
@@ -5886,7 +5883,7 @@ async function main() {
   if (args[0] === 'doctor') {
     const { handleDoctorCommand } = require('./adcp-project.js');
     await handleDoctorCommand(
-      args.slice(1).filter(arg => arg !== '--allow-v2' && arg !== '--allow-http'),
+      args.slice(1).filter(arg => arg !== '--allow-http'),
       {
         libraryVersion: LIBRARY_VERSION,
         adcpVersion: ADCP_VERSION,

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

@@ -160,7 +160,7 @@ export type TaskRequestFor<K extends AdcpTaskName> = TaskRequestTypeMap[K];
  * - `governance` — buyer-side governance config
  * - `requireV3ForMutations` — enforce AdCP v3 before dispatching mutating tools
  */
-export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'allowV2' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
+export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
     /**
      * Human-readable name for this agent, used in debug logs and
      * `getAgentName()`. Defaults to `'in-process'`.
@@ -536,8 +536,10 @@ export declare class AgentClient {
     /**
      * Resolve the creative wire mode used by canonical writes without sending a
      * mutation. Uses capabilities, this tool's input schema, and the client wire
-     * pin. Older peers with insufficient evidence return `unknown` and require
-     * an unambiguous legacy reference during projection; conflicting evidence
+     * pin. Older peers with insufficient evidence return `unknown`; a matching
+     * seller-advertised product option can establish canonical delivery for an
+     * individual 3.1 write. Otherwise projection requires an unambiguous legacy
+     * reference. Conflicting evidence
      * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
      */
     resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
@@ -553,13 +555,12 @@ export declare class AgentClient {
      * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`, or
      * throw when a v3 seller omits the (required) declaration.
      *
-     * Returns `undefined` for v2 agents — v2 pre-dates the idempotency envelope.
      */
     getIdempotencyReplayTtlSeconds(): Promise<number | undefined>;
     /**
      * Assert that the seller's capabilities corroborate this client's pinned
      * AdCP major (per `getAdcpVersion()`). Throws `VersionUnsupportedError`
-     * otherwise. Set `ADCP_ALLOW_V2=1` to bypass.
+     * otherwise.
      */
     requireSupportedMajor(taskType?: string): Promise<void>;
     /**
@@ -739,6 +740,8 @@ export declare class AgentClient {
      * Get the agent protocol
      */
     getProtocol(): 'mcp' | 'a2a';
+    /** Resolved MCP endpoint already used by this client; never performs discovery. */
+    getDiscoveredMcpEndpoint(): string | undefined;
     /**
      * Get the canonical base URL for this agent
      *

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

@@ -160,7 +160,7 @@ export type TaskRequestFor<K extends AdcpTaskName> = TaskRequestTypeMap[K];
  * - `governance` — buyer-side governance config
  * - `requireV3ForMutations` — enforce AdCP v3 before dispatching mutating tools
  */
-export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'allowV2' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
+export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'wireAdcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations' | 'deferredStorage' | 'resolveDeferredAgent' | 'deferredTaskTtlSeconds'> & {
     /**
      * Human-readable name for this agent, used in debug logs and
      * `getAgentName()`. Defaults to `'in-process'`.
@@ -536,8 +536,10 @@ export declare class AgentClient {
     /**
      * Resolve the creative wire mode used by canonical writes without sending a
      * mutation. Uses capabilities, this tool's input schema, and the client wire
-     * pin. Older peers with insufficient evidence return `unknown` and require
-     * an unambiguous legacy reference during projection; conflicting evidence
+     * pin. Older peers with insufficient evidence return `unknown`; a matching
+     * seller-advertised product option can establish canonical delivery for an
+     * individual 3.1 write. Otherwise projection requires an unambiguous legacy
+     * reference. Conflicting evidence
      * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
      */
     resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: Pick<TaskOptions, 'signal' | 'transport'>): Promise<CreativeFormatWireMode>;
@@ -553,13 +555,12 @@ export declare class AgentClient {
      * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`, or
      * throw when a v3 seller omits the (required) declaration.
      *
-     * Returns `undefined` for v2 agents — v2 pre-dates the idempotency envelope.
      */
     getIdempotencyReplayTtlSeconds(): Promise<number | undefined>;
     /**
      * Assert that the seller's capabilities corroborate this client's pinned
      * AdCP major (per `getAdcpVersion()`). Throws `VersionUnsupportedError`
-     * otherwise. Set `ADCP_ALLOW_V2=1` to bypass.
+     * otherwise.
      */
     requireSupportedMajor(taskType?: string): Promise<void>;
     /**
@@ -739,6 +740,8 @@ export declare class AgentClient {
      * Get the agent protocol
      */
     getProtocol(): 'mcp' | 'a2a';
+    /** Resolved MCP endpoint already used by this client; never performs discovery. */
+    getDiscoveredMcpEndpoint(): string | undefined;
     /**
      * Get the canonical base URL for this agent
      *

package/dist/lib/core/AgentClient.js

@@ -794,8 +794,10 @@ class AgentClient {
   /**
    * Resolve the creative wire mode used by canonical writes without sending a
    * mutation. Uses capabilities, this tool's input schema, and the client wire
-   * pin. Older peers with insufficient evidence return `unknown` and require
-   * an unambiguous legacy reference during projection; conflicting evidence
+   * pin. Older peers with insufficient evidence return `unknown`; a matching
+   * seller-advertised product option can establish canonical delivery for an
+   * individual 3.1 write. Otherwise projection requires an unambiguous legacy
+   * reference. Conflicting evidence
    * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
    */
   async resolveCreativeFormatWireMode(taskType, options) {
@@ -821,7 +823,6 @@ class AgentClient {
    * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`, or
    * throw when a v3 seller omits the (required) declaration.
    *
-   * Returns `undefined` for v2 agents — v2 pre-dates the idempotency envelope.
    */
   async getIdempotencyReplayTtlSeconds() {
     return this.client.getIdempotencyReplayTtlSeconds();
@@ -829,7 +830,7 @@ class AgentClient {
   /**
    * Assert that the seller's capabilities corroborate this client's pinned
    * AdCP major (per `getAdcpVersion()`). Throws `VersionUnsupportedError`
-   * otherwise. Set `ADCP_ALLOW_V2=1` to bypass.
+   * otherwise.
    */
   async requireSupportedMajor(taskType = "request") {
     return this.client.requireSupportedMajor(taskType);
@@ -1173,6 +1174,10 @@ class AgentClient {
   getProtocol() {
     return this.client.getProtocol();
   }
+  /** Resolved MCP endpoint already used by this client; never performs discovery. */
+  getDiscoveredMcpEndpoint() {
+    return this.client.getDiscoveredMcpEndpoint();
+  }
   /**
    * Get the canonical base URL for this agent
    *

package/dist/lib/core/AgentClient.mjs

@@ -762,8 +762,10 @@ class AgentClient {
   /**
    * Resolve the creative wire mode used by canonical writes without sending a
    * mutation. Uses capabilities, this tool's input schema, and the client wire
-   * pin. Older peers with insufficient evidence return `unknown` and require
-   * an unambiguous legacy reference during projection; conflicting evidence
+   * pin. Older peers with insufficient evidence return `unknown`; a matching
+   * seller-advertised product option can establish canonical delivery for an
+   * individual 3.1 write. Otherwise projection requires an unambiguous legacy
+   * reference. Conflicting evidence
    * or unproven support with a 3.2+ buyer pin throws `CreativeFormatCapabilityError`.
    */
   async resolveCreativeFormatWireMode(taskType, options) {
@@ -789,7 +791,6 @@ class AgentClient {
    * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`, or
    * throw when a v3 seller omits the (required) declaration.
    *
-   * Returns `undefined` for v2 agents — v2 pre-dates the idempotency envelope.
    */
   async getIdempotencyReplayTtlSeconds() {
     return this.client.getIdempotencyReplayTtlSeconds();
@@ -797,7 +798,7 @@ class AgentClient {
   /**
    * Assert that the seller's capabilities corroborate this client's pinned
    * AdCP major (per `getAdcpVersion()`). Throws `VersionUnsupportedError`
-   * otherwise. Set `ADCP_ALLOW_V2=1` to bypass.
+   * otherwise.
    */
   async requireSupportedMajor(taskType = "request") {
     return this.client.requireSupportedMajor(taskType);
@@ -1141,6 +1142,10 @@ class AgentClient {
   getProtocol() {
     return this.client.getProtocol();
   }
+  /** Resolved MCP endpoint already used by this client; never performs discovery. */
+  getDiscoveredMcpEndpoint() {
+    return this.client.getDiscoveredMcpEndpoint();
+  }
   /**
    * Get the canonical base URL for this agent
    *

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

@@ -380,35 +380,8 @@ export interface SingleAgentClientConfig extends ConversationConfig {
      * @default true
      */
     validateFeatures?: boolean;
-    /**
-     * Gate mutating-task dispatch on the seller's declared major version.
-     * When the seller returns an authoritative `get_adcp_capabilities`
-     * response, the guard requires:
-     *   1. `major_versions` includes 3
-     *   2. `adcp.idempotency.replay_ttl_seconds` is declared (spec-required)
-     *
-     * Sellers whose capabilities are synthesized from `tools/list` (no
-     * authoritative `get_adcp_capabilities` response) route through the
-     * v2 adapter with a one-time warning — a compliant v3 seller would
-     * declare itself, so absence of a declaration is read as v2. Adopters
-     * who need a hard "definitely-v3" gate should validate
-     * `(await client.getCapabilities())._synthetic === false` directly.
-     *
-     * Throws `VersionUnsupportedError` before the request is sent when
-     * the guard rejects. Bypass with `allowV2` or — process-wide as a
-     * fallback — `ADCP_ALLOW_V2=1`.
-     *
-     * @default false
-     */
+    /** Require release compatibility and the declared idempotency replay TTL before mutations. */
     requireV3ForMutations?: boolean;
-    /**
-     * Per-client bypass for the v3 guard. When `true`, the guard is off
-     * regardless of the `ADCP_ALLOW_V2` env var. When `undefined`, the env
-     * var is consulted as a fallback. Set explicitly in multi-tenant
-     * deployments so one tenant's override can't silently disable safety
-     * for another.
-     */
-    allowV2?: boolean;
     /**
      * Runtime schema validation options
      */
@@ -593,9 +566,7 @@ export declare class SingleAgentClient {
     private discoveredEndpointExpiresAt?;
     private sharedEvidenceEpoch?;
     private sharedEvidenceKey?;
-    private _v2WarningFired;
     private _syntheticV3WarningFired;
-    private _syntheticV2WarningFired;
     private readonly productPolicyRequestParamsByTask;
     private readonly canonicalCreativeTaskAssociations;
     private readonly previewCreativeHandlersByTask;
@@ -882,7 +853,7 @@ export declare class SingleAgentClient {
     /**
      * Execute task and call appropriate handler on completion
      *
-     * Automatically adapts requests for v2 servers and normalizes responses.
+     * Adapts requests for maintained AdCP 3 releases and normalizes product responses.
      */
     private executeAndHandle;
     private executeAndHandleWithinDeadline;
@@ -928,8 +899,7 @@ export declare class SingleAgentClient {
     private applyProductPropertyPolicyToWebhookResult;
     /**
      * Adapt a request for the detected server wire version and the seller's
-     * AdCP protocol version. Applies wire-format adapters (v2.5) when talking
-     * to a v2 server, then applies protocol-version adapters (e.g. stripping
+     * AdCP protocol version. Applies protocol-version adapters (e.g. stripping
      * 3.1-only fields for a 3.0 seller). Returns the adapted params and any
      * drift log entries describing what was changed.
      *
@@ -937,22 +907,7 @@ export declare class SingleAgentClient {
      * current call's tool schemas can be supplied without cross-tenant caching.
      */
     private adaptRequest;
-    /**
-     * Normalize response to v3 format
-     *
-     * Converts v2 responses to v3 structure for consistent API surface.
-     */
-    private normalizeResponseToV3;
-    /**
-     * Check if request uses v3 features that the server doesn't support
-     *
-     * Returns an early empty result if the request requires v3 features
-     * that the server doesn't support. This treats "products matching unsupported
-     * capability" as an empty result set rather than an error.
-     *
-     * @returns TaskResult with empty data if v3 features are unsupported, null to proceed normally
-     */
-    private getEarlyResultForUnsupportedFeatures;
+    private normalizeEstablishedResponse;
     /**
      * Discover available advertising products
      *
@@ -1041,14 +996,17 @@ export declare class SingleAgentClient {
      * sending a mutation. Discovers capabilities and the current tool's input
      * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
      *
-     * `unknown` preserves the conservative legacy projection for older peers
-     * whose capabilities and schema do not establish support. Projection still
-     * requires an unambiguous legacy reference for each creative in that case.
+     * This context-free check returns `unknown` when capabilities and schema do
+     * not establish support. A write to a proven 3.1 seller can still select
+     * canonical delivery from matching seller-advertised product options;
+     * otherwise projection requires an unambiguous legacy reference.
      * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
      * `CreativeFormatCapabilityError`, just as they do during a write.
      */
     resolveCreativeFormatWireMode(taskType: 'sync_creatives' | 'create_media_buy' | 'update_media_buy', options?: ReadRequestOptions): Promise<CreativeFormatWireMode>;
     private resolveCreativeWireMode;
+    /** Product evidence applies to this request only; it must never prime a tool-wide capability. */
+    private productOptionsSupportCanonicalWire;
     /** Validate malformed creative payloads before capability discovery can perform I/O. */
     private validateBeforeCreativeCapabilityProbe;
     /**
@@ -1358,6 +1316,8 @@ export declare class SingleAgentClient {
      * Get the agent protocol (may be normalized from original config)
      */
     getProtocol(): 'mcp' | 'a2a';
+    /** Resolved MCP endpoint already used by this client; never performs discovery. */
+    getDiscoveredMcpEndpoint(): string | undefined;
     /**
      * Get the canonical base URL for this agent
      *
@@ -1526,7 +1486,7 @@ export declare class SingleAgentClient {
      * Get agent capabilities, including AdCP version support
      *
      * For v3 servers, calls get_adcp_capabilities tool.
-     * For v2 servers, builds synthetic capabilities from available tools.
+     * Requires AdCP 3 capability discovery; retired AdCP 2 agents are rejected.
      *
      * @returns Promise resolving to normalized capabilities object
      *
@@ -1675,20 +1635,8 @@ export declare class SingleAgentClient {
     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.
-     *
-     * v2 went unsupported on 2026-04-20 (AdCP 3.0 GA — adcp#2220). We still
-     * execute v2 code paths (no behaviour change), but clients integrating
-     * against an unsupported agent should hear about it loudly.
-     *
-     * Synthetic capabilities (no `get_adcp_capabilities` tool available) don't
-     * trigger the warning — we don't actually know the agent's version, and
-     * shouting at legitimately-unversioned agents would be noise.
-     *
-     * Suppression: `process.env.ADCP_ALLOW_V2 === '1'`.
-     */
-    private maybeWarnV2Sunset;
+    /** Reject retired protocol generations before caching or dispatching. */
+    private assertSupportedServer;
     /**
      * Warn once per client when `requireSupportedMajor` accepts synthetic v3
      * capabilities — the agent advertised the v3-only `get_adcp_capabilities`
@@ -1702,47 +1650,16 @@ export declare class SingleAgentClient {
      * cadence). Issue #1217.
      */
     private maybeWarnSyntheticV3;
-    /**
-     * Warn once per client when `requireSupportedMajor` routes a synthetic-v2
-     * seller through the v2 adapter — the agent did not expose
-     * `get_adcp_capabilities`, so the version was inferred from `tools/list`.
-     * A compliant v3 seller would declare itself; absence of a declaration is
-     * read as v2. Idempotency-TTL guarantees are unknown for these sellers,
-     * so BYOK retry callers should treat them as such.
-     *
-     * One-shot via `_syntheticV2WarningFired` (matches `maybeWarnV2Sunset`
-     * cadence).
-     */
-    private maybeWarnSyntheticV2;
     /**
      * Detect server AdCP version
      *
      * @returns 'v2' or 'v3' based on server capabilities
      */
     detectServerVersion(options?: ReadRequestOptions): Promise<'v2' | 'v3'>;
-    /**
-     * Whether the seller's capabilities are synthesized from `tools/list`
-     * with no authoritative `get_adcp_capabilities` response — i.e. the
-     * dispatcher routes through the v2 adapter and idempotency-TTL is
-     * unknown. Use this to gate retry behavior for sellers whose retry
-     * safety can't be derived from declared capabilities (lower attempt
-     * caps, longer backoff, or fall back to natural-key recovery).
-     *
-     * Returns `false` for declared v2 sellers, declared v3 sellers, and
-     * synthetic v3 sellers (which advertise the v3 discovery tool even
-     * when the call itself failed).
-     *
-     * Caveat for synthetic v3: the predicate returns `false`, but TTL is
-     * still unknown for those sellers — `getIdempotencyReplayTtlSeconds()`
-     * throws until the agent's capabilities endpoint is fixed (issue
-     * #1217). Retry-policy consumers that need a complete "TTL unknown"
-     * gate should additionally check `getCapabilities()._synthetic`.
-     */
-    isSyntheticV2(): Promise<boolean>;
     /**
      * Check if server supports a specific AdCP major version
      */
-    supportsVersion(version: 2 | 3): Promise<boolean>;
+    supportsVersion(version: 3): Promise<boolean>;
     /**
      * Return the seller's declared `adcp.idempotency.replay_ttl_seconds`.
      *
@@ -1752,8 +1669,7 @@ export declare class SingleAgentClient {
      *
      * Fails closed when the seller is v3 but does not declare the field: the
      * spec makes the declaration REQUIRED, and silently defaulting to 24h
-     * would mislead buyers about retry safety. Callers on v2 servers get
-     * `undefined` instead of a throw — v2 pre-dates the idempotency envelope.
+     * would mislead buyers about retry safety.
      */
     getIdempotencyReplayTtlSeconds(): Promise<number | undefined>;
     /**
@@ -1843,16 +1759,8 @@ export declare class SingleAgentClient {
      *   2. `capabilities.idempotency.replayTtlSeconds` present (spec-required
      *      for real major-3+ sellers)
      *
-     * Sellers whose capabilities are synthesized from `tools/list` (no
-     * authoritative `get_adcp_capabilities` response) are treated as v2: a
-     * compliant v3 seller would declare itself, so absence of a declaration
-     * is taken as evidence of v2. The dispatcher routes the request through
-     * the v2 wire-shape adapter. A one-time warning surfaces the routing
-     * decision so adopters can audit it; retry-safety (idempotency TTL) is
-     * unknown for these sellers and BYOK callers should treat them as such.
-     *
-     * Per-client `allowV2: true` or, when that's undefined,
-     * `ADCP_ALLOW_V2=1` in the environment bypasses the guard entirely.
+     * Synthetic v3 evidence is accepted only when the agent advertises discovery.
+     * Agents without discovery and AdCP 2-only agents are rejected.
      *
      * Throws `VersionUnsupportedError` with the specific reason on failure.
      */
@@ -1866,7 +1774,6 @@ export declare class SingleAgentClient {
      * @deprecated Use `requireSupportedMajor()` instead.
      */
     requireV3(taskType?: string): Promise<void>;
-    private isV2Allowed;
     /**
      * Query a legacy creative-agent named-format catalog.
      *