@adcp/sdk 6.6.0 → 6.8.0

package/skills/build-signals-agent/SKILL.md

@@ -9,6 +9,8 @@ description: Use when building an AdCP signals agent, creating an audience data
 
 A signals agent serves audience segments to buyers for campaign targeting. Two tools: `get_signals` (discovery) and `activate_signal` (push to DSPs or sales agents). The business model — marketplace vs owned data — shapes every implementation decision. Determine that first.
 
+> **Common shape gotchas:** `signal_ids[]` in `get_signals` is `signal_id[]` (provenance objects with `source`/`data_provider_domain`/`id`), not bare strings. `activate_signal` returns deployments with `ActivationKey` `oneOf` — for `type: 'key_value'` the `key` and `value` fields sit at the TOP level of `activation_key`, NOT nested under a `key_value` sub-field. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for the patterns adopters consistently get wrong on first pass.
+
 ## When to Use
 
 - User wants to build an agent that serves audience/targeting data
@@ -21,6 +23,8 @@ A signals agent serves audience segments to buyers for campaign targeting. Two t
 - Rendering creatives from briefs → that's a creative agent
 - Building a client that _calls_ a signals agent → see `docs/getting-started.md`
 
+**Often claimed alongside:** [`sales-social`](../build-seller-agent/SKILL.md) (walled-garden audience push), [`sales-non-guaranteed`](../build-seller-agent/SKILL.md) (DSP data marketplace as a side surface), [`audience-sync`](../build-seller-agent/SKILL.md) (identity-provider owned-graph activation). See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).
+
 ## Specialisms This Skill Covers
 
 | Specialism           | Status | Delta                                                                                                                                                               | See                                                    |

package/skills/call-adcp-agent/SKILL.md

@@ -118,8 +118,12 @@ Every validation failure produces:
 - `issues[].pointer` — RFC 6901 JSON Pointer to the field.
 - `issues[].keyword` — AJV keyword (`required`, `type`, `oneOf`, `anyOf`, `additionalProperties`, `format`, `enum`).
 - `issues[].variants` — when the keyword is `oneOf` or `anyOf`, each entry lists one variant's `required` + declared `properties`. **Pick ONE variant**, send only its `required` fields. This is the fastest recovery path when you didn't know the field was a union.
+- `issues[].discriminator` — when an SDK ≥6.7 picks a "best surviving variant" of a const-discriminated union, this is the `[{field, value}, …]` pairs that variant requires. Reads as the validator's verdict on which branch you were inferred to be targeting. Example: `discriminator: [{field: 'type', value: 'key_value'}]` plus `pointer: '/deployments/0/activation_key/key'` and `keyword: 'required'` means "you picked the `key_value` activation_key variant and it requires top-level `key` and `value`." Compound discriminators like `audience-selector`'s `(type, value_type)` produce two-entry arrays.
+- `issues[].schemaId` — `$id` of the rejecting schema. For tools served from the bundled tree this is usually the response root; for flat-tree tools it can land on the deeper sub-schema. Diagnostic only; the actionable lever is `discriminator` + `variants` + `pointer`.
+- `issues[].allowedValues` — closed enum lists for `keyword: 'enum'` issues. Picking from this list closes the case in one round.
+- `issues[].hint` — SDK ≥6.8 only. One-sentence curated recipe for known shape gotchas: discriminator nesting (`activation_key`, VAST `delivery_type`), shape mismatches (`format_id` object, `budget` number, `signal_ids` provenance objects), and discriminator merging (`account`). When present, the hint is the most-direct fix path; read it before walking variants. Absent on the long tail — no hint just means there's no curated rule for the pattern.
 
-Patch the pointers, don't re-guess what the skill or the `variants` already told you, resend. Three attempts should cover every field.
+**Recovery order**: read `hint` first (when present, it's the validated fix path); then `discriminator` (names which branch to fix); then `variants` (lists every option if you're not in a branch); then `pointer` + `keyword` + `message` for the leaf fix. Patch and resend. Three attempts should cover every field.
 
 ## Minimal working examples
 
@@ -225,6 +229,8 @@ Quick lookup before reading the full envelope. Match what you see in `adcp_error
 | Symptom | What it means | Fix |
 |---|---|---|
 | `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
+| `discriminator: [{field, value}]` on a `required` issue | Validator inferred which branch you targeted; you missed required fields IN that branch | Read the `discriminator` pair, fill the missing required fields at the same level (don't nest under the discriminator field name). |
+| `hint:` field present on the issue | SDK matched a curated shape-gotcha rule | Apply the hint directly — it's the validated fix path. |
 | 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants ({account_id, brand, operator, …}) | Drop to one variant. Don't keep "extra" fields "for completeness". |
 | `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse it on retries. |
 | `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |

package/skills/run-by-experts/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: run-by-experts
+description: Use before opening a SUBSTANTIVE PR (protocol changes, multi-tenant or auth surfaces, adopter-facing examples, refactors that span specialism modules). Fires multiple expert reviewers in parallel and uses convergence as the blocker signal — items flagged by 2+ reviewers are real; single-reviewer findings are usually preferences. Skip for trivial changes (single-line fixes, README typos, mechanical refactors).
+---
+
+# Run by Experts
+
+## Overview
+
+Multi-reviewer parallel review where **convergence is the load-bearing signal**. Items flagged by two or more reviewers are real blockers. Single-reviewer findings are usually preferences worth considering but not gating.
+
+This skill exists because solo Claude review on a non-trivial PR catches obvious bugs but misses domain-specific landmines (multi-tenant isolation, protocol shape, type-system gotchas, adopter-DX cliffs). Each expert reviewer carries different domain priors; running them in parallel and acting on the intersection produces a better signal than any single review.
+
+## When to use
+
+**Always run before opening:**
+
+- Protocol-level changes (request/response shapes, error codes, new specialism interfaces)
+- Multi-tenant or auth surfaces (isolation gates, credential handling, sandbox boundaries)
+- Adopter-facing examples (`examples/hello_*`, skill files, public docs)
+- Bug fixes where the root cause might be either side of an interface boundary
+
+**Optional but high-value:**
+
+- Refactors that span multiple specialism modules
+- API surface changes (export shape, type changes, deprecations)
+- New subagent prompts or skill files
+
+**Skip:**
+
+- Trivial changes (changesets, single-line bug fixes with obvious test coverage, README typos)
+- Pure mechanical refactors (rename, dead-code removal) where you've verified no behavior change
+
+## The reviewer set
+
+Pick the relevant subset for the PR. Default for a substantive change is all four:
+
+| Reviewer                  | Focus                                                                                                       | Fire when                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `ad-tech-protocol-expert` | Wire shape vs spec, error code placement, schema conformance, protocol contract                             | Any protocol-touching change                                                                        |
+| `code-reviewer`           | Correctness, type-safety, dead code, casts, edge cases, hidden control flow                                 | All non-trivial code changes                                                                        |
+| `security-reviewer`       | Tenant isolation, auth/credential handling, prompt-injection surfaces, fail-open vs fail-closed gates, SSRF | Any change that touches auth, multi-tenancy, or buyer-supplied data flowing through error envelopes |
+| `dx-expert`               | Forkability, SWAP markers, header doc clarity, copy-paste anti-patterns, README discoverability             | Any adopter-facing example or doc change                                                            |
+
+For protocol-only / spec-side changes, `adtech-product-expert` (buy-side / sell-side product fit) is often a fifth.
+
+## How to fire
+
+Single message, multiple `Agent` tool calls in parallel — never sequential. Run-in-background unless the PR is so small that you'll wait on the first one. Each prompt is **self-contained**: the agent has no memory of the conversation, so include:
+
+- File paths in scope
+- Branch name
+- Specific items the prior round (if any) claimed to fix — verify each
+- Specific concerns you want flagged (don't ask "what do you think?" — that produces shallow review)
+- Word budget ("Under 500 words")
+- Format expectation ("Report: blockers / concerns / fine, per item")
+
+Example brief shape (excerpted from `bokelley/hello-adapters-gov-rights` round 2):
+
+> Re-review of PR #XXXX. Prior round flagged 17 findings; all blockers + must-fix concerns claimed addressed. Verify, and flag any NEW issues introduced by the fixes.
+>
+> Files in scope: `examples/foo.ts` (new, ~1200 lines).
+>
+> Prior-round items that should be fixed — verify each:
+>
+> 1. ...
+> 2. ...
+>
+> New questions for this round:
+>
+> 1. ...
+>
+> Report: blockers / suggestions / nits. Under 500 words. Don't restate prior-round findings unless the fix introduces a new issue.
+
+## Reading the results
+
+**Convergence (2+ reviewers same finding) = real blocker.** Act on these unconditionally.
+
+**Single-reviewer must-fix = should-fix.** Read the reasoning; usually it's worth doing but defensibly skippable. Push back if the finding contradicts the convergent signals.
+
+**Advisory = nice-to-have.** Roll into a follow-up issue or comment-only fix.
+
+The convergence signal is doing real work. From the production example (round 1 of the multi-tenant adapter PR):
+
+- The `as unknown as { account?: ... }` cast was flagged by THREE of four reviewers (code: "may be reading a runtime-undefined field"; DX: "cargo-cult-bait"; protocol: implicitly endorsed by saying "should pull from `ctx.account`"). All three independently spotted that the cast was a real bug, not a style preference.
+- Single-reviewer concerns were mostly preferences (helper extraction style, comment placement nits). Worth doing but not gating.
+
+## Two-round pattern
+
+For substantive PRs, run **two rounds**:
+
+1. **Round 1 — initial review.** Fire all relevant reviewers on the unreviewed code. Consolidate findings by convergence. Apply blockers + must-fix.
+2. **Round 2 — re-review of fixes.** Fire the same reviewers again, asking each to (a) verify each prior-round finding is fixed and (b) flag any NEW issues the fix introduced.
+
+Round-2 finds the regressions fix-blindness misses. Production example: round 2 caught a fail-OPEN tenant gate that round 1's fix had introduced (the gate was `if (homeTenantId && tenantId !== homeTenantId)` — when `homeTenantId` is undefined, the check skips; round 1 hadn't considered that path).
+
+## Process artifacts to ship with the PR
+
+After all rounds land, the PR description should include:
+
+- A consolidated "Expert review" section listing each round's blockers and how each was addressed
+- The reviewer convergence signal (e.g., "3 of 4 flagged X" → "this was the real bug")
+- Any single-reviewer items that were intentionally NOT fixed, with reasoning
+- Cross-links to upstream-spec issues filed during review (if storyboards or spec gaps surfaced — see `skills/triage-storyboard-failure/`)
+
+## What this skill is NOT
+
+- A replacement for human reviewers — convergent expert review surfaces issues fast, but humans make the final call on whether to merge
+- An excuse to skip writing tests — reviewers can't verify behavior they can't run
+- A substitute for `npm run typecheck` / `npm run format:check` / CI — those gate-before-review
+
+## See also
+
+- `skills/triage-storyboard-failure/` — when an expert review (or your own testing) surfaces a storyboard-vs-spec mismatch
+- `examples/CONTRIBUTING.md` — the SWAP-marker and DO-NOT-DEPLOY-AS-IS conventions DX reviewers will check for
+- `~/.claude/commands/prep-for-pr.md` (personal command) — calls this skill plus the build/test/security-review chain

package/skills/triage-storyboard-failure/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: triage-storyboard-failure
+description: Use when an AdCP compliance storyboard fails on an adapter you believe is spec-correct. Walks the rubric for deciding whether to fix the SDK, the adapter, or file upstream against the spec/storyboard.
+---
+
+# Triage a Storyboard Failure
+
+## Overview
+
+Storyboards in `compliance/cache/<version>/` are assertions about adopter behavior. They are **not** the spec — they are tests authored against the spec. Storyboards drift. When one fails, the question is _which side is wrong_: the adapter, the SDK, or the storyboard itself.
+
+This skill is the rubric for that decision. It exists because adopter-facing failures look identical regardless of cause, and the wrong-direction fix (changing the SDK to satisfy a storyboard that disagrees with the spec) compounds drift across the ecosystem.
+
+## When to Use
+
+- A `storyboard run` step fails on an adapter you believe satisfies the spec
+- The runner reports `expect_error.code` mismatch, `context_outputs path did not resolve`, or a `response_schema` failure on a response that round-trips through the generated TS types
+- You're tempted to add a field, change an error code, or adjust a response shape "to make the test pass"
+
+**Not this skill:**
+
+- Real adopter bugs (your handler returns malformed data, throws unexpectedly, ignores a required field) — fix the adapter
+- Wire-schema validation failures (`additionalProperties`, missing required) on requests YOU sent — fix the request
+
+## The rubric
+
+For any failing step, work the three checks in order. **Stop at the first answer.**
+
+### 1. Does the spec define the contract the storyboard is asserting?
+
+Open the schema the storyboard's step references (`schemas/cache/<version>/<protocol>/<tool>-response.json` or similar). Find the field, error code, or shape the storyboard expects.
+
+- **Field exists in the spec, with the shape the storyboard expects** → continue to step 2.
+- **Field exists in the spec but with a different shape** → spec or storyboard mismatch; the storyboard is wrong. File upstream against `adcontextprotocol/adcp`. Cite the schema file path + line.
+- **Field does NOT exist in the spec** → the storyboard authored an opinion that has no spec basis. The storyboard is wrong. File upstream.
+- **Spec is silent** (the contract is ambiguous) → flag the spec gap upstream. The storyboard's interpretation may be reasonable, but adopters can't know which interpretation to follow without spec clarity.
+
+### 2. Does the SDK shape match the spec?
+
+If the spec defines the contract correctly, check whether the SDK's generated TS types and runtime validators match it. Read the relevant `src/lib/types/*.generated.ts` interface and confirm:
+
+- Every `required` field in the schema is present and non-optional in the TS type
+- Every discriminator (e.g., `asset_type`, `status`) is preserved (codegen sometimes strips `oneOf` discriminators when generating union types)
+- Format constraints (date vs date-time, URL pattern, idempotency_key length/pattern) are reflected in either the TS type or the framework's runtime validator
+
+- **TS type matches spec, runtime validation works** → continue to step 3.
+- **TS type allows what spec rejects (or vice versa)** → SDK bug. Fix the codegen or hand-fix the type. File against `adcp-client`.
+
+### 3. Is the storyboard's expectation actually testable from the request the runner sent?
+
+Run the failing step in step mode (`adcp storyboard step <agent> <storyboard_id> <step_id> --json`) and inspect:
+
+- The actual request payload the runner sent
+- The actual response your adapter returned
+- Each `validations[]` entry's pass/fail
+
+Common patterns:
+
+- **`context_outputs path did not resolve`** → the runner couldn't capture a value from your response under the expected path. Check whether the path matches what the spec defines (e.g., adcp#3892 captured `rights_grant_id` but the spec field is `rights_id` — storyboard was wrong).
+- **`expect_error: code: X`** but your adapter returned a structured success response (e.g., `AcquireRightsRejected` with `reason`) → storyboard is asserting a thrown-error shape when the spec gives a first-class denial arm. Storyboard convention, not spec contract. File upstream.
+- **`unresolved context variables from prior steps`** → the runner can't seed a variable the storyboard requires. Runner gap. File upstream against the storyboard runner.
+
+## Heuristics
+
+- **Generated TS types** are not always tighter than the schema. Discriminator fields, `additionalProperties: false` constraints, and `oneOf` arms can be loosened during codegen. Trust the JSON Schema as ground truth.
+- **`response_schema` validation passes but the step still fails** → almost always a storyboard `context_outputs` or `expect_error` mismatch. Your response is correct; the test's assertion is wrong.
+- **A storyboard expects a thrown error code** (`expect_error: true` + `code: X`) when the spec defines a structured denial arm → the storyboard is shipping a non-spec convention. The Rejected/Pending/Acquired union is the canonical shape; thrown error codes are for system failures (timeout, unreachable), not policy decisions.
+- **`requires_scenarios:`** in a storyboard YAML lists prerequisite scenarios that must run first. Step-mode runs lose this dependency; use full `storyboard run` mode to verify, then re-step the failing piece for diagnostics.
+
+## What to file
+
+When the rubric points upstream, file with this template:
+
+> **Title**: `<storyboard_id>` step `<step_id>`: `<assertion>` is non-spec — `<canonical_shape>` is the canonical wire shape
+>
+> **Repro**: Run any spec-compliant adapter; show the failing step's `--json` output.
+>
+> **Root cause**: Cite the spec schema file path + line that defines (or is silent on) the contract the storyboard asserts.
+>
+> **Fix**: Update the storyboard YAML (or the spec doc-comment, if the spec is genuinely ambiguous).
+
+Cross-link to the adapter PR that surfaced it. The storyboard maintainers see the convergent signal across adopters and can prioritize.
+
+## Examples from production
+
+Real triage walks from this codebase:
+
+- **adcontextprotocol/adcp#3892** (closed): brand-rights storyboard's `acquire_rights` step captured `rights_grant_id` via `context_outputs`. Spec field is `rights_id`. Cascading skip on next step. **Resolution**: spec → field is `rights_id`; storyboard is wrong; filed; closed.
+- **adcontextprotocol/adcp#3914** (open): brand-rights/governance_denied storyboard's `acquire_rights_denied` step expected thrown `code: GOVERNANCE_DENIED`. Spec gives `AcquireRightsRejected` arm with `reason`. **Resolution**: storyboard is asserting a non-spec convention; filed upstream; adapter ships spec-correct shape.
+- **adcontextprotocol/adcp#3913** (open): `brand_rights/governance_denied` storyboard step `sync_governance` skips because `$context.governance_agent_url` is unresolved; runner has no `--context` flag for full `storyboard run` mode. **Resolution**: runner gap, not adapter or spec gap; filed upstream.
+
+## See also
+
+- CLAUDE.md (this repo): "When a compliance storyboard fails, triage before patching" — the inline guidance this skill expands.
+- `docs/guides/VALIDATE-YOUR-AGENT.md` — adopter-facing validation flow that runs storyboards.
+- `docs/development/WIRE-VERSION-COMPAT.md` — storyboard cache layout per spec version.

package/skills/call-adcp-agent.previous/SKILL.md

@@ -1,339 +0,0 @@
----
-name: call-adcp-agent
-description: Wire-level invariants for any AdCP buyer call — idempotency_key replay semantics, account `oneOf` variants, async `status:'submitted'`+`task_id` polling, error recovery from `adcp_error.issues[]`. Load before any per-protocol task skill (adcp-media-buy, adcp-creative, adcp-signals, adcp-governance, adcp-si, adcp-brand) when calling an AdCP agent as a buyer.
-adcp_version: "3.x"
-type: cross-cutting
----
-
-# Call an AdCP agent
-
-## Overview
-
-AdCP (Ad Context Protocol) agents expose a fixed tool surface (`get_products`, `create_media_buy`, `get_signals`, …) over MCP or A2A. Tool names come from `get_adcp_capabilities`; exact request/response shapes come from `get_schema(tool_name)` when the agent exposes it, otherwise from the bundled JSON Schemas your SDK ships (the layout differs by SDK — see "Discovery chain" below). This skill teaches the invariants that don't live cleanly in any schema: cross-tool patterns, async flow, error recovery.
-
-## When to Use
-
-- User wants to call a publisher / SSP / retail media network over AdCP
-- Tool names like `get_products`, `create_media_buy`, `sync_creatives`, `get_signals` appear in the available-tools list
-- Agent card advertises `protocolVersion: '0.3.0'` with `skills` listing AdCP tool names
-- **Not this skill:** building an AdCP seller agent (see `@adcp/client/skills/build-seller-agent/` and analogous SDK skills)
-
-## Discovery chain
-
-Walk these in order on first contact:
-
-1. **Agent card** (A2A) or **`tools/list`** (MCP): returns tool NAMES. AdCP MCP servers no longer publish per-tool parameter schemas in `tools/list` — everything shows `{type: 'object', properties: {}}`. Don't try to infer shape from here.
-2. **`get_adcp_capabilities`**: returns supported protocols (`media_buy`, `signals`, `creative`, …), AdCP major versions, feature flags. Tells you WHICH tools this agent supports, not how to call them.
-3. **`get_schema(tool_name)`** *(when the agent exposes it — pending standardization in [#3057](https://github.com/adcontextprotocol/adcp/issues/3057), not yet universal)*: returns the JSON Schema for a tool's request/response. Preferred over reading bundled schemas when available.
-4. **Bundled schemas** (offline, authoritative): every SDK ships the AdCP JSON Schemas locally. Path differs by SDK — spec repo source uses `dist/schemas/<version>/bundled/`, `@adcp/client` puts them at `schemas/cache/<version>/bundled/` after `npm run sync-schemas`, Python and Go SDKs use their own conventions. **Don't hardcode a path** — let the SDK's loader find them, or ask the developer. Each schema is `<protocol>/<tool>-{request,response}.json` once you locate the bundle. The canonical source for every SDK is `https://adcontextprotocol.org/protocol/<version>.tgz`.
-
-## Non-obvious rules every buyer must follow
-
-### `idempotency_key` is required on every mutating tool
-
-UUID format. The key is your retry-safety guarantee — and the most common way naive callers create duplicate media buys is by misunderstanding it:
-
-- **Same key on retry → replay.** The server returns the SAME response — same `task_id`, same `media_buy_id`, same shape, byte-for-byte. Use this for transport-level retries (timeout, 5xx, dropped connection).
-- **Fresh key on retry → NEW operation.** Generating a new UUID because the previous attempt failed is how you double-book. Reuse the key until you've seen a terminal response (success, error, or non-retryable error).
-- **Same key, different body → server-defined.** Most agents return the original cached response and ignore the body change. Don't rely on it — pick a fresh key only when you genuinely want a new operation.
-- For async flows, the replayed response carries the **same `task_id`**, so polling continues against the same task instead of forking a duplicate.
-
-Required on: `create_media_buy`, `update_media_buy`, `sync_creatives`, `sync_audiences`, `sync_accounts`, `sync_catalogs`, `sync_event_sources`, `sync_plans`, `sync_governance`, `activate_signal`, `acquire_rights`, `log_event`, `report_usage`, `provide_performance_feedback`, `report_plan_outcome`, `create_property_list`, `update_property_list`, `delete_property_list`, `create_collection_list`, `update_collection_list`, `delete_collection_list`, `create_content_standards`, `update_content_standards`, `calibrate_content`, `si_initiate_session`, `si_send_message`.
-
-Missing the key → `adcp_error.code: 'VALIDATION_ERROR'` with `/idempotency_key` in `issues`.
-
-### `account` is a `oneOf` — pick ONE variant, send ONLY its fields
-
-Probably the single most common stumble for naive LLMs. `account` is a discriminated union. Per AdCP 3.0, two variants on `create_media_buy` / `update_media_buy`:
-
-```json
-// variant 0: by seller-assigned id (from sync_accounts or list_accounts)
-"account": { "account_id": "seller_assigned_id" }
-
-// variant 1: by natural key (brand + operator, optional sandbox)
-"account": { "brand": { "domain": "acme.com" }, "operator": "sales.example" }
-```
-
-**Do NOT merge required fields across variants** — `additionalProperties: false` on each variant means `{account_id, brand}` fails BOTH. Pick one variant and send only its fields. Always check the specific tool's schema because other tools (e.g. `sync_creatives`) may accept a superset.
-
-### `brand` takes `{domain}` — not `{brand_id}`
-
-```json
-"brand": { "domain": "acme.example" }
-```
-
-### Async responses: `status: 'submitted'` means "queued, poll later"
-
-A mutating tool can return one of three shapes:
-
-```json
-// Success (sync): the work is done
-{ "media_buy_id": "mb_123", "packages": [...], "confirmed_at": "..." }
-
-// Submitted (async): the work is queued
-{ "status": "submitted", "task_id": "tk_abc", "message": "Awaiting IO signature" }
-
-// Error: don't retry without fixing
-{ "errors": [{ "code": "PRODUCT_NOT_FOUND", "message": "..." }] }
-```
-
-When you see `status: 'submitted'`, the work is NOT complete. Poll via `tasks/get` (A2A) or the MCP async task extension, using the `task_id`. Over A2A the AdCP `task_id` also rides on `artifact.metadata.adcp_task_id` — both work.
-
-### `packages[*]` on media buys
-
-```json
-"packages": [
-  { "buyer_ref": "pkg_1", "product_id": "p_from_catalog", "budget": 10000, "pricing_option_id": "po_xyz" }
-]
-```
-
-`budget` is a **number** (not `{amount, currency}` — currency is implied by the pricing option). Required per package: `product_id`, `budget`, `pricing_option_id`. `buyer_ref` is optional but strongly recommended as a buyer-side correlation id across retries and reporting.
-
-## Error envelope — read `issues[]` to recover
-
-Every validation failure produces:
-
-```json
-{
-  "adcp_error": {
-    "code": "VALIDATION_ERROR",
-    "recovery": "correctable",
-    "field": "/first/offending/pointer",
-    "issues": [
-      {
-        "pointer": "/account",
-        "keyword": "oneOf",
-        "message": "must match exactly one schema in oneOf",
-        "variants": [
-          { "index": 0, "required": ["account_id"],        "properties": ["account_id"] },
-          { "index": 1, "required": ["brand", "operator"], "properties": ["brand", "operator", "sandbox"] }
-        ]
-      },
-      { "pointer": "/brand/domain", "keyword": "required", "message": "must have required property 'domain'" }
-    ]
-  }
-}
-```
-
-- `issues[].pointer` — RFC 6901 JSON Pointer to the field.
-- `issues[].keyword` — AJV keyword (`required`, `type`, `oneOf`, `anyOf`, `additionalProperties`, `format`, `enum`).
-- `issues[].variants` — when the keyword is `oneOf` or `anyOf`, each entry lists one variant's `required` + declared `properties`. **Pick ONE variant**, send only its `required` fields. This is the fastest recovery path when you didn't know the field was a union.
-
-Patch the pointers, don't re-guess what the skill or the `variants` already told you, resend. Three attempts should cover every field.
-
-## Minimal working examples
-
-### get_products
-
-```json
-{
-  "buying_mode": "brief",
-  "brief": "premium CTV sports inventory for live NBA finals in major US markets"
-}
-```
-
-Returns `{ products: [{ product_id, name, description, delivery_type, pricing_options, ... }] }`.
-
-### create_media_buy
-
-```json
-{
-  "idempotency_key": "<uuid>",
-  "account": { "account_id": "seller_assigned_id" },
-  "brand": { "domain": "acme.example" },
-  "start_time": "2026-05-01T00:00:00Z",
-  "end_time": "2026-05-31T23:59:59Z",
-  "packages": [
-    {
-      "buyer_ref": "pkg_1",
-      "product_id": "<product_id from get_products>",
-      "budget": 10000,
-      "pricing_option_id": "<pricing_option_id from product.pricing_options>"
-    }
-  ]
-}
-```
-
-If you don't have a `seller_assigned_id`, use the natural-key variant instead:
-`"account": { "brand": { "domain": "acme.example" }, "operator": "sales.example" }`.
-
-Returns **either** `{ media_buy_id, packages: [...], confirmed_at }` (sync) **or** `{ status: 'submitted', task_id, message }` (async — guaranteed / IO-signed flows).
-
-### sync_creatives
-
-```json
-{
-  "idempotency_key": "<uuid>",
-  "account": { "account_id": "seller_assigned_id" },
-  "creatives": [
-    {
-      "creative_id": "cr_1",
-      "name": "My Creative",
-      "format_id": { "agent_url": "https://creatives.adcontextprotocol.org", "id": "video_1920x1080" },
-      "assets": {}
-    }
-  ]
-}
-```
-
-Per-creative required: `creative_id`, `name`, `format_id: { agent_url, id }`, `assets` (shape depends on `format_id`; start with `{}` then fill required asset keys per format spec). Returns `{ creatives: [{ creative_id, action, status }] }` — items may fail individually without failing the batch.
-
-### get_signals
-
-```json
-{
-  "signal_spec": "female professionals 25-54 in major US metros"
-}
-```
-
-Returns `{ signals: [{ signal_agent_segment_id, match_rate, pricing, ... }] }`. Note: the identifier field is `signal_agent_segment_id` (not `signal_id`) — used as input to `activate_signal` below.
-
-### activate_signal
-
-```json
-{
-  "idempotency_key": "<uuid>",
-  "signal_agent_segment_id": "sig_premium_ctv_sports",
-  "destinations": [
-    { "type": "platform", "platform": "the-trade-desk" }
-  ]
-}
-```
-
-`destinations[]` is a `oneOf`: either `{type: 'platform', platform, account?}` OR `{type, agent_url, account?}`. Pick one shape per destination.
-
-## Transport notes
-
-- **MCP**: `tools/call` with `{ name: 'tool_name', arguments: {...} }`. Returns `{ content, structuredContent, isError? }`. Read `structuredContent` for the typed response.
-  - **Use the official `@modelcontextprotocol/sdk` client.** The Streamable HTTP transport requires `Accept: application/json, text/event-stream` on every request — a raw `fetch()` with only `Accept: application/json` gets an unhelpful `406 Not Acceptable` from the server before any AdCP framing runs. The official client sets the header correctly; reach for it instead of rolling your own HTTP plumbing.
-- **A2A**: `message/send` with a `DataPart` of shape `{ skill: 'tool_name', input: {...} }` (the legacy key `parameters` is also accepted). Returns an A2A `Task`; the typed response is at `task.artifacts[0].parts[0].data`.
-
-Both transports share: idempotency, error shape, schema enforcement, and handler semantics. If a call works on one, the equivalent call works on the other.
-
-## Gotchas I keep seeing
-
-1. **Merging `oneOf` variants**: see the account section above. If you see three `additionalProperties` errors under one pointer, you merged. Drop to one variant.
-2. **`budget` as an object**: it's a number. Currency comes from the `pricing_option`.
-3. **`brand.brand_id` instead of `brand.domain`**: spec uses `domain`.
-4. **Forgetting `idempotency_key`**: required on every mutating tool; see the list above.
-5. **Treating A2A `Task.state: 'completed'` as AdCP completion**: A2A task state = transport call lifecycle. AdCP-level completion is in the artifact's payload (`structuredContent.status` or `data.status`). A `completed` A2A task can still carry a `submitted` AdCP response.
-6. **`format_id` as a string**: `format_id` is always an object `{ agent_url, id }` (and sometimes `{ width, height, duration_ms }` for dimensions). Sending `"format_id": "video_1920x1080"` fails with an `additionalProperties` / `type` error — pass the object.
-
-## Symptom → fix
-
-Quick lookup before reading the full envelope. Match what you see in `adcp_error.issues[*]`, apply the fix:
-
-| Symptom | What it means | Fix |
-|---|---|---|
-| `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
-| 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants ({account_id, brand, operator, …}) | Drop to one variant. Don't keep "extra" fields "for completeness". |
-| `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse it on retries. |
-| `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
-| `additionalProperties` at `/format_id` (string passed) | Sent `"format_id": "video_..."` | `format_id` is `{agent_url, id}` — always an object. |
-| `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
-| Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`. |
-| `recovery: 'transient'` (rate limit, 5xx, timeout) | Server-side, retry-safe | Retry with the **same** `idempotency_key`. |
-| `406 Not Acceptable` before any AdCP framing | Hand-rolled HTTP without `Accept: text/event-stream` (MCP transport) | Use `@modelcontextprotocol/sdk` client; it sets the right Accept header. |
-| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. (See exceptions below — four codes are technically `correctable` but operator-semantically human-escalate.) |
-| `recovery: 'terminal'` (account suspended, payment required, …) | Requires human action | Don't retry. Surface to the user. |
-| HTTP 401 with `WWW-Authenticate` header | Missing or expired credential | Add `Authorization` per the agent's auth spec; re-auth if applicable. |
-
-> **⚠️ Four codes are technically `correctable` but operator-semantically human-escalate. Don't auto-tweak.**
->
-> - **`POLICY_VIOLATION`** — buyer's content/targeting violates seller policy. Auto-mutating creative or targeting and resubmitting **looks like evasion** to the seller's governance reviewer. Surface to a human.
-> - **`COMPLIANCE_UNSATISFIED`** — required disclosure can't be satisfied by the chosen format. Auto-relaxing the compliance section IS the compliance failure. Surface to a human.
-> - **`GOVERNANCE_DENIED`** — registered governance agent rejected the spend. Auto-shrinking budget and retrying looks like governance evasion. Surface to the plan operator.
-> - **`AUTH_REQUIRED`** — conflates missing creds (genuinely correctable) with revoked / expired creds (operator must rotate). Until [adcontextprotocol/adcp#3730](https://github.com/adcontextprotocol/adcp/issues/3730) splits this into `auth_missing` + `auth_invalid`, treat as escalate-after-one-attempt.
->
-> Spec recovery on these is `correctable`; operator behavior is human-in-loop. The pattern: read `error.message` + `error.suggestion`, surface to the user, **don't loop**.
-
-### Operationalize the recovery rules — `decideRetry`
-
-`@adcp/sdk` exports `decideRetry(error, ctx?)` which encodes the operator-grade defaults from the table above plus this section. It returns a discriminated `RetryDecision` so the type system enforces the same-vs-fresh `idempotency_key` rule:
-
-```typescript
-import { decideRetry } from '@adcp/sdk';
-import { randomUUID } from 'node:crypto';
-
-async function callWithRetry(toolName: string, params: Record<string, unknown>): Promise<unknown> {
-  let attempt = 1;
-  let idempotencyKey = randomUUID();
-
-  while (true) {
-    try {
-      return await agent.call(toolName, { ...params, idempotency_key: idempotencyKey });
-    } catch (e) {
-      const error = extractAdcpError(e); // your SDK's error extractor
-      if (!error) throw e; // not an AdCP-shaped failure — let it bubble
-
-      const decision = decideRetry(error, { attempt });
-
-      if (decision.action === 'retry') {
-        // Server-side transient (RATE_LIMITED, SERVICE_UNAVAILABLE, CONFLICT).
-        // Replay with the SAME idempotency_key after the suggested delay.
-        await sleep(decision.delayMs);
-        attempt++;
-        continue;
-      }
-
-      if (decision.action === 'mutate-and-retry') {
-        // Buyer-fixable. Apply the seller's correction (decision.field /
-        // decision.suggestion) and mint a FRESH idempotency_key — payload
-        // changed, so the seller's replay-window must NOT dedupe.
-        params = applyCorrection(params, error, decision); // your domain logic
-        idempotencyKey = randomUUID();
-        await sleep(decision.delayMs); // small jitter (~125-250ms by default)
-        attempt++;
-        continue;
-      }
-
-      // 'escalate' — stop the loop and surface to a human. Includes
-      // commercial-relationship signals (POLICY_VIOLATION etc.), auth
-      // failures, IDEMPOTENCY_EXPIRED (do a natural-key check first!),
-      // attempt-cap exhaustion, and unknown vendor codes.
-      throw new EscalationRequired(decision.reason, decision.message);
-    }
-  }
-}
-```
-
-The discriminated union means TypeScript narrows correctly in each branch — `decision.delayMs` is only available on retry/mutate-and-retry, `decision.field` only on mutate-and-retry, `decision.message` only on escalate.
-
-For per-vertical overrides (e.g., a creative-template platform that legitimately auto-fixes `CREATIVE_REJECTED` format mismatches), instantiate `BuyerRetryPolicy` directly:
-
-```typescript
-import { BuyerRetryPolicy } from '@adcp/sdk';
-
-const policy = new BuyerRetryPolicy({
-  overrides: {
-    CREATIVE_REJECTED: (error) => {
-      if (error.field === 'creative.format' && /unsupported_format/.test(error.message)) {
-        return { action: 'mutate-and-retry', delayMs: 0, attemptCap: 2, sameIdempotencyKey: false, reason: 'capability' };
-      }
-      return null; // fall through to default (escalate as commercial)
-    },
-  },
-});
-
-const decision = policy.decide(error, { attempt });
-```
-
-Default policy is intentionally conservative — see the source comments in `src/lib/utils/buyer-retry-policy.ts` for per-code reasoning.
-
-If your symptom isn't here, fall through to the next section.
-
-## If you get stuck
-
-Priority order:
-
-1. Re-read the failure's `issues[]`. The pointer list plus this skill covers 80% of cases.
-2. Call `get_schema(tool_name)` if the agent exposes it (see [#3057](https://github.com/adcontextprotocol/adcp/issues/3057) for the pending standard).
-3. Read the bundled JSON Schema for `<protocol>/<tool>-request.json` — see Discovery chain step 4 for path resolution. If you can't locate the SDK's schema cache, ask the developer or fall back to `get_schema()`.
-4. Consult the per-protocol skill (`adcp-media-buy`, `adcp-creative`, …) for specialism-specific patterns.
-
-## Related
-
-- [Calling an agent (docs)](https://adcontextprotocol.org/docs/protocol/calling-an-agent) — human-readable narrative form of this skill
-- `skills/adcp-media-buy/`, `skills/adcp-creative/`, `skills/adcp-signals/`, `skills/adcp-governance/`, `skills/adcp-si/`, `skills/adcp-brand/` — per-protocol task skills (layered on top of this one)
-- `@adcp/client/skills/build-seller-agent/SKILL.md` — building agents on the other side of the call
-- Bundled JSON Schemas — canonical for every tool, version-pinned. Path differs by SDK (see Discovery chain step 4). Pulled from the protocol tarball at `/protocol/<version>.tgz`.