feat(server): /.well-known/adcp-agents.json discovery endpoint (PR adcp#3903)

[bokelley]

Context

AdCP PR #3903 / commit 5c3e3e626 in the spec adds a /.well-known/adcp-agents.json discovery doc for multi-agent topology. Sellers should serve it; buyers should be able to discover it.

The schema lives at static/schemas/source/adcp-agents.json in adcontextprotocol/adcp.

Refs:

• src/adcp/server/serve.py
• adcontextprotocol/adcp PR #3903

Acceptance Criteria

• Server-side: serve() exposes /.well-known/adcp-agents.json for transport="streamable-http", transport="a2a", and transport="both"
• Document is generated from the platform's declared agents/capabilities — not a static file
• Validates against the upstream adcp-agents.json schema in CI
• Client-side helper to fetch + parse a remote discovery doc
• Smoke test hits the endpoint on each transport mode and asserts the response validates

[bokelley]

Triage complete — PR opened

Classification: non-breaking feature addition
Bucket: execute-pr (non-breaking, experts converge, clear scope)

Expert sign-offs

Protocol expert confirmed:

• cache-control: no-cache is the correct directive for capability documents (not no-store)
• Auth bypass scope (GET /.well-known/*) is spec-aligned
• Document shape { adcp_version, agents: [{ name, capabilities }] } matches AdCP PR #3903 prose

Code reviewer flagged and resolved:

• SSRF: fetch_adcp_agents now validates scheme (http/https only) and rejects private/reserved IPs and localhost before any network call
• Shadow import: removed urlparse as _urlparse inside function body; uses module-level urlparse
• Timeout namespace: raises AdcpAgentsTimeoutError (not AdagentsTimeoutError) in timeout path
• Duplicate code: extracted _send_adcp_agents_response() helper used by both transport paths

What shipped

• /.well-known/adcp-agents.json endpoint on streamable-http, a2a, and both transports
• BearerTokenAuthMiddleware exempts GET /.well-known/* before reading the body
• fetch_adcp_agents(agent_base_url) client helper with SSRF protection
• AdcpAgentsValidationError, AdcpAgentsNotFoundError, AdcpAgentsTimeoutError exported from adcp
• 19 smoke tests; public API snapshot updated

Draft PR: #404
Note: CI schema validation against the upstream adcp-agents.json schema is deferred until the schema artifact from AdCP PR #3903 is available via sync_schemas.py.

---

Generated by Claude Code