feat(api): type the HTTP wire from AG-UI and the read routes from their shapes

[ciaransweet]

The generated OpenAPI described four of the five routes as a bare
object, additionalProperties: true, messages on POST /runs as a list of
untyped dicts, and the SSE stream as application/json — which is the one thing
a turn never is. A consumer could not write a client from it.

What the document says now

route	before	after
POST /runs request	list[dict]	RunRequest → ag_ui.core.Message, all seven roles
POST /runs response	application/json {}	text/event-stream, oneOf of all 33 AG-UI events, discriminated on type
GET /threads/{id}	object	ThreadResponse (messages typed as Message too)
GET /threads/{id}/turns	object	TurnsResponse → TurnInfo
GET /threads/{id}/state/{key}	object	StateValueResponse
GET /views/{toolset}/{view}	text/html string	unchanged; already honest

8 component schemas → 65.

The AG-UI types come from AG-UI

ag-ui-protocol is already the [api] extra's dependency and exports both
unions, so nothing is re-described by hand and none of it can drift from the
protocol. Message includes the activity and reasoning roles, which is what
makes typing the request safe: a client echoing back a history containing the
activity messages this server emitted still validates.

Our own four models — ThreadResponse, TurnsResponse, TurnInfo,
StateValueResponse and the StateEntryInfo three of them share — are exported
from mcp_agent_api, so a Python client validates against them instead of
re-declaring the shapes.

Three mechanics worth reviewing, all established by testing

Passing the Event union as the response model is what registers the event
schemas into components. Without it the oneOf's $refs dangle and Swagger
renders nothing. Inlining the schema instead would have looked correct in the
source and been broken in the browser, because #/$defs/... resolves against the
document root rather than the enclosing schema. There is a test asserting every
referenced branch is defined.

A StreamingResponse subclass naming media_type is what keeps the default
application/json out. Passing the model without it documented both media
types. The handler builds its own response, so this only affects the document.

The read models are attached through responses=, not response_model=, so
nothing is re-serialised. Two nullable fields need opposite treatment:
state_metadata omits seq until the write is merged, so a client ordering by
it is never sorting nulls, while kind: null is meaningful — the value is
untyped — and must stay. A plain response_model turns the first into
"seq": null; response_model_exclude_none drops the second; a
@model_serializer fixes the wire and then erases the schema, which is the whole
point of the change. A test pins both halves after a real turn.

One behaviour change

A posted message without an id now gets a 422. The protocol requires one,
so using its models enforces it. Any string does — a fresh uuid per message is
the obvious choice — and nothing here reads it: history is the server's, only the
trailing user message's text is taken, and the id a client posts is discarded
rather than stored. Documented in CONSUMING.md and on RunRequest, including
the awkward part: we require a field we then throw away, because the protocol
says so and claiming conformance while accepting what it forbids helps nobody.

338 tests pass, lint clean.

Raised from

Reviewing the Swagger page of the dss deployment now serving this API. Its
/health is dss's own route and gets the same treatment separately, in the PR
that bumps its lock.

🤖 Generated with Claude Code