@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/core/AgentClient.mjs

@@ -5,6 +5,8 @@ import {
 import { assertNativeRequestProposalsTask, guardNativeRequestProposalsCompletion } from "./request-proposals-guard.mjs";
 import { buildRefineProposalsRequest } from "../negotiation/buyer.mjs";
 import { assertRefineProposalsResponse } from "../negotiation/verification.mjs";
+import { applicableRefinementServedVersion } from "../negotiation/version.mjs";
+import { toReleasePrecisionVersion } from "../version.mjs";
 function stripRefineProposalsSdkAnnotations(data) {
   const canonical = { ...data };
   delete canonical.success;
@@ -147,6 +149,10 @@ class AgentClient {
   getAdcpVersion() {
     return this.client.getAdcpVersion();
   }
+  /** @internal Original envelope pin, separate from the validation schema pin. */
+  getWireAdcpVersion() {
+    return this.client.getWireAdcpVersion();
+  }
   /**
    * Negotiate one compact-first media-buy facade for this seller.
    *
@@ -480,7 +486,17 @@ class AgentClient {
     this.retainSession(result);
     if (result.success && result.status === "completed") {
       const data = stripRefineProposalsSdkAnnotations(result.data);
-      assertRefineProposalsResponse(request, data);
+      const cachedServedVersion = this.client.getCachedServedAdcpVersion(taskOptions);
+      assertRefineProposalsResponse(request, data, {
+        adcpVersion: this.client.getAdcpVersion(),
+        // Task metadata repeats the response echo. Independently discovered
+        // actual served evidence must constrain that seller-controlled value.
+        servedAdcpVersion: applicableRefinementServedVersion(
+          cachedServedVersion,
+          request.adcp_version,
+          toReleasePrecisionVersion(this.client.getWireAdcpVersion())
+        ) ?? result.metadata.adcpVersion
+      });
       return { ...result, data };
     }
     return result;

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

@@ -503,6 +503,13 @@ export interface TaskResultMetadata {
      * configuration pin, when detecting same-major downshift.
      */
     adcpVersion?: string;
+    /**
+     * Older AdCP release negotiated with the seller for this call. Present only
+     * when it differs from the client's release: the request was converted down
+     * to it and the response converted back up (see `debug_logs` for every
+     * field the conversion removed or moved).
+     */
+    negotiatedAdcpVersion?: string;
     /** Seller wire generation used for this request after capability discovery. */
     serverVersion?: 'v2' | 'v3';
     /** True when {@link serverVersion} came from the SDK's synthetic fallback. */

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

@@ -503,6 +503,13 @@ export interface TaskResultMetadata {
      * configuration pin, when detecting same-major downshift.
      */
     adcpVersion?: string;
+    /**
+     * Older AdCP release negotiated with the seller for this call. Present only
+     * when it differs from the client's release: the request was converted down
+     * to it and the response converted back up (see `debug_logs` for every
+     * field the conversion removed or moved).
+     */
+    negotiatedAdcpVersion?: string;
     /** Seller wire generation used for this request after capability discovery. */
     serverVersion?: 'v2' | 'v3';
     /** True when {@link serverVersion} came from the SDK's synthetic fallback. */

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

@@ -1,6 +1,7 @@
 import { type ListProductsResponseWithSupplyPath, type ProductSupplyPathOptions } from '../supply-path/products.mjs';
 import type { AccountReference, AgentConfig } from '../types/index.mjs';
 import { type AdcpVersion } from '../version.mjs';
+import { type AccountIdentityDowngrade } from '../adapters/version/index.mjs';
 import type { GetProductsRequest, GetProductsResponse, ListProductsRequest, ListCreativeFormatsRequest, ListCreativeFormatsResponse, ListTransformersRequest, ListTransformersResponse, CreateMediaBuyRequest, CreateMediaBuyResponse, UpdateMediaBuyRequest, UpdateMediaBuyResponse, SyncCreativesRequest, SyncCreativesResponse, ListCreativesRequest, ListCreativesResponse, GetMediaBuysRequest, GetMediaBuysResponse, GetMediaBuyDeliveryRequest, GetMediaBuyDeliveryResponse, GetCreativeDeliveryRequest, GetCreativeDeliveryResponse, ProvidePerformanceFeedbackRequest, ProvidePerformanceFeedbackResponse, GetSignalsRequest, GetSignalsResponse, ActivateSignalRequest, ActivateSignalResponse, PreviewCreativeRequest, PreviewCreativeResponse, BuildCreativeRequest, BuildCreativeResponse, Format, GetAdCPCapabilitiesRequest, GetAdCPCapabilitiesResponse, ListAccountChangesRequest, ListAccountChangesResponse, ListAccountsRequest, ListAccountsResponse, SyncAccountsRequest, SyncAccountsResponse, SyncAudiencesRequest, SyncAudiencesResponse, CreatePropertyListRequest, CreatePropertyListResponse, GetPropertyListRequest, GetPropertyListResponse, UpdatePropertyListRequest, UpdatePropertyListResponse, ListPropertyListsRequest, ListPropertyListsResponse, DeletePropertyListRequest, DeletePropertyListResponse, ListContentStandardsRequest, ListContentStandardsResponse, GetContentStandardsRequest, GetContentStandardsResponse, CalibrateContentRequest, CalibrateContentResponse, ValidateContentDeliveryRequest, ValidateContentDeliveryResponse, SIGetOfferingRequest, SIGetOfferingResponse, SIInitiateSessionRequest, SIInitiateSessionResponse, SISendMessageRequest, SISendMessageResponse, SITerminateSessionRequest, SITerminateSessionResponse, SyncPlansRequest, SyncPlansResponse, GetPlanAuditLogsRequest, GetPlanAuditLogsResponse, GetPrincipalRequest, SyncPrincipalRequest, SyncPrincipalResponse, OutcomeType } from '../types/tools.generated.mjs';
 import { type MutatingRequestInput } from '../utils/idempotency.mjs';
 import type { MCPWebhookPayload, TaskStatus } from '../types/core.generated.mjs';
@@ -382,6 +383,29 @@ export interface SingleAgentClientConfig extends ConversationConfig {
     validateFeatures?: boolean;
     /** Require release compatibility and the declared idempotency replay TTL before mutations. */
     requireV3ForMutations?: boolean;
+    /**
+     * What to do when a request reaches a seller on an older AdCP release and
+     * its account key uses fields that release cannot express. AdCP 3.2 added
+     * `operator_unit`, `currency` and `timezone` to the account natural key and
+     * `countries` to brand references; a 3.1 seller's key has none of them.
+     *
+     * - `'refuse'` (default): fail the call before it is sent with
+     *   `ProtocolFeatureUnsupportedError`.
+     * - `'reduce'`: send the older key when that is unambiguous, and refuse when
+     *   it would merge accounts. Each reduced key is claimed for the one buyer
+     *   key it came from (a key sent unreduced claims itself), and a second
+     *   buyer key that would reach the same seller account fails with
+     *   `account_identity_collision` before sending, so no two buyer accounts
+     *   share one seller account. Each reduction is reported in `debug_logs` as
+     *   an `account_identity_reduced` entry. Requires `accountStorage` with
+     *   `compareAndSet`, so the claims hold across instances and restarts.
+     *
+     * The rule is proposed for the spec as adcontextprotocol/adcp DR-0032
+     * (#8373); the default may change to `'reduce'` once it is ratified.
+     *
+     * @default 'refuse'
+     */
+    accountIdentityDowngrade?: AccountIdentityDowngrade;
     /**
      * Runtime schema validation options
      */
@@ -556,6 +580,8 @@ export declare class SingleAgentClient {
     private cachedCapabilities?;
     private runAgentInfo?;
     private cachedToolSchemas?;
+    /** Release negotiated per operation, for converting webhook completions up. */
+    private readonly negotiatedReleaseByOperation;
     private primedCapabilitiesExpiresAt?;
     private capabilityEvidenceScopeKey;
     private capabilityEvidenceAuthMaterial?;
@@ -907,6 +933,62 @@ export declare class SingleAgentClient {
     private productPolicyRequestParamsForWebhook;
     private productPolicyRequestParamsForKey;
     private applyProductPropertyPolicyToWebhookResult;
+    private get accountIdentityDowngrade();
+    /**
+     * Negotiate the AdCP release to speak with this seller for one call: the
+     * highest release both sides support. Returns `undefined` when the call
+     * keeps its configured wire version: an explicit `wireAdcpVersion`
+     * override, a governed payload that must reach the seller byte-for-byte,
+     * the identity 3.3 experiment, or no authoritative seller release
+     * (synthetic capabilities, no release in common, or no release metadata at
+     * all: AdCP 3.1 does not require `supported_versions`, so its absence does
+     * not prove a 3.0 seller, and such sellers keep the 3.0 request adapters).
+     */
+    private negotiateCallRelease;
+    /**
+     * Per-call options carrying the negotiated release to the executor, which
+     * stamps it on the version envelope and validates the response against it.
+     */
+    private withNegotiatedRelease;
+    /**
+     * Refuse a tool the negotiated release does not define (a 3.2-only task
+     * sent to a 3.1 seller) with a typed error instead of a seller-side schema
+     * or unknown-tool failure. Sellers that list the tool anyway are called.
+     */
+    private assertToolAvailableAtRelease;
+    /**
+     * Account-key bookkeeping for `accountIdentityDowngrade: 'reduce'`.
+     *
+     * Converting down to an older seller release: claim each reduced key for
+     * the buyer key it came from, and refuse the request when the reduced key
+     * (or an unreduced key the request sends as is) already belongs to a
+     * different buyer key. Without this, two buyer accounts would silently
+     * share one seller account, with merged settings, spend and reads.
+     *
+     * Seller on the client's release: a buyer key that earlier reached this
+     * seller reduced is still addressed by its reduced key, which is the key
+     * the seller's account has, until the caller moves the account to the full
+     * key and calls `client.accounts.clearReduction(key)`.
+     *
+     * Runs only once the account registry is in use or under `'reduce'`.
+     */
+    private reconcileAccountKeyReductions;
+    private throwAccountKeyCollision;
+    private throwFieldsUnsupportedAtRelease;
+    private throwAccountIdentityUnsupported;
+    private rememberNegotiatedRelease;
+    /**
+     * Webhook completions bypass task finalization, so convert their result up
+     * here. The seller's own `adcp_version` names the release it served; an
+     * AdCP 3.0 seller sends none, so fall back to the release this client
+     * negotiated for the operation.
+     */
+    private convertWebhookResultToClientRelease;
+    /**
+     * Convert a response served at the negotiated release up to the client's
+     * release. Returns drift entries for each conversion applied.
+     */
+    private convertResponseToClientRelease;
     /**
      * Adapt a request for the detected server wire version and the seller's
      * AdCP protocol version. Applies protocol-version adapters (e.g. stripping

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

@@ -1,6 +1,7 @@
 import { type ListProductsResponseWithSupplyPath, type ProductSupplyPathOptions } from '../supply-path/products';
 import type { AccountReference, AgentConfig } from '../types';
 import { type AdcpVersion } from '../version';
+import { type AccountIdentityDowngrade } from '../adapters/version';
 import type { GetProductsRequest, GetProductsResponse, ListProductsRequest, ListCreativeFormatsRequest, ListCreativeFormatsResponse, ListTransformersRequest, ListTransformersResponse, CreateMediaBuyRequest, CreateMediaBuyResponse, UpdateMediaBuyRequest, UpdateMediaBuyResponse, SyncCreativesRequest, SyncCreativesResponse, ListCreativesRequest, ListCreativesResponse, GetMediaBuysRequest, GetMediaBuysResponse, GetMediaBuyDeliveryRequest, GetMediaBuyDeliveryResponse, GetCreativeDeliveryRequest, GetCreativeDeliveryResponse, ProvidePerformanceFeedbackRequest, ProvidePerformanceFeedbackResponse, GetSignalsRequest, GetSignalsResponse, ActivateSignalRequest, ActivateSignalResponse, PreviewCreativeRequest, PreviewCreativeResponse, BuildCreativeRequest, BuildCreativeResponse, Format, GetAdCPCapabilitiesRequest, GetAdCPCapabilitiesResponse, ListAccountChangesRequest, ListAccountChangesResponse, ListAccountsRequest, ListAccountsResponse, SyncAccountsRequest, SyncAccountsResponse, SyncAudiencesRequest, SyncAudiencesResponse, CreatePropertyListRequest, CreatePropertyListResponse, GetPropertyListRequest, GetPropertyListResponse, UpdatePropertyListRequest, UpdatePropertyListResponse, ListPropertyListsRequest, ListPropertyListsResponse, DeletePropertyListRequest, DeletePropertyListResponse, ListContentStandardsRequest, ListContentStandardsResponse, GetContentStandardsRequest, GetContentStandardsResponse, CalibrateContentRequest, CalibrateContentResponse, ValidateContentDeliveryRequest, ValidateContentDeliveryResponse, SIGetOfferingRequest, SIGetOfferingResponse, SIInitiateSessionRequest, SIInitiateSessionResponse, SISendMessageRequest, SISendMessageResponse, SITerminateSessionRequest, SITerminateSessionResponse, SyncPlansRequest, SyncPlansResponse, GetPlanAuditLogsRequest, GetPlanAuditLogsResponse, GetPrincipalRequest, SyncPrincipalRequest, SyncPrincipalResponse, OutcomeType } from '../types/tools.generated';
 import { type MutatingRequestInput } from '../utils/idempotency';
 import type { MCPWebhookPayload, TaskStatus } from '../types/core.generated';
@@ -382,6 +383,29 @@ export interface SingleAgentClientConfig extends ConversationConfig {
     validateFeatures?: boolean;
     /** Require release compatibility and the declared idempotency replay TTL before mutations. */
     requireV3ForMutations?: boolean;
+    /**
+     * What to do when a request reaches a seller on an older AdCP release and
+     * its account key uses fields that release cannot express. AdCP 3.2 added
+     * `operator_unit`, `currency` and `timezone` to the account natural key and
+     * `countries` to brand references; a 3.1 seller's key has none of them.
+     *
+     * - `'refuse'` (default): fail the call before it is sent with
+     *   `ProtocolFeatureUnsupportedError`.
+     * - `'reduce'`: send the older key when that is unambiguous, and refuse when
+     *   it would merge accounts. Each reduced key is claimed for the one buyer
+     *   key it came from (a key sent unreduced claims itself), and a second
+     *   buyer key that would reach the same seller account fails with
+     *   `account_identity_collision` before sending, so no two buyer accounts
+     *   share one seller account. Each reduction is reported in `debug_logs` as
+     *   an `account_identity_reduced` entry. Requires `accountStorage` with
+     *   `compareAndSet`, so the claims hold across instances and restarts.
+     *
+     * The rule is proposed for the spec as adcontextprotocol/adcp DR-0032
+     * (#8373); the default may change to `'reduce'` once it is ratified.
+     *
+     * @default 'refuse'
+     */
+    accountIdentityDowngrade?: AccountIdentityDowngrade;
     /**
      * Runtime schema validation options
      */
@@ -556,6 +580,8 @@ export declare class SingleAgentClient {
     private cachedCapabilities?;
     private runAgentInfo?;
     private cachedToolSchemas?;
+    /** Release negotiated per operation, for converting webhook completions up. */
+    private readonly negotiatedReleaseByOperation;
     private primedCapabilitiesExpiresAt?;
     private capabilityEvidenceScopeKey;
     private capabilityEvidenceAuthMaterial?;
@@ -907,6 +933,62 @@ export declare class SingleAgentClient {
     private productPolicyRequestParamsForWebhook;
     private productPolicyRequestParamsForKey;
     private applyProductPropertyPolicyToWebhookResult;
+    private get accountIdentityDowngrade();
+    /**
+     * Negotiate the AdCP release to speak with this seller for one call: the
+     * highest release both sides support. Returns `undefined` when the call
+     * keeps its configured wire version: an explicit `wireAdcpVersion`
+     * override, a governed payload that must reach the seller byte-for-byte,
+     * the identity 3.3 experiment, or no authoritative seller release
+     * (synthetic capabilities, no release in common, or no release metadata at
+     * all: AdCP 3.1 does not require `supported_versions`, so its absence does
+     * not prove a 3.0 seller, and such sellers keep the 3.0 request adapters).
+     */
+    private negotiateCallRelease;
+    /**
+     * Per-call options carrying the negotiated release to the executor, which
+     * stamps it on the version envelope and validates the response against it.
+     */
+    private withNegotiatedRelease;
+    /**
+     * Refuse a tool the negotiated release does not define (a 3.2-only task
+     * sent to a 3.1 seller) with a typed error instead of a seller-side schema
+     * or unknown-tool failure. Sellers that list the tool anyway are called.
+     */
+    private assertToolAvailableAtRelease;
+    /**
+     * Account-key bookkeeping for `accountIdentityDowngrade: 'reduce'`.
+     *
+     * Converting down to an older seller release: claim each reduced key for
+     * the buyer key it came from, and refuse the request when the reduced key
+     * (or an unreduced key the request sends as is) already belongs to a
+     * different buyer key. Without this, two buyer accounts would silently
+     * share one seller account, with merged settings, spend and reads.
+     *
+     * Seller on the client's release: a buyer key that earlier reached this
+     * seller reduced is still addressed by its reduced key, which is the key
+     * the seller's account has, until the caller moves the account to the full
+     * key and calls `client.accounts.clearReduction(key)`.
+     *
+     * Runs only once the account registry is in use or under `'reduce'`.
+     */
+    private reconcileAccountKeyReductions;
+    private throwAccountKeyCollision;
+    private throwFieldsUnsupportedAtRelease;
+    private throwAccountIdentityUnsupported;
+    private rememberNegotiatedRelease;
+    /**
+     * Webhook completions bypass task finalization, so convert their result up
+     * here. The seller's own `adcp_version` names the release it served; an
+     * AdCP 3.0 seller sends none, so fall back to the release this client
+     * negotiated for the operation.
+     */
+    private convertWebhookResultToClientRelease;
+    /**
+     * Convert a response served at the negotiated release up to the client's
+     * release. Returns drift entries for each conversion applied.
+     */
+    private convertResponseToClientRelease;
     /**
      * Adapt a request for the detected server wire version and the seller's
      * AdCP protocol version. Applies protocol-version adapters (e.g. stripping