feat: ADCP 3.0 server DX helpers, type guards, and schema sync

[bokelley]

Summary

Major DX improvements for building ADCP agents in Python, bringing parity with key JS client patterns.

Server DX Helpers (adcp.server.helpers)

• adcp_error() — structured errors with all 32 spec error codes and auto-recovery classification (transient/correctable/terminal)
• valid_actions_for_status() — media buy state machine mapped to spec's pending_activation, active, paused statuses
• resolve_account() with AccountError — handles not-found, suspended, payment-required, ambiguous accounts
• inject_context() — context passthrough with size limits (security)
• cancel_media_buy_response() — auto-sets canceled_at, status, valid_actions

Decorator Server Builder

• adcp_server() factory with auto-capabilities detection from registered handlers
• ValueError on unknown task names (catches typos at registration time)
• serve() accepts both ADCPHandler and ADCPServerBuilder

Type Safety

• Type guards: is_adcp_success/is_adcp_error + 15 typed TypeGuard functions
• Typed handler params: all 52 ADCPHandler methods accept RequestType | dict[str, Any]
• Response builders auto-populate valid_actions, revision, confirmed_at from status

New Domains

• Collection lists: 5 CRUD tasks (handler, MCP tools, types, response builders)
• Schema sync to latest: 434 schemas including async response variants
• TASK_FEATURE_MAP: 48 tasks across 12 domains

Error Handling

• ADCPTaskError with is_retryable (checks error codes for transient classification)
• ADCPSimpleAPIError preserves structured errors
• Plain text suggestions (emoji removed)

Documentation

• llms.txt — agent-facing quick reference
• AGENTS.md — structured handler/builder/error code tables with DX helper examples
• Updated skills with adcp_error(), proposal workflow, update_media_buy, account resolution

Security

• adcp_error() details parameter typed to prevent raw request param reflection
• inject_context() enforces 64KB size limit on context passthrough
• serve() docstring documents auth requirement for production
• Builder raises ValueError (not warning) for unknown task names

Test plan

• 1149 tests passing, 0 failures (68 new tests)
• Lint clean on all new/modified files
• Smoke test: end-to-end server framework (builder -> handler -> response)
• Skill validation: agents can follow seller/signals skills to build working agents
• Code review: all must-fix items addressed
• Security review: all must-fix items addressed
• DX expert review: all P0s fixed
• Ad tech expert review: error codes and state machine aligned to spec
• Python expert review: is_retryable, docstring ordering, deferred imports fixed

🤖 Generated with Claude Code

[bokelley]

Review from the Prebid Sales Agent team

We're the largest AdCP server implementation in Python — 16 AdCP tools across MCP + A2A transports, multi-tenant with adapter abstraction (GAM, mock, Xandr). This PR directly affects our adoption path. Sharing feedback both as consumers and as a reference for what real server DX looks like.

Overall: this is a great direction. The helpers, type guards, and builder are all things we've had to build ourselves. Excited to see them in the SDK. Below is concrete feedback on what would make adoption smoother.

---

1. Promote generated_poc types to stable API (blocking for us)

We have 60+ imports from adcp.types.generated_poc.* — ContextObject, CreativeAsset, MediaBuyStatus, PaginationRequest, PaginationResponse, AccountReference, TargetingOverlay, BrandReference, etc. These are not edge cases; they're the core types any real server needs.

The 434-schema sync in this PR could break all of them silently. We need these importable from adcp.types without reaching into generated internals. Without stable paths, every schema sync is a potential breaking change for consumers.

Ask: promote commonly-used types to adcp.types.* before this ships. At minimum: ContextObject, CreativeAsset, MediaBuyStatus, PaginationRequest, PaginationResponse, TargetingOverlay, BrandReference, AccountReference, CreativeAction, FormatCategory, AssetContentType.

---

2. Error handling: our approach is stronger for servers — can the SDK meet us halfway?

We built a typed exception hierarchy (src/core/exceptions.py) with 16 exception classes, each carrying error_code, status_code, and recovery (transient/correctable/terminal). This is better for servers than adcp_error() returning dicts because:

• Exceptions flow naturally through Python's transport boundaries
• Structural guards enforce that _impl functions raise AdCPError, never ToolError
• Type checkers catch misuse at definition time
• Transport layers (MCP, A2A) each have a single translator that maps the hierarchy to their protocol's error format

What we'd adopt from this PR: the 32 standard error codes. We currently cover 14/32 — missing codes like STATUS_TRANSITION_INVALID, REVISION_CONFLICT, CREATIVE_REJECTED, CREATIVE_POLICY_VIOLATION, IDEMPOTENCY_CONFLICT, UPSTREAM_TIMEOUT, etc.

Ask: publish the 32 standard error codes as a Literal union or Enum, not just a dict in helpers.py. Something like:

from adcp.types import AdCPErrorCode  # Literal["VALIDATION_ERROR", "AUTH_TOKEN_INVALID", ...]

class AdCPError(Exception):
    error_code: AdCPErrorCode  # type-checked at definition time

This lets servers validate their error codes against the spec at import time. The dict-of-dicts in STANDARD_ERROR_CODES is useful for adcp_error() but not for servers that build their own exception hierarchy.

Also: the recovery classification (transient/correctable/terminal) auto-derived from error codes is smart. Consider exporting TRANSIENT_CODES, CORRECTABLE_CODES, TERMINAL_CODES as sets so servers can stay aligned without duplicating the classification logic.

---

3. valid_actions_for_status() — we need this, but as typed data

We have zero valid_actions logic today — this is a gap. We'd adopt this immediately. But:

• What's the return type? list[str]? If so, what's the canonical action vocabulary? These should be a Literal union or enum in adcp.types, not just strings.
• The state machine mapping (status → valid actions) is spec-level data. It should be importable as a constant dict, not only accessible through a helper function. Servers need to inspect it, test against it, and potentially extend it.

Ask: export MEDIA_BUY_STATE_MACHINE: dict[MediaBuyStatus, list[MediaBuyAction]] as a public constant alongside the helper function.

---

4. A2A server DX — the biggest pain point you could solve

Our A2A server (adcp_a2a_server.py, ~2300 lines) has significant boilerplate that the SDK could eliminate:

a) Handler routing boilerplate. Every handler follows the same pattern: validate params via Pydantic model → resolve identity → call _impl → serialize response. We have 16 of these. The builder pattern in this PR is close but oriented toward ADCPHandler subclasses. For servers using the _impl pattern (transport-agnostic business logic + thin wrappers), a decorator that auto-routes would be transformative:

@adcp_handler("create_media_buy", CreateMediaBuyRequest)
async def handle_create(req: CreateMediaBuyRequest, identity: ResolvedIdentity):
    return await _create_media_buy_impl(req, identity=identity)

b) Error translation duplication. We have the same AdCPError → protocol error translation in both our MCP layer and A2A layer, implemented separately. The SDK could provide translate_error(exc, protocol="a2a"|"mcp") to centralize this.

c) Serialization inconsistency. Our handlers return a mix of Pydantic models and raw dicts (especially for error paths). A consistent contract — "handlers always return BaseModel, framework handles serialization" — would eliminate a class of bugs.

d) Request normalization. We built request_compat.py to handle field renames across AdCP versions (account_id → account: {account_id}, campaign_ref → buyer_campaign_ref, promoted_offerings → catalogs, etc.). This is spec-level knowledge that should live in the SDK, not in every server. Consider a normalize_request(task_name, params, client_version) helper.

---

5. TASK_FEATURE_MAP — great, needs one thing

The expansion from 2 → 48 tasks is exactly what we need for capabilities reporting. We currently build capabilities dynamically from adapter config. build_synthetic_capabilities() could replace a lot of that.

Ask: make the map bidirectional — given a capability, which tasks require it? We need this for feature-gating: "tenant doesn't have creative management enabled → hide sync_creatives from capabilities."

---

6. Type guards — easy win, will adopt

is_adcp_success() / is_adcp_error() are useful. The 15 typed guards are even better. No feedback — these are clean.

---

7. inject_context() 64KB limit

Is this configurable? We pass context objects for various operations and 64KB is probably fine today, but a hard-coded limit with no escape hatch will eventually bite someone. At minimum, document what happens at the boundary (truncate? raise?).

---

8. Collection lists

New domain, we'll track it. No urgency for us but good to see the coverage expanding.

---

9. Schema sync changelog

434 schemas changed. What fields were removed/renamed? A BREAKING_CHANGES.md or at least a summary of removed fields per schema would save every consumer hours of debugging at upgrade time. This is especially important given the generated_poc stability question above.

---

Summary of asks (priority order):

1. Stable import paths for commonly-used generated_poc types
2. Error code enum/literal for type-safe server error hierarchies
3. Recovery classification sets exported as constants
4. Valid actions state machine as public constant + typed action vocabulary
5. Request normalization helper for cross-version field renames
6. Error translation helper for multi-transport servers
7. Schema sync changelog for breaking field changes
8. TASK_FEATURE_MAP bidirectional lookup
9. inject_context limit configurability or documentation

Happy to pair on any of these — we have a battle-tested server implementation that could serve as a reference for DX design decisions.

[bokelley]

Response to salesagent team review

Thanks for the thorough review. Here's what we've addressed and what's tracked as follow-ups.

Fixed in this PR

Ask	Status
Stable import for PaginationResponse	Added to adcp.types
Recovery classification sets	Exported TRANSIENT_CODES, CORRECTABLE_CODES, TERMINAL_CODES as frozenset[str] from adcp.server
State machine as public constant	Renamed to MEDIA_BUY_STATE_MACHINE and exported from adcp.server
TASK_FEATURE_MAP bidirectional	FEATURE_HANDLER_MAP (feature → tasks) already existed, now documented
inject_context limit	Already configurable via max_size kwarg; drops oversized context silently (documented)
Single source of truth for transient codes	ADCPTaskError.is_retryable now imports from TRANSIENT_CODES instead of hardcoding

Regarding stable import paths

9/11 of your requested types are already in adcp.types — ContextObject, CreativeAsset, MediaBuyStatus, PaginationRequest, PaginationResponse (just added), AccountReference, TargetingOverlay, BrandReference, CreativeAction, AssetContentType. FormatCategory was removed from the spec in RC3.

Filed as follow-up issues

Issue	Description
#175	A2A server support — serve(handler, transport="a2a")
adcontextprotocol/adcp-client#549	Storyboard A2A testing parity
#176	Error translation + request normalization helpers for multi-transport servers

On error code enum vs dict

Good point about type-safe error codes. The ErrorCode enum is already generated from the spec in adcp.types.ErrorCode. The STANDARD_ERROR_CODES dict in helpers adds recovery classification on top. We'll consider a TypedDict or typed wrapper in a follow-up.

On A2A server DX

This is the biggest gap. Your A2A server is ~2300 lines of boilerplate the SDK should eliminate. #175 tracks this. Your implementation would be a valuable reference for the design.