feat(server): pre-validation request hook / spec-default registry

[bokelley]

Problem

Some 4.4+ schemas mark fields as required at the wire level even though the spec instructs sellers to apply a default for missing values from pre-v3 clients. Examples:

• GetProductsRequest.buying_mode — spec text: "Sellers receiving requests from pre-v3 clients without buying_mode SHOULD default to 'brief'."
• account and idempotency_key on tools where the seller resolves identity from the auth chain (we backfill account_id="auth-chain" and idem-{uuid4} placeholders so strict validation passes; the impl ignores them)
• format_id shape: 4.4 made it a structured {agent_url, id} reference; pre-4.4 buyers send a bare string
• assets[].asset_type on sync_creatives — buyers send {"image": {...}} without asset_type, which makes the discriminated union unable to pick a branch
• Image asset variant strictly requires width/height; pre-4.4 buyers often send image URLs without dims (we demote image → url)

The typed dispatcher validates payloads against the library Pydantic models before the platform handler runs, so a per-handler model_validator cannot apply spec-mandated defaults in time.

Workaround (the most advanced Python adopter)

We ship a 273-LOC ASGI middleware (SpecDefaultsMiddleware) that bytes-rewrites JSON-RPC tools/call bodies and the matching A2A skill payloads, applying defaults in-place before the SDK validator runs. It works, but:

1. Every adopter who hits AdCP 4.4+ strictness needs the same set of defaults.
2. The middleware sits outside the SDK's validation boundary by definition.
3. Bytes-level body rewriting is brittle — adding a new defaulted field means another hand-rolled patcher.

Proposed SDK shape

Either of:

A) Pre-validation request hook (per-tool or global):

serve(
    router,
    pre_validation_hooks={
        "get_products": lambda args: {**args, "buying_mode": args.get("buying_mode", "brief")},
        # or global hook receiving (tool_name, args)
    },
)

B) Declarative spec-default registry:

from adcp.server import SpecDefaults

serve(
    router,
    spec_defaults=SpecDefaults(
        get_products={"buying_mode": "brief"},
        sync_creatives={"asset_type_inference": True, "format_id_normalize": True},
    ),
)

Either approach kills our 273-LOC middleware and gives every Python adopter the same spec-conformant defaulting behaviour.

Files

• Our workaround: core/middleware/spec_defaults.py
• Per-spec-text justification for each default is in the module docstring + per-rule comments.

[bokelley]

Triage result: implemented — draft PR opened.

Bucket: server-handlers (Option A — callable dict chosen over declarative SpecDefaults because 3 of 5 use cases in the issue require structural transforms that a declarative approach cannot handle)

Draft PR: #629

What the PR adds:
pre_validation_hooks: dict[str, Callable[[str, dict], dict]] | None on all public entry points (serve(), create_mcp_server(), create_a2a_server(), MCPToolSet, create_tool_caller()). The hook runs on the raw wire dict before JSON schema validation and Pydantic model_validate — exactly the insertion point needed to apply spec-mandated defaults for pre-v3 buyers.

Your workaround middleware becomes:

serve(
    router,
    pre_validation_hooks={
        "get_products": lambda n, a: {**a, "buying_mode": a.get("buying_mode", "brief")},
    },
)

Key invariants enforced:

• None default → zero overhead on hot path
• Hook exceptions → INVALID_REQUEST (never INTERNAL_ERROR)
• Context-echo contract preserved: raw_params snapshotted before hook runs, so server-injected defaults are not echoed back to the buyer as if they sent them

CI: 4161 tests pass, mypy clean (783 files), ruff clean.

---

Opened by triage automation · label: claude-triaged

---

Generated by Claude Code