Problem
The supervisor client surface is currently split across regular HTTP endpoints plus an SSE event stream. That makes clients more complicated than they need to be:
- multiple connection types to manage
- separate request and event plumbing
- reconnect/state recovery complexity spread across HTTP and SSE
- harder generation of a single typed client contract
Request
Move the supervisor client transport to a single long-lived WebSocket connection per client.
The socket protocol should carry:
- request/response style operations for supervisor commands and queries
- server-pushed events and state updates
- correlation identifiers for in-flight client requests
- explicit reconnect / replay semantics where needed
Why
A single WebSocket transport would:
- simplify supervisor client implementations
- eliminate the current split between HTTP calls and SSE subscriptions
- provide one place for auth, reconnect, backpressure, and observability
- make the client protocol easier to describe as a single async contract
Contract / Codegen Direction
If the supervisor moves to a single async WebSocket protocol, AsyncAPI is the right contract format for that transport:
https://www.asyncapi.com/en
For code generation, prefer an OSS toolchain built around AsyncAPI + Modelina:
- AsyncAPI for the WebSocket protocol contract
- Modelina for generating DTOs / payload models in the client languages we care about
- hand-written transport/runtime logic on top of that contract where needed
This keeps the protocol description open and portable without introducing vendor account/token coupling into the core toolchain.
Explicit Non-Goal
Do not depend on Fern for this transport layer.
Reason: even though Fern supports OpenAPI and AsyncAPI, its workflow introduces vendor-managed accounts/tokens and product coupling that we do not want in the supervisor transport stack.
Related
Problem
The supervisor client surface is currently split across regular HTTP endpoints plus an SSE event stream. That makes clients more complicated than they need to be:
Request
Move the supervisor client transport to a single long-lived WebSocket connection per client.
The socket protocol should carry:
Why
A single WebSocket transport would:
Contract / Codegen Direction
If the supervisor moves to a single async WebSocket protocol, AsyncAPI is the right contract format for that transport:
https://www.asyncapi.com/en
For code generation, prefer an OSS toolchain built around AsyncAPI + Modelina:
This keeps the protocol description open and portable without introducing vendor account/token coupling into the core toolchain.
Explicit Non-Goal
Do not depend on Fern for this transport layer.
Reason: even though Fern supports OpenAPI and AsyncAPI, its workflow introduces vendor-managed accounts/tokens and product coupling that we do not want in the supervisor transport stack.
Related