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

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

@@ -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.
      *