Application-managed WebSocket sessions for extension-owned protocols

[franciscojavierarceo]

Summary

Praxis needs an opt-in way for a trusted extension to own a validated WebSocket session at the level of complete application messages. The immediate need is to let PraxisAI hydrate the response.create messages that Codex sends over the Responses WebSocket before those requests reach OpenAI or vLLM.

Today, Praxis can accept a WebSocket upgrade and forward the resulting connection as a transparent byte tunnel. That is the right behavior when both sides speak the same application protocol, but it prevents an extension from receiving a complete message, performing asynchronous work, replacing or suppressing that message, initiating an independent upstream exchange, or producing downstream messages itself.

Concrete motivation

Current Codex reuses a persistent Responses WebSocket and, for eligible follow-up requests, sends only the new input while identifying the preceding response with previous_response_id. Codex can fall back to HTTP and remain functional, but current Codex only uses this incremental previous_response_id exchange in its Responses WebSocket path.

The upstream transport is not always the same:

• OpenAI's SaaS Responses API offers a native WebSocket upstream.
• vLLM currently offers the Responses API over HTTP, with SSE for streaming.

PraxisAI should be able to accept the same downstream Codex WebSocket, hydrate and validate each logical Responses request, and then either mediate a native upstream WebSocket or bridge the operation to HTTP/SSE. Requiring Codex to use its HTTP fallback discards its incremental WebSocket behavior. Requiring every backend to implement WebSockets makes backend transport an unnecessary gateway prerequisite.

Passive observation is not sufficient. A read-only observer could extract metadata, but it could not hydrate a request, replace a message, wait for an external lookup, suppress forwarding, initiate vLLM's HTTP exchange, or synthesize downstream Responses events. Raw upgraded-body chunks are also not complete WebSocket message boundaries.

Desired outcome

Praxis core would provide a provider-neutral, opt-in application-managed WebSocket capability that:

• is selected through trusted configuration before the upgrade completes;
• gives extensions asynchronous, bidirectional access to complete text and binary messages;
• supports multiple logical operations over one persistent connection;
• keeps framing, control messages, close behavior, cancellation, backpressure, timeouts, and resource limits under framework control;
• preserves authenticated identity, tenant, authorization policy, and immutable connection context for the session;
• exposes lifecycle and failure signals for diagnostics; and
• leaves the existing transparent WebSocket fast path unchanged for routes that do not opt in.

Provider-specific Responses decoding, hydration, persistence, token accounting, and OpenAI/vLLM adapters would remain outside Praxis core.

Non-goals

This is not a proposal to make Praxis a general-purpose forward proxy, intercept arbitrary TLS traffic, persist raw WebSocket content, or require all WebSocket routes to use application management.

Sign-off requested

Do maintainers agree that this problem belongs in Praxis core and that an application-managed WebSocket extension boundary is the appropriate capability to take into an EPIC and proposal PR?

[shaneutt]

I agree that application-managed websockets makes sense given the scope of our project, and adding that to core in particular is the right place. Please feel free to start an initial proposal and reference this discussion.

As for the non-goals: I feel like those non-goals are actually on shaky ground. I think it's fine to claim that we don't want to do some of these in the proposal, but I would phrase it as "not in this iteration" as opposed to never.

cc @leseb