feat(testing): forward pre_validation_hooks through build_asgi_app (follow-up to #626)

[bokelley]

Problem (follow-up to #626)

adcp.testing.build_asgi_app (PR #626) is the public test-harness builder we adopted in salesagent (replacing private _build_mcp_and_a2a_app / _apply_asgi_middleware imports). It accepts every production serve() kwarg we needed — auth, asgi_middleware, context_factory, streaming_responses, allowed_hosts/origins, validation, etc. — but not pre_validation_hooks.

Effect on adopters: in-process HTTP-shaped tests driven via httpx.ASGITransport(app=build_asgi_app(...)) get a different validation surface than production. Pre-v3 buyer payloads (buying_mode omitted, bare-string format_id, missing asset_type) that production auto-defaults via serve(pre_validation_hooks=...) are rejected by build_asgi_app-driven tests. Tests pass on payloads that would have been coerced in prod; tests fail on payloads that prod accepts.

We hit this during salesagent's 5.0 migration. Our code reviewer flagged it as IMPORTANT: "Pre-v3 buyer shapes that production would auto-default to will not be auto-defaulted in tests. This means in-process HTTP-shaped tests can pass while production fails on the same payload, or vice versa."

Concrete divergence

# Production:
serve(
    router,
    pre_validation_hooks={"get_products": apply_buying_mode_default},
    ...
)
# Buyer payload {"brand": ...} (no buying_mode) → coerced to {"brand": ..., "buying_mode": "brief"} → validates.

# Test:
app = build_asgi_app(router, ...)
# Same payload → ValidationError: "buying_mode" field required.

Tests can't reach the production code path without re-implementing the coercion in test setup — which defeats the point of testing the production wiring.

Proposed fix

Add pre_validation_hooks to build_asgi_app's signature, forwarded the same way serve() forwards it to create_adcp_server_from_platform or the underlying MCP server builder:

def build_asgi_app(
    platform: DecisioningPlatform,
    *,
    name: str = ...,
    # ... existing kwargs ...
    pre_validation_hooks: dict[str, Callable[[str, dict[str, Any]], dict[str, Any]]] | None = None,
    factory_kwargs: ...,
) -> Any: ...

Symmetric with serve(). Forwards to whatever internal path serve() uses to install the hooks pre-dispatcher.

Why this matters

This is the second adopter friction point on build_asgi_app since 5.0 (the first was the #618 pre-existing gap that the PR addressed). Every kwarg serve() accepts that build_asgi_app doesn't accept is a place adopters either (a) lose production fidelity in tests, or (b) re-implement plumbing on the test side.

For salesagent, the workaround for now is documenting in build_app()'s docstring that pre-v3 wire fidelity is not preserved in in-process tests — adopters who need pre-v3-shape testing must use the production serve() path or pre-shape payloads themselves. Worth fixing properly upstream.

Files

• Our build_app(): bokelley/salesagent core/main.py — search for build_asgi_app. Currently drops pre_validation_hooks with a comment justifying the divergence; that comment can be removed once this lands.

Related

• feat(testing): extend build_asgi_app with full serve-layer kwargs #626 (closed) — shipped the public build_asgi_app. This is a per-kwarg gap, not a regression.
• feat(server): pre-validation request hook for spec-default injection (#614) #629 — the pre_validation_hooks mechanism this would forward.
• Our composition issue #645 (TenantRegistry → serve adapter) and feat(a2a): per-request agent-card URL resolution (follow-up to #616) #647 (per-request public_url) — same pattern of "SDK shipped the production primitive, but the test/composition surface lags."

[bokelley]

Triage

Classification: Feature request (API gap — missing kwarg forwarding)
Bucket(s): handlers (testing surface for DecisioningPlatform-based servers)
Status: drafting-pr
Milestone: (omitted — no target version specified)

What the experts said:

• dx-expert: approved — param belongs on create_mcp_server call, not create_adcp_server_from_platform; build_test_client must mirror to close the gap symmetrically; use dict[str, Callable[..., Any]] to match the rest of the codebase
• code-reviewer: approved — forwarding is correct and thread-safe; Callable under TYPE_CHECKING is safe given from __future__ import annotations

My take: create_mcp_server already accepts pre_validation_hooks — this is a pure forwarding gap, non-breaking (optional param with None default), and exactly symmetric with every other kwarg build_asgi_app exposes. Drafted PR immediately.

PR summary: Add pre_validation_hooks: dict[str, Callable[..., Any]] | None = None to build_asgi_app and build_test_client, forwarded to the existing create_mcp_server call. 4318 tests pass.

Draft PR: #655

---

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

---

Generated by Claude Code