@adcp/client 4.23.0 → 4.24.0

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

@@ -0,0 +1,313 @@
+---
+name: build-seller-agent
+description: Use when building an AdCP seller agent — a publisher, SSP, or retail media network that sells advertising inventory to buyer agents.
+---
+
+# Build a Seller Agent
+
+## Overview
+
+A seller agent receives briefs from buyers, returns products with pricing, accepts media buys, manages creatives, and reports delivery. The business model — what you sell, how you price it, and whether humans approve deals — shapes every implementation decision. Determine that first.
+
+## When to Use
+
+- User wants to build an agent that sells ad inventory
+- User mentions publisher, SSP, retail media, or media network in the context of AdCP
+- User references `get_products`, `create_media_buy`, or the media buy protocol
+
+**Not this skill:**
+- Buying ad inventory → that's a buyer/DSP agent (see `docs/getting-started.md`)
+- Serving audience segments → `skills/build-signals-agent/`
+- Rendering creatives from briefs → that's a creative agent
+
+## Before Writing Code
+
+Determine these five things. Ask the user — don't guess.
+
+### 1. What Kind of Seller?
+
+- **Premium publisher** — guaranteed inventory, fixed pricing, IO approval (ESPN, NYT)
+- **SSP / Exchange** — non-guaranteed, auction-based, instant activation
+- **Retail media network** — both guaranteed and non-guaranteed, proposals, catalog-driven creative, conversion tracking
+
+### 2. Guaranteed or Non-Guaranteed?
+
+- **Guaranteed** — `delivery_type: "guaranteed"`, may require async approval (`submitted` → `pending_approval` → `confirmed`)
+- **Non-guaranteed** — `delivery_type: "non_guaranteed"`, buyer sets `bid_price`, instant activation
+
+Many sellers support both — different products can have different delivery types.
+
+### 3. Products and Pricing
+
+Get specific inventory. Each product needs:
+- Name and description
+- Channel: `display`, `olv`, `ctv`, `social`, `retail_media`, `dooh`, etc.
+- Creative format requirements
+- At least one pricing option
+
+Pricing models:
+- `cpm` — `{ pricing_model: "cpm", fixed_price: 12.00, currency: "USD" }`
+- `cpc` — `{ pricing_model: "cpc", fixed_price: 1.50, currency: "USD" }`
+- Auction — `{ pricing_model: "cpm", floor_price: 5.00, currency: "USD" }` (buyer bids above floor)
+
+Each pricing option can set `min_spend_per_package` to enforce minimum budgets.
+
+### 4. Approval Workflow
+
+For guaranteed buys, choose one:
+- **Instant confirmation** — `create_media_buy` returns completed with confirmed status. Simplest.
+- **Async approval** — returns `submitted`, buyer polls `get_media_buys`. Use `registerAdcpTaskTool`.
+- **Human-in-the-loop** — returns `input-required` with a setup URL for IO signing.
+
+Non-guaranteed buys are always instant confirmation.
+
+### 5. Creative Management
+
+- **Standard** — `list_creative_formats` + `sync_creatives`. Buyer uploads assets, seller validates.
+- **Catalog-driven** — buyer syncs product catalog via `sync_catalogs`. Common for retail media.
+- **None** — creative handled out-of-band. Omit creative tools.
+
+## Tools and Required Response Shapes
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['media_buy'],
+})
+```
+
+**`sync_accounts`** — `SyncAccountsRequestSchema.shape`
+```
+taskToolResponse({
+  accounts: [{
+    account_id: string,       // required - your platform's ID
+    brand: { domain: string },// required - echo back from request
+    operator: string,         // required - echo back from request
+    action: 'created' | 'updated',  // required
+    status: 'active' | 'pending_approval',  // required
+  }]
+})
+```
+
+**`sync_governance`** — `SyncGovernanceRequestSchema.shape`
+```
+taskToolResponse({
+  accounts: [{
+    account: { brand: {...}, operator: string },  // required - echo back
+    status: 'synced',         // required
+    governance_agents: [{ url: string, categories?: string[] }],  // required
+  }]
+})
+```
+
+**`get_products`** — `GetProductsRequestSchema.shape`
+```
+productsResponse({
+  products: Product[],  // required - each needs product_id, delivery_type, pricing_options
+  sandbox: true,        // for mock data
+})
+```
+
+**`create_media_buy`** — `CreateMediaBuyRequestSchema.shape`
+```
+mediaBuyResponse({
+  media_buy_id: string,       // required
+  packages: [{                // required
+    package_id: string,
+    product_id: string,
+    pricing_option_id: string,
+    budget: number,
+  }],
+})
+```
+
+**`get_media_buys`** — `GetMediaBuysRequestSchema.shape`
+```
+taskToolResponse({
+  media_buys: [{
+    media_buy_id: string,   // required
+    status: 'active' | 'pending_start' | ...,  // required
+    currency: 'USD',        // required
+    packages: [{
+      package_id: string,   // required
+    }],
+  }]
+})
+```
+
+**`list_creative_formats`** — `ListCreativeFormatsRequestSchema.shape`
+```
+taskToolResponse({
+  formats: [{
+    format_id: { agent_url: string, id: string },  // required
+    name: string,  // required
+  }]
+})
+```
+
+**`sync_creatives`** — `SyncCreativesRequestSchema.shape`
+```
+taskToolResponse({
+  creatives: [{
+    creative_id: string,          // required - echo from request
+    action: 'created' | 'updated',  // required
+  }]
+})
+```
+
+**`get_media_buy_delivery`** — `GetMediaBuyDeliveryRequestSchema.shape`
+```
+deliveryResponse({
+  reporting_period: { start: string, end: string },  // required - ISO timestamps
+  media_buy_deliveries: [{
+    media_buy_id: string,     // required
+    status: 'active',         // required
+    totals: { impressions: number, spend: number },  // required
+    by_package: [],           // required (can be empty)
+  }]
+})
+```
+
+## Compliance Testing (Optional)
+
+Add `registerTestController` so the comply framework can deterministically test your state machines. Without it, compliance testing relies on observational storyboards that can't force state transitions.
+
+```
+import { registerTestController } from '@adcp/client';
+import type { TestControllerStore } from '@adcp/client';
+
+const store: TestControllerStore = {
+  async forceAccountStatus(accountId, status) {
+    const prev = accounts.get(accountId);
+    if (!prev) throw new TestControllerError('NOT_FOUND', `Account ${accountId} not found`);
+    accounts.set(accountId, status);
+    return { success: true, previous_state: prev, current_state: status };
+  },
+  async forceMediaBuyStatus(mediaBuyId, status) {
+    const prev = mediaBuys.get(mediaBuyId);
+    if (!prev) throw new TestControllerError('NOT_FOUND', `Media buy ${mediaBuyId} not found`);
+    const terminal = ['completed', 'rejected', 'canceled'];
+    if (terminal.includes(prev))
+      throw new TestControllerError('INVALID_TRANSITION', `Cannot transition from ${prev}`, prev);
+    mediaBuys.set(mediaBuyId, status);
+    return { success: true, previous_state: prev, current_state: status };
+  },
+  async forceCreativeStatus(creativeId, status, rejectionReason) {
+    const prev = creatives.get(creativeId);
+    if (!prev) throw new TestControllerError('NOT_FOUND', `Creative ${creativeId} not found`);
+    if (prev === 'archived')
+      throw new TestControllerError('INVALID_TRANSITION', `Cannot transition from archived`, prev);
+    creatives.set(creativeId, status);
+    return { success: true, previous_state: prev, current_state: status };
+  },
+  async simulateDelivery(mediaBuyId, params) {
+    // Accumulate delivery data and return simulated + cumulative totals
+    return { success: true, simulated: { ...params }, cumulative: { ...params } };
+  },
+  async simulateBudgetSpend(params) {
+    return { success: true, simulated: { spend_percentage: params.spend_percentage } };
+  },
+};
+
+registerTestController(server, store);
+```
+
+When using this, declare `compliance_testing` in `supported_protocols`:
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['media_buy', 'compliance_testing'],
+})
+```
+
+Only implement the store methods for scenarios your agent supports. Unimplemented methods are excluded from `list_scenarios` automatically.
+
+The storyboard tests state machine correctness:
+- `NOT_FOUND` when forcing transitions on unknown entities
+- `INVALID_TRANSITION` when transitioning from terminal states (completed, rejected, canceled for media buys; archived for creatives)
+- Successful transitions between valid states
+
+Throw `TestControllerError` from store methods for typed errors. The SDK validates status enum values before calling your store.
+
+Validate with: `adcp storyboard run <agent> deterministic_testing --json`
+
+## SDK Quick Reference
+
+| SDK piece | Usage |
+|-----------|-------|
+| `serve(createAgent)` | Start HTTP server on `:3001/mcp` |
+| `createTaskCapableServer(name, version, { taskStore })` | Create MCP server with task support |
+| `server.tool(name, Schema.shape, handler)` | Register tool — `.shape` unwraps Zod for MCP SDK |
+| `capabilitiesResponse(data)` | Build `get_adcp_capabilities` response |
+| `productsResponse(data)` | Build `get_products` response |
+| `mediaBuyResponse(data)` | Build `create_media_buy` response |
+| `deliveryResponse(data)` | Build `get_media_buy_delivery` response |
+| `taskToolResponse(data, summary)` | Build generic tool response |
+| `adcpError(code, { message })` | Structured error (e.g., `BUDGET_TOO_LOW`, `PRODUCT_NOT_FOUND`) |
+| `registerTestController(server, store)` | Add `comply_test_controller` for deterministic testing |
+| `TestControllerError(code, message)` | Typed error from store methods |
+
+Import everything from `@adcp/client`. Types from `@adcp/client` with `import type`.
+
+## Implementation
+
+1. Single `.ts` file — all tools in one file
+2. Always register `get_adcp_capabilities` as the **first** tool with empty `{}` schema
+3. Use `Schema.shape` (not `Schema`) when registering tools
+4. Use response builders — never return raw JSON
+5. Set `sandbox: true` on all mock/demo responses
+6. Use `ServeContext` pattern: `function createAgent({ taskStore }: ServeContext)` and pass `taskStore` to `createTaskCapableServer`
+
+The skill contains everything you need. Do not read additional docs before writing code.
+
+## Validation
+
+**After writing the agent, validate it. Fix failures. Repeat.**
+
+**Full validation** (if you can bind ports):
+```bash
+npx tsx agent.ts &
+npx @adcp/client storyboard run http://localhost:3001/mcp media_buy_seller --json
+```
+
+**Sandbox validation** (if ports are blocked):
+```bash
+npx tsc --noEmit agent.ts
+```
+
+When storyboard output shows failures, fix each one:
+- `response_schema` → response doesn't match Zod schema
+- `field_present` → required field missing
+- MCP error → check tool registration (schema, name)
+
+**Keep iterating until all steps pass.**
+
+## Storyboards
+
+| Storyboard | Use case |
+|-----------|----------|
+| `media_buy_seller` | Full lifecycle — every seller should pass this |
+| `media_buy_non_guaranteed` | Auction flow with bid adjustment |
+| `media_buy_guaranteed_approval` | IO approval workflow |
+| `media_buy_proposal_mode` | AI-generated proposals |
+| `media_buy_catalog_creative` | Catalog sync + conversions |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Pass `Schema` instead of `Schema.shape` | MCP SDK needs unwrapped Zod fields |
+| Skip `get_adcp_capabilities` | Must be the first tool registered |
+| Return raw JSON without response builders | LLM clients need the text content layer |
+| Missing `brand`/`operator` in sync_accounts response | Echo them back from the request — they're required |
+| sync_governance returns wrong shape | Must include `status: 'synced'` and `governance_agents` array |
+| `sandbox: false` on mock data | Buyers may treat mock data as real |
+
+## Reference
+
+- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns and async tools
+- `docs/llms.txt` — full protocol reference
+- `docs/TYPE-SUMMARY.md` — curated type signatures
+- `storyboards/media_buy_seller.yaml` — full buyer interaction sequence
+- `examples/error-compliant-server.ts` — seller with error handling

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

@@ -0,0 +1,203 @@
+---
+name: build-signals-agent
+description: Use when building an AdCP signals agent, creating an audience data server, or standing up a data provider agent that serves targeting segments to buyers.
+---
+
+# Build a Signals Agent
+
+## Overview
+
+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.
+
+## When to Use
+
+- User wants to build an agent that serves audience/targeting data
+- User mentions signals, segments, audiences, data provider, or CDP in the context of AdCP
+- User references `get_signals`, `activate_signal`, or the signals protocol
+
+**Not this skill:**
+- Selling ad inventory (products, packages, media buys) → `skills/build-seller-agent/`
+- Rendering creatives from briefs → that's a creative agent
+- Building a client that *calls* a signals agent → see `docs/getting-started.md`
+
+## Before Writing Code
+
+Determine these four things. Ask the user — don't guess.
+
+### 1. Marketplace or Owned?
+
+These are fundamentally different businesses.
+
+**Marketplace** — aggregates third-party data providers (LiveRamp, Oracle Data Cloud, Lotame). Each signal traces to a `data_provider_domain` that buyers can verify via `adagents.json`. `signal_type: "marketplace"`, `signal_id.source: "catalog"`.
+
+**Owned** — first-party data (retailer CDP, publisher contextual, CRM). Buyers trust your agent directly. `signal_type: "owned"` or `"custom"`, `signal_id.source: "agent"`.
+
+### 2. What Segments?
+
+Get specifics: names, definitions, what each represents. Push for 3-5 segments with variety. Each needs:
+- Clear behavioral/demographic definition
+- Realistic `coverage_percentage` (typically 5-30%)
+- Value type: `binary` (in/out), `categorical` (tier levels — define the categories), or `numeric` (score range — define min/max)
+
+### 3. Pricing
+
+At least one pricing option per signal:
+- `cpm` — `{ pricing_option_id: "po_cpm", model: "cpm", cpm: 2.50, currency: "USD" }`
+- `percent_of_media` — `{ pricing_option_id: "po_pom", model: "percent_of_media", percent: 15, currency: "USD" }`
+- `flat_fee` — `{ pricing_option_id: "po_flat", model: "flat_fee", amount: 5000, period: "monthly", currency: "USD" }`
+
+### 4. Activation Destinations
+
+If implementing `activate_signal`:
+- **Platform** (DSP): `type: "platform"`, returns `activation_key: { type: "segment_id", segment_id: "..." }`
+- **Agent** (sales agent): `type: "agent"`, returns `activation_key: { type: "key_value", key: "...", value: "..." }`
+
+## Tools and Required Response Shapes
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['signals'],
+})
+```
+
+**`get_signals`** — `GetSignalsRequestSchema.shape`
+
+Two discovery modes — support both:
+1. `signal_spec` — natural language. Match against segment names and descriptions.
+2. `signal_ids` — exact lookup by `{ source, data_provider_domain, id }` or `{ source, agent_url, id }`.
+
+Plus filtering via `filters.catalog_types`, `filters.max_cpm`, `filters.min_coverage_percentage`, and `max_results`.
+
+```
+taskToolResponse({
+  signals: [{
+    signal_agent_segment_id: string,  // required - key for activate_signal
+    name: string,                     // required
+    description: string,              // required
+    signal_type: 'marketplace' | 'owned' | 'custom',  // required
+    data_provider: string,            // required - your company name
+    coverage_percentage: number,      // required - 0 to 100
+    deployments: [],                  // required - empty array (not live until activated)
+    pricing_options: [{               // required - at least one
+      pricing_option_id: string,      // required
+      model: 'cpm',                   // required - discriminator
+      cpm: number,                    // required for cpm model
+      currency: 'USD',               // required
+    }],
+    // signal_id is critical — shape depends on marketplace vs owned:
+    signal_id: {
+      source: 'catalog',             // marketplace
+      data_provider_domain: string,  // marketplace — domain for provenance verification
+      id: string,                    // unique segment ID
+    },
+    // OR for owned:
+    signal_id: {
+      source: 'agent',              // owned
+      agent_url: string,            // your agent URL
+      id: string,
+    },
+    value_type: 'binary' | 'categorical' | 'numeric',  // optional but recommended
+  }],
+  sandbox: true,  // for mock data
+})
+```
+
+**`activate_signal`** — `ActivateSignalRequestSchema.shape`
+
+Look up by `signal_agent_segment_id`. Validate `pricing_option_id`. Return deployments matching the requested destinations.
+
+```
+taskToolResponse({
+  deployments: [{
+    // Match the destination type from the request:
+    type: 'platform',              // for platform destinations
+    platform: string,              // echo from request destination
+    account: string | null,        // echo from request
+    is_live: true,                 // signal is now active
+    activation_key: {
+      type: 'segment_id',
+      segment_id: string,          // platform-specific segment ID
+    },
+  }],
+  // OR for agent destinations:
+  deployments: [{
+    type: 'agent',
+    agent_url: string,
+    is_live: true,
+    activation_key: {
+      type: 'key_value',
+      key: string,
+      value: string,
+    },
+  }],
+  sandbox: true,
+})
+```
+
+## SDK Quick Reference
+
+| SDK piece | Usage |
+|-----------|-------|
+| `serve(createAgent)` | Start HTTP server on `:3001/mcp` |
+| `createTaskCapableServer(name, version, { taskStore })` | Create MCP server with task support |
+| `server.tool(name, Schema.shape, handler)` | Register tool — `.shape` unwraps Zod |
+| `capabilitiesResponse(data)` | Build `get_adcp_capabilities` response |
+| `taskToolResponse(data, summary)` | Build tool response |
+| `adcpError(code, { message })` | Structured error (`SIGNAL_NOT_FOUND`, `INVALID_DESTINATION`) |
+| `GetSignalsRequestSchema.shape` | Zod schema for get_signals input |
+| `ActivateSignalRequestSchema.shape` | Zod schema for activate_signal input |
+| `type Signal = GetSignalsResponse['signals'][number]` | Type for a single signal object |
+
+Import everything from `@adcp/client`. Types from `@adcp/client` with `import type`.
+
+## Implementation
+
+1. Single `.ts` file — all tools in one file
+2. Always register `get_adcp_capabilities` as the **first** tool with empty `{}` schema
+3. Use `Schema.shape` (not `Schema`) when registering tools
+4. Set `sandbox: true` for mock/demo data
+5. Use `ServeContext` pattern: `function createAgent({ taskStore }: ServeContext)`
+
+The skill contains everything you need. Do not read additional docs before writing code.
+
+## Validation
+
+**After writing the agent, validate it. Fix failures. Repeat.**
+
+**Full validation** (if you can bind ports):
+```bash
+npx tsx agent.ts &
+npx @adcp/client storyboard run http://localhost:3001/mcp signal_owned --json       # for owned data
+npx @adcp/client storyboard run http://localhost:3001/mcp signal_marketplace --json  # for marketplace
+```
+
+**Sandbox validation** (if ports are blocked):
+```bash
+npx tsc --noEmit agent.ts
+```
+
+**Keep iterating until all steps pass.**
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Pass `Schema` instead of `Schema.shape` | MCP SDK needs unwrapped Zod fields |
+| Skip `get_adcp_capabilities` | Must be the first tool registered |
+| Missing `signal_agent_segment_id` on signals | Buyers can't activate without it |
+| Wrong `signal_id` shape | Marketplace: `{ source: "catalog", data_provider_domain, id }`. Owned: `{ source: "agent", agent_url, id }` |
+| Missing `data_provider` field | Required on every signal — your company/brand name |
+| Empty `pricing_options` array | Must have at least one pricing option per signal |
+| `is_live: true` in get_signals deployments | Signals aren't live until `activate_signal` — use empty `deployments: []` |
+| Activation doesn't match destination type | If request has `type: "platform"`, deployment must be `type: "platform"` |
+| `sandbox: false` on mock data | Buyers may treat mock data as real |
+
+## Reference
+
+- `examples/signals-agent.ts` — complete runnable example
+- `storyboards/signal_marketplace.yaml` — buyer call sequences for marketplace agent
+- `storyboards/signal_owned.yaml` — call sequences for owned data agent
+- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns
+- `docs/llms.txt` — full protocol reference

package/storyboards/campaign_governance_conditions.yaml

@@ -160,9 +160,9 @@ phases:
         expected: |
           Confirm the media buy with governance approval:
           - media_buy_id: your platform's identifier
-          - status: confirmed or active
+          - status: active
           - governance_context: echoed back confirming governance was validated
-          - packages: confirmed line items
+          - packages: line items
 
         sample_request:
           account:

package/storyboards/campaign_governance_delivery.yaml

@@ -164,7 +164,7 @@ phases:
           - check: response_schema
             description: "Response matches get-media-buy-delivery-response.json schema"
           - check: field_present
-            path: "media_buys"
+            path: "media_buy_deliveries"
             description: "Response contains media buy delivery data"
 
   - id: drift_recheck

package/storyboards/campaign_governance_denied.yaml

@@ -129,6 +129,7 @@ phases:
             description: "Response contains a governance decision"
           - check: field_value
             path: "decision"
+            value: "denied"
             description: "Decision is denied"
           - check: field_present
             path: "findings"