examples/seller_agent.py: storyboard content gaps exposed by #296 transport fix

[bokelley]

Context

Once #296 fixes the ASGI transport so the storyboard runner can connect, running

```
npx -y -p @adcp/client@latest adcp storyboard run http://localhost:3001/mcp media_buy_seller --json --allow-http
```

against `examples/seller_agent.py` produces `overall_status: partial` — 29/47 steps pass, 10 fail, 8 skipped, and `controller_detected: false`. Every failure is content-side in the example seller (or its `DemoStore`); none are SDK regressions from this round of releases.

This issue tracks the punch list. Each item is a separate seller-agent fix and can land independently.

Failures

1. `adcp.idempotency` not declared in capabilities — `get_adcp_capabilities` returns `compliance_testing` without an `idempotency` block. PR fix(server): fix streamable-http ASGI error, host binding, and AdCP 3.0.1 scenario gaps #296 added a runtime WARNING log for exactly this case; the example just doesn't follow its own advice. Fix: pass `idempotency=store.capability()` (or `idempotency={"supported": False}`) to `capabilities_response()`.

2. `get_media_buys` response missing `total_budget` — schema validation: `/media_buys/0/total_budget: must have required property 'total_budget'`. The reference `media_buys_response()` either doesn't populate it or the example's seed data drops it.

3. Status returned as `active` instead of `pending_creatives` when no creatives supplied — runner sends `create_media_buy` with no creatives and expects `status=pending_creatives`. The example seller jumps straight to `active`. Fix: branch on `creatives_present` and return `pending_creatives` per the AdCP v3 lifecycle.

4. `list_creative_formats` renders missing required fields — schema validation: each render must have `role`, `dimensions`, and `parameters_from_format_id`, OR match the alternate variant of the discriminated union. Likely a 3.0.1-related schema tightening on the format-render type. Fix: populate render objects with the AdCP 3.0.1-required fields.

5. `list_creative_formats` filter ignored — runner filters for `format_id.id = display_970x250` but the seller returns `display_300x250`. Either the filter parameter isn't honored or the format catalog's primary format is just the wrong one for this storyboard.

6. `update_media_buy` with bogus package_id doesn't return `PACKAGE_NOT_FOUND` — the example doesn't validate package existence; runner expects a structured `PACKAGE_NOT_FOUND` adcp_error.

7. `create_media_buy` for storyboard fixture product fails with "Product 'sports_preroll_q2' not found" — the storyboard pre-populates a product fixture via a `seed_product` controller call. `DemoStore` doesn't override `seed_product` (it's a `NotImplementedError` stub from PR fix(server): fix streamable-http ASGI error, host binding, and AdCP 3.0.1 scenario gaps #296). Without a working `seed_*` controller on the example, every storyboard that needs fixtures skips. Related: the `controller_detected: false` outcome.

Why `controller_detected: false`?

The runner discovers the `comply_test_controller` tool but doesn't grade the controller as detected. `DemoStore` overrides 5 `force_`/`simulate_` scenarios but none of the AdCP 3.0.1 `seed_*` or `force_create_media_buy_arm`/`force_task_completion` ones (the latter come from PR #282, in flight). When PR #282 lands and `DemoStore` overrides at least `force_task_completion` and `seed_creative_format`, controller detection should flip.

Out of scope

• The transport-level fixes — those are fix(server): fix streamable-http ASGI error, host binding, and AdCP 3.0.1 scenario gaps #296.
• Adding the controller scenarios to the SDK base class — those are feat(server): add force_create_media_buy_arm + force_task_completion controller scenarios #282 and partially in fix(server): fix streamable-http ASGI error, host binding, and AdCP 3.0.1 scenario gaps #296.
• Adding a CI job that runs the storyboard suite — separate issue.

Verification

```
ADCP_PORT=3001 python examples/seller_agent.py &
sleep 2
npx -y -p @adcp/client@latest adcp storyboard run \
http://localhost:3001/mcp media_buy_seller --json --allow-http \
| jq '{overall_status, controller_detected, summary, failures}'
```

Target on completion of this punch list: `overall_status: pass`, `controller_detected: true`.

[bokelley]

/triage execute

[bokelley]

Triage

Classification: Bug
Bucket(s): examples
Status: drafting-pr
Milestone: omitted (no target version specified)

What the experts said:

• ad-tech-protocol-expert: all 6 items schema-sound; one blocker fixed (creative_assignments path added to has_creatives check — package-request.json has two creative-attachment fields); PACKAGE_NOT_FOUND is the canonical error code; compound (agent_url, id) key is correct for format_ids filter
• dx-expert: ship with small tweaks — static message in PACKAGE_NOT_FOUND (no user-supplied data in LLM-visible errors per adcp_error docstring); .get() guards in format_ids filter; clarifying comments added for renders schema and filter optionality

My take: Items 1–6 are independent, non-breaking example fixes that directly address schema violations and storyboard failures. Item 7 (seed_product controller stub) is deferred pending #296. The controller_detected: true target additionally requires #282.

PR #308 covers items 1–6. Items 7 + controller_detected remain open here pending #296 and #282.

Shipped (PR #308):

• adcp.idempotency declared in capabilities ({"supported": False})
• get_media_buys includes total_budget
• create_media_buy returns pending_creatives when no creatives/creative_assignments
• list_creative_formats renders have required role + nested dimensions
• list_creative_formats honors format_ids filter
• update_media_buy returns PACKAGE_NOT_FOUND for unknown package IDs

Remaining (blocked):

• seed_product controller stub (blocked on fix(server): fix streamable-http ASGI error, host binding, and AdCP 3.0.1 scenario gaps #296)
• controller_detected: true (blocked on feat(server): add force_create_media_buy_arm + force_task_completion controller scenarios #282)

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01GDFGtecoKD34z3KmZ4GuML

---

Generated by Claude Code

[bokelley]

Triage

Classification: Bug
Bucket(s): examples
Status: drafting-pr
Milestone: (omitted — item 7 blocks full closure)

What the experts said:

• code-reviewer: approved — all 6 fixes correct; valid_actions gap for pending_creatives caught and fixed; nits: silent empty-list on agent_url mismatch in format filter, missing inject_context calls (pre-existing)
• dx-expert: approved — idiomatic, spec-compliant reference after fixes; caught simulate_delivery type mismatch (float → dict) and explicit valid_actions requirement for pending_creatives (both fixed)

My take: Items 1–6 are content-side fixes in the example with no SDK changes. Drafted PR #310. Item 7 (seed_product / controller_detected: false) remains blocked on #282 — once #282 merges, DemoStore needs seed_product, seed_creative_format, and force_task_completion overrides to flip controller detection.

What shipped (PR #310):

• Items 1–6 (all 7 storyboard content failures addressable without feat(server): add force_create_media_buy_arm + force_task_completion controller scenarios #282)

What remains:

• Item 7: DemoStore.seed_product — blocked on feat(server): add force_create_media_buy_arm + force_task_completion controller scenarios #282 landing; resurfaces on merge

Label gap: examples bucket label does not exist in this repo — bucket noted in comment only.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01HAP5upax2a7FrcrmgVwTX2

---

Generated by Claude Code