@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/specialisms/creative-template/index.yaml

@@ -0,0 +1,510 @@
+id: creative_template
+version: "1.0.0"
+title: "Creative template and transformation agent"
+protocol: creative
+category: creative_template
+summary: "Stateless creative agent that takes assets in, applies templates, and produces tags or rendered output."
+track: creative
+required_tools:
+  - build_creative
+
+# Cross-step assertion (adcp#2664). status.monotonic rejects resource
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph — e.g. approved → processing on a creative asset.
+#
+# Cross-resource assertion (adcp#2859). impairment.coherence verifies that
+# creative.rejected transitions propagate to any non-terminal media buy
+# that references the creative — the buy's impairments[] MUST list an
+# entry for the rejected creative, and `health` MUST track impairments[]
+# non-empty (impaired) ↔ empty (ok). See snapshot-and-log Rule 1 and
+# lifecycle.mdx Compliance for the full forward + inverse rule. Grades
+# not_applicable until #2860 wires the cross-resource exercise.
+invariants:
+  - status.monotonic
+  - impairment.coherence
+
+narrative: |
+  You build a creative management or rich media platform — think Celtra, a format
+  conversion service, or any tool that defines ad templates and transforms input assets
+  into finished creatives. Your agent is stateless: every call is self-contained. The
+  caller passes assets inline with each request, and you return the result. There is no
+  creative library to sync to and no persistent state between calls.
+
+  A buyer agent connects to discover your templates, preview them with real brand assets,
+  and request fully built creatives for trafficking. This storyboard walks through that
+  flow step by step.
+
+agent:
+  interaction_model: stateless_transform
+  capabilities:
+    - supports_transformation
+  examples:
+    - "Celtra"
+    - "Format conversion services"
+    - "Rich media template platforms"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity (brand.json with colors, fonts, logos) and creative
+    assets that match the format's requirements (images at the right dimensions, text at
+    the right lengths). The test kit provides these ingredients so you can test without
+    assembling them yourself.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports creative operations before browsing or building creatives.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring creative in supported_protocols, confirming the agent handles creative operations.
+        sample_request:
+          context:
+            correlation_id: "creative_template--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: format_exposure
+    title: "Format discovery"
+    narrative: |
+      The buyer's first question is: what can your platform do? They call
+      list_creative_formats to discover your templates — the available ad formats,
+      what assets each one requires, what dimensions they render at, and what
+      variables (dynamic fields) they support.
+
+      For a Celtra-like platform, this is where your publisher templates (Yahoo
+      Lighthouse, custom slider units) and standard templates (300x250 banners,
+      responsive display) get exposed as AdCP-compliant format definitions.
+
+    steps:
+      - id: discover_formats
+        title: "Discover available formats"
+        narrative: |
+          A buyer agent asks: "What creative formats do you support?" This is
+          the entry point for any interaction with your agent. The response tells
+          the buyer what templates are available, what assets each one needs, and
+          what the output dimensions will be.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_sync
+        stateful: false
+        expected: |
+          Return your supported formats. Each format must include:
+          - format_id with your agent_url and a unique id
+          - Human-readable name and description
+          - Asset slots with types, roles, and requirements (dimensions, file sizes, mime types)
+          - Render dimensions (width/height per render)
+          - Variables array if the format supports dynamic fields (text, colors, images)
+
+        sample_request:
+          context:
+            correlation_id: "creative_template--discover_formats"
+
+        validations:
+          - check: response_schema
+            description: "Response matches list-creative-formats-response.json schema"
+          - check: field_present
+            path: "formats"
+            description: "Response contains a formats array"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Each format has a format_id with agent_url"
+          - check: field_present
+            path: "formats[0].assets"
+            description: "Each format defines its asset requirements"
+          - check: field_present
+            path: "formats[0].renders"
+            description: "Each format defines its render dimensions"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--discover_formats"
+            description: "Context correlation_id returned unchanged"
+      - id: filter_by_type
+        title: "Filter formats by type"
+        narrative: |
+          The buyer narrows the search. Maybe they only want display formats, or
+          they need formats that accept image assets at specific dimensions. This
+          tests that your agent handles filter parameters correctly.
+        task: list_creative_formats
+        schema_ref: "creative/list-creative-formats-request.json"
+        response_schema_ref: "creative/list-creative-formats-response.json"
+        doc_ref: "/creative/task-reference/list_creative_formats"
+        comply_scenario: creative_sync
+        stateful: false
+        expected: |
+          Return only formats matching the filter criteria. If no formats match,
+          return an empty formats array — not an error.
+
+        sample_request:
+          type: "display"
+          max_width: 728
+          max_height: 90
+
+          context:
+            correlation_id: "creative_template--filter_by_type"
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--filter_by_type"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "formats[0].format_id.agent_url"
+            description: "Format IDs include agent_url"
+          - check: field_present
+            path: "formats[0].format_id.id"
+            description: "Format IDs include id — must match those in get_products"
+  - id: preview
+    title: "Preview with real assets"
+    narrative: |
+      The buyer wants to see what the template looks like with actual content.
+      They pass a complete creative manifest inline — brand identity, assets,
+      and format reference — and your agent renders a preview.
+
+      This is where the stateless nature matters: the buyer doesn't sync assets
+      to your library first. Everything needed is in the request.
+
+      To test this, you need compatible "ingredients" — a brand.json and assets
+      that match your format's requirements. The test kit provides these.
+
+    steps:
+      - id: preview_creative
+        title: "Preview a creative"
+        narrative: |
+          The buyer has chosen a format from Phase 1 and assembled a manifest with
+          brand assets. They call preview_creative with the full manifest inline to
+          see how the template renders with real content.
+
+          For a Celtra-like platform, this is where the template gets populated with
+          the advertiser's images, copy, and brand colors, and a preview URL or HTML
+          snippet is returned.
+        task: preview_creative
+        schema_ref: "creative/preview-creative-request.json"
+        response_schema_ref: "creative/preview-creative-response.json"
+        doc_ref: "/creative/task-reference/preview_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a preview render. The response should include:
+          - A preview URL (iframe-embeddable) and/or inline HTML
+          - Render dimensions matching the format spec
+          - An expiration timestamp (previews are ephemeral)
+
+          The preview should show the template populated with the provided assets —
+          not a placeholder or empty template.
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          request_type: "single"
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250"
+            assets:
+              image:
+                asset_type: "image"
+                url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-300x250.jpg"
+                width: 300
+                height: 250
+              click_url:
+                asset_type: "url"
+                url: "https://acmeoutdoor.example/summer-sale"
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+          output_format: "url"
+          quality: "draft"
+
+          context:
+            correlation_id: "creative_template--preview_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches preview-creative-response.json schema"
+          - check: field_present
+            path: "previews[0].renders[0].preview_url"
+            description: "Preview includes a renderable URL"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--preview_creative"
+            description: "Context correlation_id returned unchanged"
+  - id: build
+    title: "Full build (transformation)"
+    narrative: |
+      Now the buyer needs a finished creative — a serving tag or rendered output they
+      can traffic in a media buy. They call build_creative with the same inline manifest
+      and a target format. Your agent applies the template and returns the output.
+
+      This is where the three tag generation models come in:
+      - Universal tags: a single tag that adapts to any environment
+      - Single-placement tags: scoped to specific dimensions
+      - Multi-placement tags: covering multiple sizes in one tag
+
+      The output is a creative manifest with the serving code in an HTML, JavaScript,
+      or VAST asset — ready for the buyer to traffic.
+
+    steps:
+      - id: build_creative
+        title: "Build a creative from assets"
+        narrative: |
+          The buyer passes assets inline along with a target format and asks your agent
+          to produce a finished creative. This is the core transformation: raw assets in,
+          serving tag out.
+
+          For a Celtra-like platform, this means applying the template, assembling the
+          rich media unit, and returning an ad tag the buyer can traffic.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a creative manifest with the output creative. The response should include:
+          - A creative manifest with serving code (html, javascript, or vast asset)
+          - The format_id matching the target format
+          - Assets array with the generated output
+
+          The output should be a valid, traffickable creative — not a preview or placeholder.
+
+        sample_request:
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "display_300x250"
+            assets:
+              image:
+                asset_type: "image"
+                url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-300x250.jpg"
+                width: 300
+                height: 250
+              click_url:
+                asset_type: "url"
+                url: "https://acmeoutdoor.example/summer-sale"
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "display_300x250"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#creative_template_build_build_creative"
+          context:
+            correlation_id: "creative_template--build_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Output manifest includes assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Output manifest includes format_id"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--build_creative"
+            description: "Context correlation_id returned unchanged"
+      - id: build_multi_format
+        title: "Build for multiple formats"
+        narrative: |
+          The buyer needs the same creative adapted to several sizes — 300x250, 728x90,
+          and 320x50. Instead of making three separate calls, they pass target_format_ids
+          (plural) and your agent returns manifests for each.
+
+          This tests the multi-format generation capability that makes template agents
+          valuable — build once, get all sizes.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return creative manifests for each requested format. If a format cannot be
+          produced, include it in the response with an error — don't fail the entire
+          request.
+
+        sample_request:
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "source_master"
+            assets:
+              image:
+                asset_type: "image"
+                url: "https://test-assets.adcontextprotocol.org/acme-outdoor/hero-master.jpg"
+                width: 1200
+                height: 628
+              click_url:
+                asset_type: "url"
+                url: "https://acmeoutdoor.example/summer-sale"
+              headline:
+                asset_type: "text"
+                content: "Summer Sale — 40% Off All Gear"
+          target_format_ids:
+            - agent_url: "https://your-agent.example.com"
+              id: "display_300x250"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_728x90"
+            - agent_url: "https://your-agent.example.com"
+              id: "display_320x50"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#creative_template_build_build_multi_format"
+          context:
+            correlation_id: "creative_template--build_multi_format"
+        validations:
+          - check: response_schema
+            description: "Response matches schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--build_multi_format"
+            description: "Context correlation_id returned unchanged"
+  - id: audio_build
+    title: "Audio creative build (optional)"
+    # Optional phase: runner grades this not_applicable for agents that do not declare
+    # any audio format in list_creative_formats. To enable, set supports_audio_formats:
+    # true in the test kit (acme-outdoor.yaml) and ensure the agent returns at least one
+    # audio format from list_creative_formats before this phase runs.
+    optional: true
+    skip_if: "!test_kit.supports_audio_formats"
+    narrative: |
+      Audio-creative platforms — TTS services, voice generation agents, audio mix/master
+      pipelines — produce audio assets rather than display tags. They cannot pass the
+      existing build phase, which sends image inputs and expects HTML/VAST output.
+
+      This optional phase exercises build_creative with audio inputs (a script and a voice
+      descriptor) and validates that the output carries a servable audio asset.
+
+      The phase accepts both sync returns (small platforms render fast) and task-envelope
+      async returns (TTS pipelines may run for minutes). The comply_scenario: creative_flow
+      gate covers both paths.
+
+    steps:
+      - id: build_audio_creative
+        title: "Build an audio creative from assets"
+        narrative: |
+          The buyer passes audio inputs — a script and a voice descriptor — alongside a
+          target audio format and asks the agent to produce a finished audio creative.
+          The output must carry an audio asset with a resolvable URL.
+
+          Audio platforms that render synchronously may return the creative_manifest
+          immediately. TTS pipelines that take minutes may return a task envelope
+          (submitted → working → completed). Both are valid under comply_scenario:
+          creative_flow.
+        task: build_creative
+        schema_ref: "media-buy/build-creative-request.json"
+        response_schema_ref: "media-buy/build-creative-response.json"
+        doc_ref: "/creative/task-reference/build_creative"
+        comply_scenario: creative_flow
+        stateful: false
+        expected: |
+          Return a creative manifest with an audio output asset. The response should include:
+          - A creative manifest with an audio asset (asset_type: audio) and a resolvable URL
+          - The format_id matching the target audio format
+
+          Both sync (immediate creative_manifest) and task-envelope async returns are accepted.
+
+        sample_request:
+          creative_manifest:
+            format_id:
+              agent_url: "https://your-agent.example.com"
+              id: "audio_30s"
+            assets:
+              script:
+                asset_type: "text"
+                content: "Built for the trail. Acme Outdoor — premium gear for every adventure."
+              voice:
+                asset_type: "text"
+                content: "narrator-warm"
+              click_url:
+                asset_type: "url"
+                url: "https://acmeoutdoor.example/summer-sale"
+          target_format_id:
+            agent_url: "https://your-agent.example.com"
+            id: "audio_30s"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#creative_template_audio_build_build_audio_creative"
+          context:
+            correlation_id: "creative_template--build_audio_creative"
+        validations:
+          - check: response_schema
+            description: "Response matches build-creative-response.json schema"
+          - check: field_present
+            path: "creative_manifest.assets"
+            description: "Output manifest includes assets"
+          - check: field_present
+            path: "creative_manifest.format_id"
+            description: "Output manifest includes format_id"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "creative_template--build_audio_creative"
+            description: "Context correlation_id returned unchanged"

package/compliance/cache/3.1.0-rc.2/specialisms/governance-aware-seller/index.yaml

@@ -0,0 +1,143 @@
+id: governance_aware_seller
+version: "1.0.0"
+title: "Governance-aware seller"
+protocol: media-buy
+category: governance_aware_seller
+summary: "Seller agent that composes with a campaign-governance agent on the buyer side after baseline sync_governance registration — calls check_governance before confirming spend, and propagates governance approvals, conditions, and denials unchanged. Optional claim for the full governance-check loop."
+track: media_buy
+required_tools:
+  - sync_governance
+  - create_media_buy
+
+# Cross-step assertion (adcp#2639): governance-aware sellers are exactly
+# the surface this assertion protects. If a seller propagates a denial
+# response from its governance agent but then creates the media buy
+# anyway, no per-step validation notices — this assertion does.
+# Cross-step assertion (adcp#2664): status.monotonic rejects media_buy
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph — catches an approved-with-conditions buy jumping
+# from pending_creatives back to pending_start, or active → pending_creatives.
+invariants:
+  - governance.denial_blocks_mutation
+  - status.monotonic
+requires_scenarios:
+  - media_buy_seller/governance_approved
+  - media_buy_seller/governance_conditions
+  - media_buy_seller/governance_denied
+  - media_buy_seller/governance_denied_recovery
+  - governance_aware_seller/governance_multi_agent_rejected
+
+narrative: |
+  Baseline `sync_governance` registration is exercised by the money-moving
+  sales specialisms. This specialism covers the full governance composition
+  loop after registration: `check_governance` consultation before confirming
+  spend, plus `GOVERNANCE_DENIED` and governance-condition propagation.
+
+  Registration and consultation are deliberately separate layers. Baseline
+  sellers register exactly one buyer governance agent per account so the
+  account has an auditable governance endpoint on file before spend moves.
+  That registration is useful even when the seller does not actively consult
+  the agent on every mutation: it establishes the account binding, lets buyers
+  rotate governance endpoints through a single task, and gives graders one
+  place to enforce the `governance_agents.maxItems: 1` invariant. Sellers only
+  claim this specialism when they also promise to call `check_governance` and
+  propagate governance results during spend-committing flows.
+
+  Sellers that want to advertise "I honor the buyer's governance plan" claim
+  this specialism. The grading exercises the four scenarios that require the
+  governance handshake:
+  - `governance_approved` — seller accepts a buy that governance approved and
+    echoes the `governance_context` token back,
+  - `governance_conditions` — seller accepts a buy with conditions attached by
+    governance and propagates them through to the response,
+  - `governance_denied` — seller refuses a buy that governance denied and
+    returns `GOVERNANCE_DENIED` with the governance findings,
+  - `governance_denied_recovery` — seller accepts the corrected retry that
+    falls within the plan limits after the buyer reads the denial findings.
+
+  Sellers that do not claim this specialism are graded `not_applicable` on
+  the `check_governance` scenarios rather than failed. This mirrors the
+  pattern used by the other governance-* specialisms
+  (`governance-spend-authority`, `governance-delivery-monitor`) and by
+  `measurement-verification` — cross-cutting behaviors beyond registration
+  are gated behind explicit specialism claims instead of being force-included
+  under every sales-* specialism. (`signed-requests` was previously listed
+  here; it was reclassified in 3.1 to a universal capability-gated storyboard.)
+
+  Composition means the seller:
+  - uses the account's registered single governance agent (one agent per
+    account; internal specialist review composes inside the agent, not at
+    registration — see #3010 / #3015),
+  - calls `check_governance` on that registered agent before confirming a
+    spend-committing request,
+  - returns `GOVERNANCE_DENIED` with the governance findings propagated
+    unchanged when the check denies,
+  - echoes the `governance_context` token from approvals and surfaces
+    governance conditions to the buyer,
+  - does not silently downgrade the denial to a seller-scoped error
+    (`VALIDATION_ERROR` etc.) — the buyer needs to know the denial came from
+    its own governance agent to correct and retry.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher seller that integrates check_governance before confirming spend"
+    - "SSP that honors buyer-side governance plans before confirming bids"
+    - "Retail media network that refuses buys when the buyer's governance denies"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer) with a registered governance agent"
+
+prerequisites:
+  description: |
+    A governance agent that supports `sync_plans` and `check_governance`, and
+    a seller agent that supports `sync_governance` and propagates governance
+    approvals, conditions, and denials unchanged.
+
+    By default, the grading runner uses the training governance agent at
+    `test-agent.adcontextprotocol.org`. Override with `--governance-agent-url`
+    to use a custom governance agent that satisfies the campaign-governance
+    protocol.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports media buying before sending briefs or creating buys.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring media_buy in supported_protocols, confirming the agent sells media.
+        sample_request:
+          context:
+            correlation_id: "governance_aware_seller--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "governance_aware_seller--get_capabilities"
+            description: "Context correlation_id returned unchanged"