@adcp/sdk 12.1.1 → 13.0.0-rc.0

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

@@ -1,65 +1,55 @@
 import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
 import type { AgentConfig } from '../types/index.mjs';
-import type { MCPWebhookPayload } from '../types/core.generated.mjs';
+import type { MCPWebhookPayload, GetBrandIdentityRequest, GetBrandIdentityResponse, ContextMatchRequest, ContextMatchResponse, IdentityMatchRequest, IdentityMatchResponse } from '../types/core.generated.mjs';
 import type { Task as A2ATask, TaskStatusUpdateEvent } from '@a2a-js/sdk';
-import { type SingleAgentClientConfig, type VerifyAndParseWebhookOptions, type WebhookParseResult } from './SingleAgentClient.mjs';
+import { type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookParseResult } from './SingleAgentClient.mjs';
 import type { InputHandler, TaskOptions, TaskResult, TaskInfo, Message } from './ConversationTypes.mjs';
 import type { AdcpCapabilities } from '../utils/capabilities.mjs';
 import type { WebhookHeaderValue } from '../webhooks/index.mjs';
-import type { GetProductsRequest, GetProductsResponse, ListCreativeFormatsRequest, ListCreativeFormatsResponse, CreateMediaBuyRequest, CreateMediaBuyResponse, UpdateMediaBuyRequest, UpdateMediaBuyResponse, SyncCreativesRequest, SyncCreativesResponse, ListCreativesRequest, ListCreativesResponse, GetMediaBuysRequest, GetMediaBuysResponse, GetMediaBuyDeliveryRequest, GetMediaBuyDeliveryResponse, ProvidePerformanceFeedbackRequest, ProvidePerformanceFeedbackResponse, GetSignalsRequest, GetSignalsResponse, ActivateSignalRequest, ActivateSignalResponse, GetAdCPCapabilitiesRequest, GetAdCPCapabilitiesResponse, PreviewCreativeRequest, PreviewCreativeResponse, BuildCreativeRequest, BuildCreativeResponse, 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 } from '../types/tools.generated.mjs';
+import type { GetProductsRequest, GetProductsResponse, ListCreativeFormatsRequest, ListCreativeFormatsResponse, CreateMediaBuyRequest, CreateMediaBuyResponse, UpdateMediaBuyRequest, UpdateMediaBuyResponse, SyncCreativesRequest, SyncCreativesResponse, ListCreativesRequest, ListCreativesResponse, GetMediaBuysRequest, GetMediaBuysResponse, GetMediaBuyDeliveryRequest, GetMediaBuyDeliveryResponse, GetCreativeDeliveryRequest, GetCreativeDeliveryResponse, ProvidePerformanceFeedbackRequest, ProvidePerformanceFeedbackResponse, GetSignalsRequest, GetSignalsResponse, ActivateSignalRequest, ActivateSignalResponse, GetAdCPCapabilitiesRequest, GetAdCPCapabilitiesResponse, PreviewCreativeRequest, PreviewCreativeResponse, BuildCreativeRequest, BuildCreativeResponse, 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, CheckGovernanceRequest, CheckGovernanceResponse, ReportPlanOutcomeRequest, ReportPlanOutcomeResponse, GetPlanAuditLogsRequest, GetPlanAuditLogsResponse, ListTransformersRequest, ListTransformersResponse } from '../types/tools.generated.mjs';
 import type { MutatingRequestInput } from '../utils/idempotency.mjs';
-import type { V2AugmentedProduct } from '../v2/projection/augment-response.mjs';
-import type { ProjectionDiagnostic, V1Product } from '../v2/projection/types.mjs';
+import type { LegacyFormatConverter } from '../v2/projection/v1-to-v2.mjs';
+import type { ProjectionCatalogSnapshot } from '../v2/projection/catalog-snapshot.mjs';
+import type { CanonicalCreateMediaBuyRequest, CanonicalCreativeResponse, CanonicalGetProductsRequest, CanonicalGetProductsResponse, CanonicalListCreativesRequest, CanonicalListCreativesResponse, CanonicalSyncCreativesRequest, CanonicalUpdateMediaBuyRequest } from '../v2/projection/creative-delivery.mjs';
+export type { CanonicalGetProductsResponse } from '../v2/projection/creative-delivery.mjs';
+export type CanonicalProjectionTaskOptions = TaskOptions & {
+    /** Migration escape hatch for seller-specific legacy refs absent from the bundled registry. */
+    legacyFormatConverter?: LegacyFormatConverter;
+    /** Pre-resolved exact-owner publisher/community catalogs, highest precedence first. */
+    projectionCatalogs?: readonly ProjectionCatalogSnapshot[];
+};
 /**
- * AdCP 3.1 V2-mental-model envelope attached to `get_products` responses
- * when the SDK auto-projects `format_ids[]` → `format_options[]`.
+ * Projection metadata attached to canonical `get_products` responses.
  *
- * Present whenever projection ran (the default). Adopters reading the
- * V2 surface check `data.projection.diagnostics` to see what didn't
- * project cleanly; absence of diagnostics means every product's
+ * Present whenever projection ran (the default). Portable projection
+ * advisories are added to the standard `data.errors[]` array; this envelope
+ * is a convenience view for SDK-local inspection. Absence of diagnostics means every product's
  * `format_options[]` is fully populated (clean catalog match) or was
  * already v2-shaped on the wire.
  */
-export interface GetProductsProjectionEnvelope {
-    /**
-     * Structured diagnostics from the v1→v2 augmentation step
-     * (`source: 'sdk'`, parseable `sdk_id`, normative or SDK-local
-     * `code`). Empty when every product projects cleanly.
-     */
-    diagnostics: ProjectionDiagnostic[];
-}
 /**
- * `GetProductsResponse` with `format_options[]` guaranteed on every
- * product (the V2 mental model) and a `projection` envelope carrying
- * any diagnostics from the v1→v2 augmentation step.
- *
- * Returned by `AgentClient.getProducts()` by default. Callers passing
- * `{ project: false }` opt out of projection and receive the raw
- * generated `GetProductsResponse` instead.
+ * @deprecated The primary SDK surface is canonical-only. Use
+ * {@link CanonicalGetProductsResponse}. Raw legacy wire shapes remain
+ * available only through the explicit `getProductsLegacy()` escape hatch.
  */
-export type V2AugmentedGetProductsResponse = Omit<GetProductsResponse, 'products'> & {
-    products: V2AugmentedProduct<V1Product>[];
-    projection: GetProductsProjectionEnvelope;
-};
+export type V2AugmentedGetProductsResponse = CanonicalGetProductsResponse;
 /**
  * Type mapping for task names to their response types
  * Enables type-safe generic executeTask() calls
  */
 export type TaskResponseTypeMap = {
-    get_products: GetProductsResponse;
-    list_creative_formats: ListCreativeFormatsResponse;
-    create_media_buy: CreateMediaBuyResponse;
-    update_media_buy: UpdateMediaBuyResponse;
-    sync_creatives: SyncCreativesResponse;
-    list_creatives: ListCreativesResponse;
-    get_media_buys: GetMediaBuysResponse;
-    get_media_buy_delivery: GetMediaBuyDeliveryResponse;
+    get_products: CanonicalGetProductsResponse;
+    create_media_buy: CanonicalCreativeResponse<CreateMediaBuyResponse>;
+    update_media_buy: CanonicalCreativeResponse<UpdateMediaBuyResponse>;
+    sync_creatives: CanonicalCreativeResponse<SyncCreativesResponse>;
+    list_creatives: CanonicalListCreativesResponse;
+    get_media_buys: CanonicalCreativeResponse<GetMediaBuysResponse>;
+    get_media_buy_delivery: CanonicalCreativeResponse<GetMediaBuyDeliveryResponse>;
+    get_creative_delivery: CanonicalCreativeResponse<GetCreativeDeliveryResponse>;
     provide_performance_feedback: ProvidePerformanceFeedbackResponse;
     get_signals: GetSignalsResponse;
     activate_signal: ActivateSignalResponse;
     get_adcp_capabilities: GetAdCPCapabilitiesResponse;
-    preview_creative: PreviewCreativeResponse;
-    build_creative: BuildCreativeResponse;
     list_accounts: ListAccountsResponse;
     sync_accounts: SyncAccountsResponse;
     sync_audiences: SyncAudiencesResponse;
@@ -68,19 +58,57 @@ export type TaskResponseTypeMap = {
     update_property_list: UpdatePropertyListResponse;
     list_property_lists: ListPropertyListsResponse;
     delete_property_list: DeletePropertyListResponse;
-    list_content_standards: ListContentStandardsResponse;
-    get_content_standards: GetContentStandardsResponse;
-    calibrate_content: CalibrateContentResponse;
-    validate_content_delivery: ValidateContentDeliveryResponse;
     si_get_offering: SIGetOfferingResponse;
     si_initiate_session: SIInitiateSessionResponse;
     si_send_message: SISendMessageResponse;
     si_terminate_session: SITerminateSessionResponse;
+    get_brand_identity: GetBrandIdentityResponse;
+    sync_plans: SyncPlansResponse;
+    check_governance: CheckGovernanceResponse;
+    report_plan_outcome: ReportPlanOutcomeResponse;
+    get_plan_audit_logs: GetPlanAuditLogsResponse;
+    context_match: ContextMatchResponse;
+    identity_match: IdentityMatchResponse;
 };
 /**
  * Valid ADCP task names
  */
 export type AdcpTaskName = keyof TaskResponseTypeMap;
+/** Exact request mapping paired with {@link TaskResponseTypeMap}. */
+export type TaskRequestTypeMap = {
+    get_products: CanonicalGetProductsRequest;
+    create_media_buy: MutatingRequestInput<CanonicalCreateMediaBuyRequest>;
+    update_media_buy: MutatingRequestInput<CanonicalUpdateMediaBuyRequest>;
+    sync_creatives: MutatingRequestInput<CanonicalSyncCreativesRequest>;
+    list_creatives: CanonicalListCreativesRequest;
+    get_media_buys: GetMediaBuysRequest;
+    get_media_buy_delivery: GetMediaBuyDeliveryRequest;
+    get_creative_delivery: GetCreativeDeliveryRequest;
+    provide_performance_feedback: MutatingRequestInput<ProvidePerformanceFeedbackRequest>;
+    get_signals: GetSignalsRequest;
+    activate_signal: MutatingRequestInput<ActivateSignalRequest>;
+    get_adcp_capabilities: GetAdCPCapabilitiesRequest;
+    list_accounts: ListAccountsRequest;
+    sync_accounts: MutatingRequestInput<SyncAccountsRequest>;
+    sync_audiences: MutatingRequestInput<SyncAudiencesRequest>;
+    create_property_list: MutatingRequestInput<CreatePropertyListRequest>;
+    get_property_list: GetPropertyListRequest;
+    update_property_list: MutatingRequestInput<UpdatePropertyListRequest>;
+    list_property_lists: ListPropertyListsRequest;
+    delete_property_list: MutatingRequestInput<DeletePropertyListRequest>;
+    si_get_offering: SIGetOfferingRequest;
+    si_initiate_session: MutatingRequestInput<SIInitiateSessionRequest>;
+    si_send_message: MutatingRequestInput<SISendMessageRequest>;
+    si_terminate_session: SITerminateSessionRequest;
+    get_brand_identity: GetBrandIdentityRequest;
+    sync_plans: MutatingRequestInput<SyncPlansRequest>;
+    check_governance: CheckGovernanceRequest;
+    report_plan_outcome: MutatingRequestInput<ReportPlanOutcomeRequest>;
+    get_plan_audit_logs: GetPlanAuditLogsRequest;
+    context_match: ContextMatchRequest;
+    identity_match: IdentityMatchRequest;
+};
+export type TaskRequestFor<K extends AdcpTaskName> = TaskRequestTypeMap[K];
 /**
  * Configuration for `AgentClient.fromMCPClient()`.
  *
@@ -94,7 +122,7 @@ export type AdcpTaskName = keyof TaskResponseTypeMap;
  * - `governance` — buyer-side governance config
  * - `requireV3ForMutations` — enforce AdCP v3 before dispatching mutating tools
  */
-export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'validateFeatures' | 'requireV3ForMutations' | 'allowV2' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations'> & {
+export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVersion' | 'versionEnvelope' | 'debug' | 'validation' | 'governance' | 'onActivity' | 'legacyFormatConverter' | 'projectionCatalogs' | 'canonicalFormatLegacyResolver' | 'validateFeatures' | 'requireV3ForMutations' | 'allowV2' | 'workingTimeout' | 'defaultMaxClarifications' | 'persistConversations'> & {
     /**
      * Human-readable name for this agent, used in debug logs and
      * `getAgentName()`. Defaults to `'in-process'`.
@@ -228,91 +256,62 @@ export declare class AgentClient {
     /**
      * Discover available advertising products.
      *
-     * By default, response products are augmented with the AdCP 3.1
-     * `format_options[]` declaration (the V2 mental model). When the
-     * seller emitted v1 `format_ids[]`, the SDK projects them via the
-     * AAO canonical-formats catalog so buyers always read the same
-     * V2 shape regardless of wire version. The original `format_ids[]`
-     * is preserved alongside `format_options[]` (additive — 7.x
-     * callers reading `format_ids` keep working).
+     * Response products expose only canonical `format_options[]`, regardless of
+     * the seller's negotiated wire version. The SDK performs any required legacy
+     * translation below this public boundary.
      *
-     * Projection diagnostics surface on
-     * `result.data.projection.diagnostics` (structured
+     * Projection failures surface portably on `result.data.errors[]` and are
+     * also mirrored on `result.data.projection.diagnostics` (structured
      * `source: 'sdk'` markers; codes mirror the spec's error-code
      * vocabulary plus three SDK-local codes — see the projection
      * module's `ProjectionDiagnostic` type for the full set).
      *
-     * Pass `{ project: false }` to opt out and receive the raw wire
-     * response unmodified — useful for storyboard / compliance
-     * harnesses asserting exact seller emission. The opt-out narrows
-     * the return type back to `GetProductsResponse` (no `projection`
-     * envelope, no guaranteed `format_options[]`).
-     *
-     * The 8.0 release narrows further by removing `format_ids[]` from
-     * the public Product type entirely.
-     */
-    getProducts(params: GetProductsRequest, inputHandler?: InputHandler, options?: TaskOptions & {
-        project?: true;
-    }): Promise<TaskResult<V2AugmentedGetProductsResponse>>;
-    getProducts(params: GetProductsRequest, inputHandler?: InputHandler, options?: TaskOptions & {
-        project: false;
-    }): Promise<TaskResult<GetProductsResponse>>;
-    /**
-     * List available creative formats
+     * Protocol tooling that must inspect raw seller emission uses the explicit
+     * deprecated `getProductsLegacy()` method.
      */
-    listCreativeFormats(params: ListCreativeFormatsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListCreativeFormatsResponse>>;
+    getProducts(params: CanonicalGetProductsRequest, inputHandler?: InputHandler, options?: CanonicalProjectionTaskOptions): Promise<TaskResult<CanonicalGetProductsResponse>>;
+    /** @deprecated Explicit raw-wire escape hatch for migration tooling. */
+    getProductsLegacy(params: GetProductsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<GetProductsResponse>>;
+    /** @deprecated Migration-only access to a legacy named-format catalog. */
+    listCreativeFormatsLegacy(params: ListCreativeFormatsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListCreativeFormatsResponse>>;
+    /** @deprecated Migration-only access to legacy creative transformer declarations. */
+    listTransformersLegacy(params: ListTransformersRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListTransformersResponse>>;
     /**
      * Create a new media buy.
      *
-     * **3.1+ format-option write flow (preferred at 3.1.0-beta.5+).** After
-     * `getProducts()` returns the V2-augmented response (`format_options[]`
-     * auto-populated), pick declarations by `format_option_id` and use
-     * `packageRefsForFormatOptions` to author the package. The helper emits
-     * BOTH `format_option_refs[]` (the 3.1+ path) AND `format_ids[]`
-     * (legacy named-format dual emission) so a single request works against
-     * both format-option-aware and legacy sellers.
+     * Discover canonical `format_options[]` with `getProducts()`, select a
+     * `format_option_id`, and send only canonical package and creative fields.
+     * Compatibility translation for an older seller happens below this method.
      *
      * ```ts
-     * import { packageRefsForFormatOptions } from '@adcp/sdk/v2/projection';
-     *
      * const { data: { products } } = await agent.getProducts({ brief: '...' });
      * const product = products[0];
+     * const format = product.format_options[0];
      *
      * await agent.createMediaBuy({
      *   packages: [{
      *     package_id: 'pkg-1',
      *     product_id: product.product_id,
      *     pricing_option_id: product.pricing_options[0].pricing_option_id,
-     *     ...packageRefsForFormatOptions(product, ['nytimes_mrec', 'nytimes_video_30s']),
-     *     // ↑ spreads `{ format_option_refs, format_ids? }`
+     *     format_option_refs: [{
+     *       scope: 'product',
+     *       format_option_id: format.format_option_id
+     *     }],
+     *     creatives: [{
+     *       creative_id: 'hero',
+     *       format_kind: format.format_kind,
+     *       format_option_ref: {
+     *         scope: 'product',
+     *         format_option_id: format.format_option_id
+     *       },
+     *       assets: { image: { url: 'https://cdn.example/hero.png' } }
+     *     }],
      *     budget: { currency: 'USD', total: 5000 },
      *   }],
      *   // ...
      * });
      * ```
      *
-     * The resulting wire payload for the package looks like:
-     *
-     * ```json
-     * {
-     *   "package_id": "pkg-1",
-     *   "product_id": "...",
-     *   "pricing_option_id": "...",
-     *   "format_option_refs": [
-     *     {"scope": "product", "format_option_id": "nytimes_mrec"},
-     *     {"scope": "product", "format_option_id": "nytimes_video_30s"}
-     *   ],
-     *   "format_ids": [
-     *     {"agent_url": "https://creative.adcontextprotocol.org/", "id": "display_300x250_image"},
-     *     {"agent_url": "https://creative.adcontextprotocol.org/", "id": "video_standard_30s"}
-     *   ],
-     *   "budget": {"currency": "USD", "total": 5000}
-     * }
-     * ```
-     *
-     * `format_ids` is omitted entirely when every chosen format option is V2-only
-     * (the spec's "neither present" fallback fires for v1 sellers in that case).
-     *
      * **Inline creative fallback.** Sellers that do not advertise a creative
      * library (`supportsSyncCreatives(await agent.getCapabilities()) === false`)
      * can still accept package-scoped creative uploads when they advertise
@@ -323,19 +322,12 @@ export declare class AgentClient {
      * assignments for create payloads, give each package a stable key such as
      * `context.buyer_ref`, or pass a custom `packageId` resolver.
      *
-     * For adopters writing strictly to v1 sellers — or for products whose
-     * `format_options[]` entries don't publish `format_option_id` — see the
-     * `legacyFormatIdsFromOptions` / `tryLegacyFormatIdsFromOptions` /
-     * `legacyFormatIdsForFormatOption` helpers in `@adcp/sdk/v2/projection`.
-     *
-     * `packageRefsForFormatOptions` throws `FormatOptionRefsLookupError`
-     * with a normalized `.code` in `{ 'unknown_format_option_id' |
-     * 'format_option_refs_not_published' | 'empty_input' | 'invalid_product' }`
-     * — branch on `.code` to fall back to the `legacy*` helpers when the
-     * product is V1-shape only. See the helper JSDoc for the full
-     * recovery example.
+     * Existing applications that still hold old named-format payloads must opt
+     * into `createMediaBuyLegacy()` explicitly.
      */
-    createMediaBuy(params: MutatingRequestInput<CreateMediaBuyRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<CreateMediaBuyResponse>>;
+    createMediaBuy(params: MutatingRequestInput<CanonicalCreateMediaBuyRequest>, inputHandler?: InputHandler, options?: CreativeDeliveryTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<CreateMediaBuyResponse>>>;
+    /** @deprecated Use `createMediaBuy`; this explicit compatibility surface accepts legacy creative `format_id`. */
+    createMediaBuyLegacy(params: MutatingRequestInput<CreateMediaBuyRequest>, inputHandler?: InputHandler, options?: CreativeDeliveryTaskOptions): Promise<TaskResult<CreateMediaBuyResponse>>;
     /**
      * Update an existing media buy.
      *
@@ -345,8 +337,12 @@ export declare class AgentClient {
      * request. Build the package patch with `inlineCreativesForPackages()` and
      * preflight it with `preflightUpdateMediaBuy(currentBuy, patch)` so
      * `available_actions[]` allows `replace_creative` before dispatch.
+     * Use `format_kind` and `format_option_ref` for every creative in the patch;
+     * the SDK handles any negotiated compatibility conversion.
      */
-    updateMediaBuy(params: MutatingRequestInput<UpdateMediaBuyRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<UpdateMediaBuyResponse>>;
+    updateMediaBuy(params: MutatingRequestInput<CanonicalUpdateMediaBuyRequest>, inputHandler?: InputHandler, options?: CreativeDeliveryTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<UpdateMediaBuyResponse>>>;
+    /** @deprecated Use `updateMediaBuy`; this explicit compatibility surface accepts legacy creative `format_id`. */
+    updateMediaBuyLegacy(params: MutatingRequestInput<UpdateMediaBuyRequest>, inputHandler?: InputHandler, options?: CreativeDeliveryTaskOptions): Promise<TaskResult<UpdateMediaBuyResponse>>;
     /**
      * Sync creative assets into the seller's reusable creative library.
      *
@@ -359,20 +355,35 @@ export declare class AgentClient {
      * send a separate `create_media_buy` or `update_media_buy` request with its
      * own idempotency key. If neither capability is advertised, creative upload
      * is not available through this SDK helper surface.
+     *
+     * A sync request does not carry product declarations. When compatibility
+     * translation needs seller selection metadata, pass
+     * `options.creativeFormatProjection.selectorContainers` with the routed
+     * package/product selectors. Assignments scope each creative to its package.
      */
-    syncCreatives(params: MutatingRequestInput<SyncCreativesRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<SyncCreativesResponse>>;
+    syncCreatives(params: MutatingRequestInput<CanonicalSyncCreativesRequest>, inputHandler?: InputHandler, options?: SyncCreativesTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<SyncCreativesResponse>>>;
+    /** @deprecated Use `syncCreatives`; this explicit compatibility surface accepts legacy creative `format_id`. */
+    syncCreativesLegacy(params: MutatingRequestInput<SyncCreativesRequest>, inputHandler?: InputHandler, options?: SyncCreativesTaskOptions): Promise<TaskResult<SyncCreativesResponse>>;
     /**
      * List creative assets
      */
-    listCreatives(params: ListCreativesRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListCreativesResponse>>;
+    listCreatives(params: CanonicalListCreativesRequest, inputHandler?: InputHandler, options?: CanonicalProjectionTaskOptions): Promise<TaskResult<CanonicalListCreativesResponse>>;
+    /**
+     * Return the unprojected `list_creatives` wire response.
+     *
+     * @deprecated Compatibility-only escape hatch for migration and protocol tooling.
+     */
+    listCreativesLegacy(params: ListCreativesRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListCreativesResponse>>;
     /**
      * Get media buy status, creative approvals, and optional delivery snapshots
      */
-    getMediaBuys(params: GetMediaBuysRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<GetMediaBuysResponse>>;
+    getMediaBuys(params: GetMediaBuysRequest, inputHandler?: InputHandler, options?: CanonicalReadTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<GetMediaBuysResponse>>>;
     /**
      * Get media buy delivery information
      */
-    getMediaBuyDelivery(params: GetMediaBuyDeliveryRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<GetMediaBuyDeliveryResponse>>;
+    getMediaBuyDelivery(params: GetMediaBuyDeliveryRequest, inputHandler?: InputHandler, options?: CanonicalReadTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<GetMediaBuyDeliveryResponse>>>;
+    /** Retrieve canonical creative-level and variant-level delivery metrics. */
+    getCreativeDelivery(params: GetCreativeDeliveryRequest, inputHandler?: InputHandler, options?: CanonicalProjectionTaskOptions): Promise<TaskResult<CanonicalCreativeResponse<GetCreativeDeliveryResponse>>>;
     /**
      * Provide performance feedback
      */
@@ -414,14 +425,10 @@ export declare class AgentClient {
      * @deprecated Use `requireSupportedMajor()` instead.
      */
     requireV3(taskType?: string): Promise<void>;
-    /**
-     * Preview a creative
-     */
-    previewCreative(params: PreviewCreativeRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<PreviewCreativeResponse>>;
-    /**
-     * Build a creative from format and brand context
-     */
-    buildCreative(params: MutatingRequestInput<BuildCreativeRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<BuildCreativeResponse>>;
+    /** @deprecated Migration-only access to legacy `format_id`-based creative preview. */
+    previewCreativeLegacy(params: PreviewCreativeRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<PreviewCreativeResponse>>;
+    /** @deprecated Migration-only access to legacy `target_format_id`-based creative building. */
+    buildCreativeLegacy(params: MutatingRequestInput<BuildCreativeRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<BuildCreativeResponse>>;
     /**
      * List accounts
      */
@@ -457,19 +464,19 @@ export declare class AgentClient {
     /**
      * List content standards
      */
-    listContentStandards(params: ListContentStandardsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListContentStandardsResponse>>;
+    listContentStandardsLegacy(params: ListContentStandardsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ListContentStandardsResponse>>;
     /**
      * Get content standards
      */
-    getContentStandards(params: GetContentStandardsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<GetContentStandardsResponse>>;
+    getContentStandardsLegacy(params: GetContentStandardsRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<GetContentStandardsResponse>>;
     /**
      * Calibrate content against standards
      */
-    calibrateContent(params: MutatingRequestInput<CalibrateContentRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<CalibrateContentResponse>>;
+    calibrateContentLegacy(params: MutatingRequestInput<CalibrateContentRequest>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<CalibrateContentResponse>>;
     /**
      * Validate content delivery
      */
-    validateContentDelivery(params: ValidateContentDeliveryRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ValidateContentDeliveryResponse>>;
+    validateContentDeliveryLegacy(params: ValidateContentDeliveryRequest, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<ValidateContentDeliveryResponse>>;
     /**
      * Get an SI offering
      */
@@ -618,17 +625,20 @@ export declare class AgentClient {
      * ```typescript
      * // ✅ TYPE-SAFE: Automatic response type inference
      * const result = await agent.executeTask('get_products', params);
-     * // result is TaskResult<GetProductsResponse> - no casting needed!
+     * // result is TaskResult<CanonicalGetProductsResponse> - no casting needed!
      *
      * // ✅ CUSTOM TYPES: For non-standard tasks
-     * const customResult = await agent.executeTask<MyCustomResponse>('custom_task', params);
+     * const customResult = await agent.executeCustomTask<MyCustomResponse>('custom_task', params);
      * ```
      */
-    executeTask<K extends AdcpTaskName>(taskName: K, params: Record<string, unknown>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<TaskResponseTypeMap[K]>>;
+    executeTask<K extends AdcpTaskName>(taskName: K, params: TaskRequestFor<K>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<TaskResponseTypeMap[K]>>;
+    /** Execute an extension task that is not part of the standard AdCP task set. */
+    executeCustomTask<T = unknown>(taskName: string, params: Record<string, unknown>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<T>>;
     /**
-     * Execute a task by name with custom response type
+     * Explicit raw-task compatibility escape hatch for conformance and migration tooling.
+     * @deprecated Application code should use typed primary methods or `executeTask()`.
      */
-    executeTask<T = unknown>(taskName: string, params: Record<string, unknown>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<T>>;
+    executeTaskLegacy<T = unknown>(taskName: string, params: Record<string, unknown>, inputHandler?: InputHandler, options?: TaskOptions): Promise<TaskResult<T>>;
     /**
      * List all tasks for this agent
      */