feat(a2a): per-request agent-card URL resolution via callable public_url

[bokelley]

Summary

Closes #647

• Adds PublicUrlResolver = Callable[[Any], str] type alias exported from adcp.server
• Widens create_a2a_server(public_url=…) and serve(public_url=…) / ServeConfig.public_url to accept a callable in addition to str | None — fully backwards-compatible
• When a callable is supplied, an ASGI middleware layer intercepts GET /.well-known/agent-card.json and GET /.well-known/agent.json per request, calls the resolver with the Starlette Request, validates the returned URL, and rebuilds the agent card on the fly — bypassing the a2a-sdk's build-time bake
• Both sync and async resolvers are supported (inspect.iscoroutine detection + await)
• Resolver errors and invalid URLs return {"error": "agent-card temporarily unavailable"} with HTTP 500 and a full traceback in the server log

Motivation

Multi-tenant subdomain deployments (acme.platform.io, beta.platform.io, …) share one server process. A static public_url can only name one host, so every tenant's agent card points at the same URL. The callable pattern puts host-resolution logic in adopter code (e.g. read the Host header) while keeping X-Forwarded-Host trust decisions out of the framework's unauthenticated agent-card endpoint.

Typical usage

from starlette.requests import Request
from adcp.server import serve, PublicUrlResolver

def agent_card_url(request: Request) -> str:
    host = request.headers.get("host", "localhost")
    return f"https://{host}/"

serve(handler, transport="a2a", public_url=agent_card_url)

Test plan

• tests/test_a2a_public_url_resolver.py — 15 tests: 6 unit (_validate_card_url) + 9 integration (per-request card, multi-host, 0.3 alias, error→500, invalid URL→500, async resolver, static/None unchanged, export check)
• ruff check src/ — all checks passed
• mypy src/adcp/ — no issues in 2 changed source files
• Pre-PR review: security-reviewer (no blockers — Option A / X-Forwarded-Host trust ruled out; Option B defers trust policy to adopter), dx-expert (0 blockers, 6 nits addressed), code-reviewer (2 blockers fixed: async support + test; 2 issues fixed: exc_info=True + brand names replaced)

---

Triage-managed PR — opened automatically by the issue-triage routine in response to issue #647. Review and merge as you would any other PR; the triage label on the issue will be updated when this PR lands.

https://claude.ai/code/session_01CTpSC8E52DSKTDFJx7Y4Gf

---

Generated by Claude Code