@adcp/sdk 15.8.0 → 15.9.0

package/compliance/cache/3.2.4/test-vectors/request-signing/profile-3.2/positive/015-bracketed-ipv6-host-with-port.json

@@ -0,0 +1,33 @@
+{
+  "name": "AdCP 3.2 bracketed IPv6 literal with non-default port in both the URL and the Host header (content-digest covered)",
+  "spec_reference": "#adcp-rfc-9421-profile (@authority derived from as-received Host; IPv6 brackets preserved, non-default port kept); AdCP 3.2 profile per #content-digest-and-proxy-compatibility and #adcp-rfc-9421-profile binary value encoding",
+  "signing_profile_version": "3.2",
+  "reference_now": 1776520800,
+  "request": {
+    "method": "POST",
+    "url": "https://[2001:db8::1]:8443/adcp/create_media_buy",
+    "headers": {
+      "Host": "[2001:db8::1]:8443",
+      "Content-Type": "application/json",
+      "Content-Digest": "sha-256=:ilCj0oXvxdCQ4XBo82djX6ROGjCL3pOW94oGtTRDPpc=:",
+      "Signature-Input": "sig1=(\"@method\" \"@target-uri\" \"@authority\" \"content-type\" \"content-digest\");created=1776520800;expires=1776521100;nonce=\"KXYnfEfJ0PBRZXQyVXfVQA\";keyid=\"test-ed25519-2026\";alg=\"ed25519\";tag=\"adcp/request-signing/v1\"",
+      "Signature": "sig1=:6cbQBDeJ7BsVa2Asx3+EWPAtDMhL2fjN2Y8y2j99FNH0t8gOiUyRAeVcaDHYspQ/rLPr/ilV/cizDGpv9kaqDw==:"
+    },
+    "body": "{\"idempotency_key\":\"vector-profile-3-2-positive-015-bracketed-ipv6-host-with-port\",\"account\":{\"brand\":{\"domain\":\"acmeoutdoor.example\"},\"operator\":\"pinnacle-agency.example\",\"sandbox\":false},\"packages\":[{\"product_id\":\"prod-1\",\"budget\":5000.0,\"pricing_option_id\":\"cpm_usd_fixed\",\"paused\":false}],\"brand\":{\"domain\":\"brand.example\"},\"start_time\":\"2027-01-04T00:00:00Z\",\"end_time\":\"2027-02-01T00:00:00Z\",\"paused\":false,\"plan_id\":\"plan_001\"}"
+  },
+  "verifier_capability": {
+    "supported": true,
+    "covers_content_digest": "required",
+    "required_for": [
+      "create_media_buy"
+    ]
+  },
+  "jwks_ref": [
+    "test-ed25519-2026"
+  ],
+  "expected_signature_base": "\"@method\": POST\n\"@target-uri\": https://[2001:db8::1]:8443/adcp/create_media_buy\n\"@authority\": [2001:db8::1]:8443\n\"content-type\": application/json\n\"content-digest\": sha-256=:ilCj0oXvxdCQ4XBo82djX6ROGjCL3pOW94oGtTRDPpc=:\n\"@signature-params\": (\"@method\" \"@target-uri\" \"@authority\" \"content-type\" \"content-digest\");created=1776520800;expires=1776521100;nonce=\"KXYnfEfJ0PBRZXQyVXfVQA\";keyid=\"test-ed25519-2026\";alg=\"ed25519\";tag=\"adcp/request-signing/v1\"",
+  "expected_outcome": {
+    "success": true
+  },
+  "$comment": "3.2-profile counterpart of positive/015-bracketed-ipv6-host-with-port.json. AdCP 3.2 profile: the signature covers content-digest, binary values use RFC 8941 sf-binary (standard padded Base64), and the verifier advertises covers_content_digest='required'. False-positive guard for negative/031. The Host header byte-matches the authority of the canonical @target-uri, so @authority is [2001:db8::1]:8443 and the request verifies. Generated by scripts/generate-request-signing-profile-3.2-vectors.mjs from the test keys in keys.json; do not hand-edit."
+}

package/compliance/cache/{3.2.3 → 3.2.4}/universal/billing-gate-dispatch.yaml

@@ -1,5 +1,5 @@
 id: billing_gate_dispatch
-version: "1.1.1"
+version: "1.1.2"
 title: "Billing contract and gate dispatch — sync_accounts capability vs per-buyer-agent gate"
 category: error_compliance
 summary: "Validates that account.supported_billing is declared and honored by sync_accounts, including out-of-set BILLING_NOT_SUPPORTED rejection, recovery-value consistency, and the distinct per-buyer-agent BILLING_NOT_PERMITTED_FOR_AGENT gate."
@@ -139,7 +139,6 @@ prerequisites:
 phases:
   - id: capability_discovery
     title: "Capability discovery"
-    optional: true
     requires_capability:
       path: "account"
       present: true

package/compliance/cache/{3.2.3 → 3.2.4}/universal/collection-lists-pagination-integrity.yaml

@@ -4,6 +4,9 @@ title: "Pagination cursor integrity — list_collection_lists"
 category: schema_validation
 summary: "Validates the cursor↔has_more invariant by walking a paginated list_collection_lists response from a continuation page to a terminal page."
 track: core
+requires:
+  - controller
+
 required_tools:
   - list_collection_lists
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/content-standards-pagination-integrity.yaml

@@ -4,6 +4,9 @@ title: "Pagination cursor integrity — list_content_standards"
 category: schema_validation
 summary: "Validates the cursor↔has_more invariant by walking a paginated list_content_standards response from a continuation page to a terminal page."
 track: core
+requires:
+  - controller
+
 required_tools:
   - list_content_standards
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/deterministic-testing.yaml

@@ -4,6 +4,9 @@ title: 'Deterministic testing'
 category: core
 summary: 'Uses comply_test_controller to force state transitions and simulate delivery/budget, verifying state machines and reporting.'
 track: core
+requires:
+  - controller
+
 required_tools:
   - comply_test_controller
 platform_types:

package/compliance/cache/{3.2.3 → 3.2.4}/universal/error-compliance-signals.yaml

@@ -4,6 +4,9 @@ title: "Error handling — signals protocol"
 category: error_compliance
 summary: "Validates that signals agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings."
 track: error_handling
+requires:
+  - controller
+
 required_tools:
   - get_signals
   - activate_signal

package/compliance/cache/{3.2.3 → 3.2.4}/universal/error-compliance.yaml

@@ -4,6 +4,9 @@ title: "Error handling and compliance"
 category: error_compliance
 summary: "Validates that agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings."
 track: error_handling
+requires:
+  - controller
+
 required_tools:
   - get_products
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/get-signals-pagination-integrity.yaml

@@ -4,6 +4,9 @@ title: "get_signals pagination cursor integrity"
 category: schema_validation
 summary: "Validates the cursor↔has_more invariant on a paginated get_signals response by walking from a continuation page to the next page under a broad query."
 track: signals
+requires:
+  - controller
+
 required_tools:
   - get_signals
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/idempotency.yaml

@@ -4,6 +4,8 @@ title: "Idempotency enforcement"
 category: core
 summary: "Validates that mutating requests enforce idempotency_key — replays return cached responses even after resource purge, key reuse with a different payload returns IDEMPOTENCY_CONFLICT, fresh keys create new resources, and concurrent retries with the same key produce exactly one resource (first-insert-wins under rule 9)."
 track: core
+requires:
+  - controller
 
 # Cross-step assertions (adcontextprotocol/adcp#2639). These convert two
 # reviewer-only checks from `key_reuse_conflict` and `security` into

package/compliance/cache/{3.2.3 → 3.2.4}/universal/property-lists-pagination-integrity.yaml

@@ -4,6 +4,9 @@ title: "Pagination cursor integrity — list_property_lists"
 category: schema_validation
 summary: "Validates the cursor↔has_more invariant by walking a paginated list_property_lists response from a continuation page to a terminal page."
 track: core
+requires:
+  - controller
+
 required_tools:
   - list_property_lists
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/read-tool-idempotency.yaml

@@ -5,6 +5,9 @@ title: "Read-tool idempotency_key envelope tolerance"
 category: idempotency
 summary: "Validates that read-only AdCP tasks and the 3.x get_products compatibility facade tolerate an optional idempotency_key without claiming read-response replay."
 track: core
+requires:
+  - controller
+
 required_tools: []  # protocol-level baseline; read-tool probes gate themselves per step
 
 narrative: |

package/compliance/cache/{3.2.3 → 3.2.4}/universal/schema-validation-signals.yaml

@@ -4,6 +4,9 @@ title: "Schema compliance — signals protocol"
 category: schema_validation
 summary: "Validates that signals agent responses conform to AdCP schemas with all required fields present and correctly typed."
 track: core
+requires:
+  - controller
+
 required_tools:
   - get_signals
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/schema-validation.yaml

@@ -4,6 +4,9 @@ title: "Schema compliance and temporal validation"
 category: schema_validation
 summary: "Validates that agent responses conform to AdCP schemas and that temporal constraints are enforced."
 track: core
+requires:
+  - controller
+
 required_tools:
   - get_products
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/signed-requests.yaml

@@ -2,7 +2,7 @@ id: signed_requests
 version: "1.0.0"
 title: "Signed requests — RFC 9421 transport-layer verification"
 category: signed_requests
-summary: "Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule."
+summary: "Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule; a verifier advertising `covers_content_digest: \"required\"` (every 3.2+ verifier) is graded against the `profile-3.2/` mirror, which carries a counterpart of every legacy vector (positive `001` and `002` collapse into `positive/001-post-with-content-digest`) except `negative/018` (`forbidden` is illegal in 3.2)."
 track: security_transport
 required_tools:
   - get_adcp_capabilities
@@ -188,6 +188,9 @@ phases:
         019 Signature without Signature-Input → request_signature_header_malformed
         020 per-keyid replay cache cap        → request_signature_rate_abuse
         028 unsigned tasks/cancel + protocol_methods_required_for → request_signature_required
+        029 duplicate label on Signature      → request_signature_header_malformed
+        030 Content-Digest SHA-256 + sha-256  → request_signature_header_malformed
+        031 unbracketed IPv6 in Host header   → request_target_uri_malformed
 
       Vector 028 is gated on `request_signing.protocol_methods_required_for`
       being non-empty: the runner skips when the agent does not declare the

package/compliance/cache/{3.2.3 → 3.2.4}/universal/stale-response-advisory.yaml

@@ -4,6 +4,9 @@ title: "STALE_RESPONSE advisory-success wire placement"
 category: stale_response_advisory
 summary: "Validates that STALE_RESPONSE rides in errors[] on a populated success response with transport success preserved, and that STALE_RESPONSE is absent on healthy upstream responses."
 track: error_handling
+requires:
+  - controller
+
 required_tools:
   - get_products
 

package/compliance/cache/{3.2.3 → 3.2.4}/universal/storyboard-schema.yaml

@@ -176,11 +176,15 @@
 #                    ("skip the whole storyboard if the capability is absent").
 #                    Storyboards may declare both: the gate fires first, and
 #                    controller_seeding takes effect only if the gate passes.
-#                    Declaring controller_seeding: true without requires:
-#                    [controller] is also valid — mid-run, individual steps
-#                    grade missing_test_controller if the agent lacks the
-#                    tool; requires: [controller] coalesces that into a single
-#                    whole-storyboard skip at load time instead.
+#                    A storyboard that declares prerequisites.controller_seeding:
+#                    true MUST also declare requires: [controller] (enforced by
+#                    tests/lint-storyboard-controller-requires.test.cjs). The
+#                    gate coalesces what would otherwise be a
+#                    missing_test_controller grade on every seeded step into a
+#                    single whole-storyboard requirement_unmet skip at load
+#                    time. Whether a given class of seller is expected to
+#                    implement comply_test_controller is a separate policy
+#                    question — see docs/building/by-layer/L3/comply-test-controller.mdx.
 #                    Mid-run transient loss: if the load-phase gate passes
 #                    (the agent advertised comply_test_controller at load
 #                    time) but the tool becomes unavailable mid-run, the

package/compliance/cache/{3.2.3 → 3.2.4}/universal/webhook-emission.yaml

@@ -6,6 +6,7 @@ summary: "Any agent that emits webhooks MUST echo the caller-supplied operation_
 track: core
 requires:
   - webhook_receiver
+  - controller
 
 narrative: |
   Webhook emission is a cross-cutting capability, not a specialism. Sellers emit

package/compliance/cache/{3.2.3 → 3.2.4}/universal/wholesale-feed-products-scope-isolation.yaml

@@ -4,6 +4,9 @@ title: "Wholesale product feed cache-scope isolation"
 category: marketplace_catalog
 summary: "Validates that get_products conditional-fetch is keyed by cache_scope: a wholesale_feed_version minted under one cache_scope must not short-circuit (unchanged: true) a request the seller resolves to a different cache_scope."
 track: media_buy
+requires:
+  - controller
+
 introduced_in: "3.2"
 
 requires_capability:

package/compliance/cache/{3.2.3 → 3.2.4}/universal/wholesale-feed-products.yaml

@@ -4,6 +4,9 @@ title: "Wholesale product feed versioning"
 category: marketplace_catalog
 summary: "Validates get_products wholesale feed versioning: bootstrap responses carry wholesale_feed_version/cache_scope and matching if_wholesale_feed_version probes return unchanged without product rows."
 track: media_buy
+requires:
+  - controller
+
 introduced_in: "3.1"
 
 requires_capability:

package/compliance/cache/{3.2.3 → 3.2.4}/universal/wholesale-feed-signals-scope-isolation.yaml

@@ -4,6 +4,9 @@ title: "Wholesale signals feed cache-scope isolation"
 category: marketplace_catalog
 summary: "Validates that get_signals conditional-fetch is keyed by cache_scope: a wholesale_feed_version minted under one cache_scope must not short-circuit (unchanged: true) a request the agent resolves to a different cache_scope."
 track: signals
+requires:
+  - controller
+
 introduced_in: "3.2"
 
 requires_capability:

package/compliance/cache/{3.2.3 → 3.2.4}/universal/wholesale-feed-signals.yaml

@@ -4,6 +4,9 @@ title: "Wholesale signals feed versioning"
 category: marketplace_catalog
 summary: "Validates get_signals wholesale feed versioning: bootstrap responses carry wholesale_feed_version/cache_scope and matching if_wholesale_feed_version probes return unchanged without signal rows."
 track: signals
+requires:
+  - controller
+
 introduced_in: "3.1"
 
 requires_capability:

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

@@ -6,5 +6,5 @@ export { ConfigurationManager } from '../core/ConfigurationManager.mjs';
 export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStoreOptions, type WebhookAuthenticationMode, type WebhookRegistration, type WebhookRegistrationStore, } from '../core/webhook-registration.mjs';
 export type { ConversationConfig, ConversationContext, InputHandler, InputHandlerResponse, InputRequest, Message, TaskInfo, TaskOptions, TaskResult, TaskResultCompleted, TaskResultFailure, TaskResultIntermediate, TaskResultMetadata, } from '../core/ConversationTypes.mjs';
 export type { AgentConfig } from '../types/adcp.mjs';
-export type { ResolveAccountOptions, ListedAccount } from '../core/account-resolution.mjs';
+export type { ResolveAccountOptions, ResolveAccountResult, ListedAccount } from '../core/account-resolution.mjs';
 export type { CreativeFormatWireMode } from '../v2/projection/creative-delivery.mjs';

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

@@ -6,5 +6,5 @@ export { ConfigurationManager } from '../core/ConfigurationManager';
 export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStoreOptions, type WebhookAuthenticationMode, type WebhookRegistration, type WebhookRegistrationStore, } from '../core/webhook-registration';
 export type { ConversationConfig, ConversationContext, InputHandler, InputHandlerResponse, InputRequest, Message, TaskInfo, TaskOptions, TaskResult, TaskResultCompleted, TaskResultFailure, TaskResultIntermediate, TaskResultMetadata, } from '../core/ConversationTypes';
 export type { AgentConfig } from '../types/adcp';
-export type { ResolveAccountOptions, ListedAccount } from '../core/account-resolution';
+export type { ResolveAccountOptions, ResolveAccountResult, ListedAccount } from '../core/account-resolution';
 export type { CreativeFormatWireMode } from '../v2/projection/creative-delivery';

package/dist/lib/compliance-fixtures/canonical-storyboards-provenance.json

@@ -1,10 +1,10 @@
 {
   "schema_version": 1,
-  "protocol_version": "3.2.3",
+  "protocol_version": "3.2.4",
   "source_repository": "adcontextprotocol/adcp",
-  "source_tag": "v3.2.3",
-  "source_commit": "dfc6ad602780c1cff4fe23e16e30a570900c89d7",
-  "bundle_sha256": "cad841ddef4617fdb6eda130be7b471d9028123489b1384a7ca843ea97fd4ba5",
+  "source_tag": "v3.2.4",
+  "source_commit": "5e6c4b01113237234b440b6c95adb8c6e0a07ca9",
+  "bundle_sha256": "d5a0b167b323e5ee05ac2c8da9ca01c46a5cb5a7b988570f40f746bb8b15ae76",
   "files": {
     "principal": {
       "source_path": "static/compliance/source/universal/principal.yaml",

package/dist/lib/compliance-fixtures/canonical-storyboards.d.mts

@@ -28,7 +28,7 @@ export interface CanonicalStoryboardFixture {
 }
 /** Load the deeply immutable provenance shared by the canonical storyboard fixtures. */
 export declare function loadCanonicalStoryboardFixtureProvenance(): CanonicalStoryboardFixtureProvenance;
-/** Load the exact AdCP 3.2.3 `universal/principal` storyboard. */
+/** Load the exact AdCP 3.2.4 `universal/principal` storyboard. */
 export declare function loadCanonicalPrincipalStoryboard(): CanonicalStoryboardFixture;
-/** Load the exact AdCP 3.2.3 `universal/reporting-core` storyboard. */
+/** Load the exact AdCP 3.2.4 `universal/reporting-core` storyboard. */
 export declare function loadCanonicalReportingCoreStoryboard(): CanonicalStoryboardFixture;

package/dist/lib/compliance-fixtures/canonical-storyboards.d.ts

@@ -28,7 +28,7 @@ export interface CanonicalStoryboardFixture {
 }
 /** Load the deeply immutable provenance shared by the canonical storyboard fixtures. */
 export declare function loadCanonicalStoryboardFixtureProvenance(): CanonicalStoryboardFixtureProvenance;
-/** Load the exact AdCP 3.2.3 `universal/principal` storyboard. */
+/** Load the exact AdCP 3.2.4 `universal/principal` storyboard. */
 export declare function loadCanonicalPrincipalStoryboard(): CanonicalStoryboardFixture;
-/** Load the exact AdCP 3.2.3 `universal/reporting-core` storyboard. */
+/** Load the exact AdCP 3.2.4 `universal/reporting-core` storyboard. */
 export declare function loadCanonicalReportingCoreStoryboard(): CanonicalStoryboardFixture;

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

@@ -1,6 +1,6 @@
 import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
 import type { AccountReference, AgentConfig } from '../types/index.mjs';
-import type { ResolveAccountOptions } from './account-resolution.mjs';
+import type { ResolveAccountOptions, ResolveAccountResult } from './account-resolution.mjs';
 import type { MCPWebhookPayload, GetBrandIdentityRequest, GetBrandIdentityResponse, ContextMatchRequest, ContextMatchResponse, IdentityMatchRequest, IdentityMatchResponseRouterPublisher } from '../types/core.generated.mjs';
 import type { Task as A2ATask, TaskStatusUpdateEvent } from '@a2a-js/sdk';
 import { type CapabilityEvidenceScope, type CapabilityEvidenceSnapshot, type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient.mjs';
@@ -580,7 +580,15 @@ export declare class AgentClient {
      */
     listAccounts(params: ListAccountsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListAccountsResponse>>;
     /** Resolve the seller's account contract into a reusable wire account reference. */
-    resolveAccount(hints?: ResolveAccountOptions, options?: TaskOptions): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails: true;
+    }, options?: TaskOptions): Promise<ResolveAccountResult>;
+    resolveAccount(hints?: ResolveAccountOptions & {
+        includeDetails?: false;
+    }, options?: TaskOptions): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails?: boolean;
+    }, options?: TaskOptions): Promise<AccountReference | ResolveAccountResult>;
     /**
      * Sync accounts
      */

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

@@ -1,6 +1,6 @@
 import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
 import type { AccountReference, AgentConfig } from '../types';
-import type { ResolveAccountOptions } from './account-resolution';
+import type { ResolveAccountOptions, ResolveAccountResult } from './account-resolution';
 import type { MCPWebhookPayload, GetBrandIdentityRequest, GetBrandIdentityResponse, ContextMatchRequest, ContextMatchResponse, IdentityMatchRequest, IdentityMatchResponseRouterPublisher } from '../types/core.generated';
 import type { Task as A2ATask, TaskStatusUpdateEvent } from '@a2a-js/sdk';
 import { type CapabilityEvidenceScope, type CapabilityEvidenceSnapshot, type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient';
@@ -580,7 +580,15 @@ export declare class AgentClient {
      */
     listAccounts(params: ListAccountsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListAccountsResponse>>;
     /** Resolve the seller's account contract into a reusable wire account reference. */
-    resolveAccount(hints?: ResolveAccountOptions, options?: TaskOptions): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails: true;
+    }, options?: TaskOptions): Promise<ResolveAccountResult>;
+    resolveAccount(hints?: ResolveAccountOptions & {
+        includeDetails?: false;
+    }, options?: TaskOptions): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails?: boolean;
+    }, options?: TaskOptions): Promise<AccountReference | ResolveAccountResult>;
     /**
      * Sync accounts
      */

package/dist/lib/core/AgentClient.js

@@ -884,7 +884,6 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
-  /** Resolve the seller's account contract into a reusable wire account reference. */
   async resolveAccount(hints = {}, options) {
     return this.client.resolveAccount(
       hints,

package/dist/lib/core/AgentClient.mjs

@@ -852,7 +852,6 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
-  /** Resolve the seller's account contract into a reusable wire account reference. */
   async resolveAccount(hints = {}, options) {
     return this.client.resolveAccount(
       hints,

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

@@ -17,7 +17,7 @@ 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';
+import { type ResolveAccountOptions, type ResolveAccountResult } from './account-resolution.mjs';
 import { type BuyerPropertyPolicy, type ProductPropertyPolicyMode } from '../media-buy/property-policy.mjs';
 import { type ResolveListOptions } from '../server/targeting-helpers.mjs';
 import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type CreativeFormatWireMode, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery.mjs';
@@ -201,8 +201,10 @@ export interface StatusHandlerErrorContext {
  * Configuration for SingleAgentClient (and multi-agent client)
  */
 export interface SingleAgentClientConfig extends ConversationConfig {
-    /** Default off preserves existing wire requests; auto/strict use the provisioning registry. */
+    /** Default off disables provisioning gates; auto/strict use the provisioning registry. */
     accountPolicy?: AccountPolicy;
+    /** Auto selects seller IDs only with stable_account_id or an AdCP 4+ wire contract. Natural-key preserves legacy implicit references. */
+    accountReferenceMode?: 'auto' | 'natural-key';
     accountStorage?: BuyerAccountStorage;
     accountRegistryMaxEntries?: number;
     accountRegistryOptions?: Pick<import('./buyer-account-registry.mjs').BuyerAccountRegistryOptions, 'onDispatchStart' | 'onResult'>;
@@ -539,6 +541,8 @@ export declare class SingleAgentClient {
      */
     private accountRegistryOptedIn;
     private accountRegistryContext;
+    private usesStableAccountIds;
+    private accountWireReference;
     private applyAccountPolicy;
     private executor;
     private asyncHandler?;
@@ -602,11 +606,18 @@ export declare class SingleAgentClient {
      */
     private sellerDeclaredFormatOptions;
     /**
-     * The direct selector for an option this client derived from the seller's
-     * legacy `format_ids`. Without a product id, every remembered route for the
-     * option must agree that the seller did not declare it.
+     * What this client's own discovery recorded about an option's origin.
+     * Without a product id, every remembered route for the option must agree
+     * that the seller did not declare it.
      */
-    private undeclaredFormatOptionSelector;
+    private cachedFormatOptionOrigin;
+    /**
+     * The direct selector for an option the seller did not declare, from the
+     * first source that knows the option's origin: the per-call resolver, this
+     * client's discovery, then the configured resolver. Resolvers carry origin
+     * only when built from persisted routes.
+     */
+    private undeclaredSelectorFor;
     private projectUndeclaredFormatOptions;
     private rememberCanonicalProductRoutesForCompletion;
     private routeForOption;
@@ -1135,11 +1146,18 @@ export declare class SingleAgentClient {
     /**
      * Resolve an account for the authenticated caller. Explicit-account sellers
      * are discovered with list_accounts; implicit-account sellers are registered
-     * with sync_accounts and addressed by their natural key.
-     */
-    resolveAccount(hints?: ResolveAccountOptions, options?: TaskOptions, 
-    /** @internal Allows the AgentClient wrapper to retain nested task session ids. */
-    onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference>;
+     * with sync_accounts. Stable-ID sellers are addressed by ID; legacy implicit
+     * sellers keep their natural key. includeDetails also exposes the seller handle.
+     */
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails: true;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ResolveAccountResult>;
+    resolveAccount(hints?: ResolveAccountOptions & {
+        includeDetails?: false;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails?: boolean;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference | ResolveAccountResult>;
     /**
      * Sync accounts
      */

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

@@ -17,7 +17,7 @@ import type { AdcpCapabilities, FeatureName } from '../utils/capabilities';
 import { type AgentDiscoveryCacheConfig } from './agent-discovery-cache';
 import { BuyerAccountRegistry, type AccountPolicy, type BuyerAccountStorage } from './buyer-account-registry';
 import type { ProductCache } from './product-cache';
-import { type ResolveAccountOptions } from './account-resolution';
+import { type ResolveAccountOptions, type ResolveAccountResult } from './account-resolution';
 import { type BuyerPropertyPolicy, type ProductPropertyPolicyMode } from '../media-buy/property-policy';
 import { type ResolveListOptions } from '../server/targeting-helpers';
 import { type CanonicalCreateMediaBuyInput, type CanonicalCreativeResponse, type CanonicalGetProductsRequest, type CanonicalGetProductsResponse, type CanonicalListCreativesRequest, type CanonicalListCreativesResponse, type CanonicalPreviewCreativeRequest, type CanonicalPreviewCreativeResponse, type CanonicalSyncCreativesRequest, type CanonicalUpdateMediaBuyRequest, type CreativeFormatWireMode, type SyncCreativeFormatProjection } from '../v2/projection/creative-delivery';
@@ -201,8 +201,10 @@ export interface StatusHandlerErrorContext {
  * Configuration for SingleAgentClient (and multi-agent client)
  */
 export interface SingleAgentClientConfig extends ConversationConfig {
-    /** Default off preserves existing wire requests; auto/strict use the provisioning registry. */
+    /** Default off disables provisioning gates; auto/strict use the provisioning registry. */
     accountPolicy?: AccountPolicy;
+    /** Auto selects seller IDs only with stable_account_id or an AdCP 4+ wire contract. Natural-key preserves legacy implicit references. */
+    accountReferenceMode?: 'auto' | 'natural-key';
     accountStorage?: BuyerAccountStorage;
     accountRegistryMaxEntries?: number;
     accountRegistryOptions?: Pick<import('./buyer-account-registry').BuyerAccountRegistryOptions, 'onDispatchStart' | 'onResult'>;
@@ -539,6 +541,8 @@ export declare class SingleAgentClient {
      */
     private accountRegistryOptedIn;
     private accountRegistryContext;
+    private usesStableAccountIds;
+    private accountWireReference;
     private applyAccountPolicy;
     private executor;
     private asyncHandler?;
@@ -602,11 +606,18 @@ export declare class SingleAgentClient {
      */
     private sellerDeclaredFormatOptions;
     /**
-     * The direct selector for an option this client derived from the seller's
-     * legacy `format_ids`. Without a product id, every remembered route for the
-     * option must agree that the seller did not declare it.
+     * What this client's own discovery recorded about an option's origin.
+     * Without a product id, every remembered route for the option must agree
+     * that the seller did not declare it.
      */
-    private undeclaredFormatOptionSelector;
+    private cachedFormatOptionOrigin;
+    /**
+     * The direct selector for an option the seller did not declare, from the
+     * first source that knows the option's origin: the per-call resolver, this
+     * client's discovery, then the configured resolver. Resolvers carry origin
+     * only when built from persisted routes.
+     */
+    private undeclaredSelectorFor;
     private projectUndeclaredFormatOptions;
     private rememberCanonicalProductRoutesForCompletion;
     private routeForOption;
@@ -1135,11 +1146,18 @@ export declare class SingleAgentClient {
     /**
      * Resolve an account for the authenticated caller. Explicit-account sellers
      * are discovered with list_accounts; implicit-account sellers are registered
-     * with sync_accounts and addressed by their natural key.
-     */
-    resolveAccount(hints?: ResolveAccountOptions, options?: TaskOptions, 
-    /** @internal Allows the AgentClient wrapper to retain nested task session ids. */
-    onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference>;
+     * with sync_accounts. Stable-ID sellers are addressed by ID; legacy implicit
+     * sellers keep their natural key. includeDetails also exposes the seller handle.
+     */
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails: true;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ResolveAccountResult>;
+    resolveAccount(hints?: ResolveAccountOptions & {
+        includeDetails?: false;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference>;
+    resolveAccount(hints: ResolveAccountOptions & {
+        includeDetails?: boolean;
+    }, options?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<AccountReference | ResolveAccountResult>;
     /**
      * Sync accounts
      */