Feat: Carry Codex's Responses WebSocket and parse every turn on it

CLAUDE.md

@@ -706,12 +706,18 @@ Every event on `/v1/sessions/{id}` and `/v1/events` carries:
   disagree about the status on purpose. **A 426 with `error.kind:
   "upgrade_declined"` is not one of these:** it is the forward proxy refusing a
   WebSocket on OpenAI's Responses API (a path ending `/responses` on `chatgpt.com` or
-  `api.openai.com`) — a deliberate steer, since a 426 sends Codex straight to HTTPS
-  where its traffic stays parseable, while a forwarded WebSocket's frames are opaque
-  to every plugin. Nothing is forwarded, the Finisher sees an allow with
-  status 426, and `/v1/usage` does not count it as an error. On by default;
-  `listener.decline_responses_websockets: false` forwards the upgrade for real
-  instead. **Every other WebSocket is forwarded** (#1488): the upgrade crosses the
+  `api.openai.com`) that it will not carry. Nothing is forwarded, the Finisher sees an
+  allow with status 426, and `/v1/usage` does not count it as an error. It is what
+  `listener.responses_websockets: decline` does to every such socket, and what the
+  default, `parse`, does to one it cannot carry (not bridged, or a `WritesResponseBody`
+  or `WritesDestination` plugin in the chain; an HTTP/2 client is refused 400 by Go's
+  HTTP/2 server before the handler runs); a carried socket records instead a `GET`
+  open and close with `tunnelReason: "websocket"` and one ordinary `POST`
+  request/response pair per turn on it (`core/listener/forwardproxy/websocket.go`).
+  v0.9.4's `decline_responses_websockets` is still read when the new key is unset
+  (`true` = `decline`, `false` = `forward`), with a startup warning; both set is
+  refused. **Every other WebSocket is forwarded** (#1488), and so is a Responses one under
+  `forward`: the upgrade crosses the
   proxy (normalized to `Connection: Upgrade` / `Upgrade: websocket`, which net/http
   pins to HTTP/1.1 even on the bridge's h2-negotiating client), the origin's 101 is
   hijacked and spliced, and the session records the request row plus a paired 101
@@ -795,7 +801,7 @@ Every event on `/v1/sessions/{id}` and `/v1/events` carries:
 - `requestedHost` — present only when a plugin redirected the request (`pctx.Redirect`): the host the client asked for. `host` is where the request actually went, and usage, the cost ledger and pricing all follow `host`. agentop's detail pane shows both on a `redirected:` line.
 - `inference.requestedModel` — present only when a plugin changed the model (`pctx.SetRequestModel`): the model the client asked for. `inference.model` is the model the request was sent for, which settlement prices; agentop's detail pane shows both on a `model:` line.
 - `bytesUp`, `bytesDown` — **body** bytes, one direction per row: a request row carries `bytesUp`, the body **as forwarded** (so a `tool-prune`-style rewrite is reflected, since the count is taken after the pipeline ran), and a response row carries `bytesDown`, the body **as it came back from the destination** — not as delivered, because extproc records the row before it emits a response mutator's replacement. Headers are not counted. A tunnel close and a forwarded WebSocket's 101 response row are the rows carrying both. **Zero means the listener counted nothing, not that the body was empty**, and there is no third value for "unknown": every listener buffers bodies only when a plugin asks, so an unbuffered request reports zero. A response relayed straight through is counted, not zero — both proxies record the row after the copy (#1251's fix), so the bytes they relayed through their own process are on it. The one arm that still reports ↓0 is extproc with a body-free pipeline: it asked Envoy for body mode NONE, so the bytes it never saw are bytes it asked not to see — `core/listener/parity`'s `TestDivergence_InboundResponseBodyCountWhenNoPluginReadsIt` pins that disagreement with its reason. agentop renders a zero side blank rather than as `0B`, and that is why its BYTES column can be trusted as a size when it shows one. Everywhere else the three listeners count the same thing for the same response, which took some doing: extproc sums the chunks Envoy hands it, while the proxies count off the upstream body at one choke point each, so every arm — buffered, block-by-block SSE, or chunk copy — reports the same figure. `core/listener/internal/bodycount` and `core/listener/parity`'s bytes fixtures hold that line.
-- `tunnel`, `tunnelReason` — an opaque CONNECT (or transparent-redirect) tunnel records two rows sharing a `requestId`: the open (`phase: "request"`, `tunnelReason` saying why the bytes stayed opaque) and, when the tunnel ends, the close (`phase: "response"`). The close carries the CONNECT's own `statusCode` — 200, or 502 with the dial error in `error` when the destination could not be reached and no TLS bridge could take the connection (`tunnelReason: "dial-failed"`; where the bridge is enabled for the port the CONNECT is answered 200 first, because a redirect can still apply, and a bridge that then declines closes with that 200 and the dial error) — plus `durationMs` for how long the tunnel stayed open and, in `bytesUp`/`bytesDown`, the bytes it carried each way (up = client to destination; opaque bytes have no body/header split, so these are everything that crossed). It is not the destination's status: that travels inside the client's end-to-end TLS. A bridged tunnel's open is recorded with its first decrypted request — in that request's session, directly before it, stamped with its time — and records no close, because the request carries its own response; a bridged tunnel that recorded no request gets its open and a close when it ends. Tunnel rows are kept out of `/v1/usage`: a tunnel's lifetime is not a request latency. `tunnelReason: "dest-private"` with a 403 close and `error.kind: "destination_private"` is the egress guard refusing the destination before any dial — never confused with `dial-failed`, which attempted.
+- `tunnel`, `tunnelReason` — an opaque CONNECT (or transparent-redirect) tunnel records two rows sharing a `requestId`: the open (`phase: "request"`, `tunnelReason` saying why the bytes stayed opaque) and, when the tunnel ends, the close (`phase: "response"`). The close carries the CONNECT's own `statusCode` — 200, or 502 with the dial error in `error` when the destination could not be reached and no TLS bridge could take the connection (`tunnelReason: "dial-failed"`; where the bridge is enabled for the port the CONNECT is answered 200 first, because a redirect can still apply, and a bridge that then declines closes with that 200 and the dial error) — plus `durationMs` for how long the tunnel stayed open and, in `bytesUp`/`bytesDown`, the bytes it carried each way (up = client to destination; opaque bytes have no body/header split, so these are everything that crossed). It is not the destination's status: that travels inside the client's end-to-end TLS. A bridged tunnel's open is recorded with its first decrypted request — in that request's session, directly before it, stamped with its time — and records no close, because the request carries its own response; a bridged tunnel that recorded no request gets its open and a close when it ends. Tunnel rows are kept out of `/v1/usage`: a tunnel's lifetime is not a request latency. **`tunnelReason: "websocket"` is the one that is not opaque:** a Responses API WebSocket the forward proxy carries (`listener.responses_websockets`, `core/listener/forwardproxy/websocket.go`). Its open is the handshake `GET`, its close is status 101 with the whole socket's duration and bytes, and each turn on it records its own ordinary `POST` request/response pair between them, parsed and priced like an HTTPS turn. A turn runs on the pipeline it began on, so a hot reload never splits one. `tunnelReason: "dest-private"` with a 403 close and `error.kind: "destination_private"` is the egress guard refusing the destination before any dial — never confused with `dial-failed`, which attempted.
 - `dialAddr` — the address the egress guard checked and the proxy dialed, `"ip:port"`, on a tunnel's open row when `listener.egress_guard` is on. With `host` it is the audit trail against DNS rebinding: under the guard the proxy resolves once, checks that answer, and dials exactly it, so the two fields together say "asked for the name, reached this address". Absent when the guard is off and on rows that dialed nothing.
 - `httpMethod`, `httpPath` — the HTTP verb and path, so a request no parser recognized is still identifiable rather than showing only a host. Distinct from the `method` inside `a2a` / `mcp`, which is a protocol method name. On an opaque tunnel `httpMethod` is `CONNECT` and `httpPath` is absent — opaque bytes carry no request line. The path is query-stripped and percent-decoded, so query-borne credentials never reach the timeline, but a secret in a path *segment* (a bot token, a webhook path) does survive on this unauthenticated surface — worth knowing before exporting events off-box.
 - `subagent` — present on rows from a Claude Code subagent or agent-team teammate: the `X-Claude-Code-Agent-Id` the request carried. For a subagent that is also the `<id>` in `~/.claude/projects/<dir>/<session>/subagents/agent-<id>.meta.json`; for a teammate the join is unverified. Resolved by `Context.Subagent`, pinned with the User-Agent by `ResolveClient` so no plugin can re-file a row, and **refused rather than sanitised** when unusable (control runes, over 128 bytes), because it is a join key and a cleaned-up id joins nothing. It does not move the row: a subagent's requests stay in their parent's session, so the header must not be added to `session.id_headers`. **It names an agent, it does not classify the row:** `inference.agentRole` stays the field that says whether a row is a subagent's, and a teammate's row is `agentRole: main` with `subagent` set — Claude Code writes `cc_is_subagent=true` only for `agentType: subagent`.

cmd/agentop/tui/detail_pane.go

@@ -150,7 +150,7 @@ func redirectHeader(e *pipeline.SessionEvent) string {
 // user blames Cortex. Cortex must not forward Upgrade (RFC 9110 makes it hop-by-hop),
 // so the request either reaches the origin as a bare GET — which an endpoint wanting
 // a POST or an upgrade answers 405 — or, on a Responses API path, is answered 426 by
-// the proxy itself (listener.decline_responses_websockets). Codex falls back to
+// the proxy itself (listener.responses_websockets). Codex falls back to
 // HTTPS after either.
 //
 // The wording holds for both because this line is drawn from the REQUEST row, which

cmd/cortex/main.go

@@ -1084,10 +1084,10 @@ func main() {
 		}
 		fpSrv.TLSBridge = bridge
 		fpSrv.Shared = sharedStore
-		// A Responses API WebSocket is answered 426 so Codex falls back to HTTPS at once,
-		// rather than after ~6s of retrying the origin's 405. On unless
-		// listener.decline_responses_websockets: false.
-		fpSrv.DeclineResponsesWebSockets = cfg.Listener.DeclinesResponsesWebSockets()
+		// A Responses API WebSocket — Codex's transport — is carried and parsed turn by
+		// turn by default; listener.responses_websockets: decline answers it 426 so Codex
+		// uses HTTPS at once, and forward restores the stripped GET.
+		fpSrv.ResponsesWebSockets = cfg.Listener.ResponsesWebSocketsMode()
 		// Per-session bucketing. Without it every coding-agent session on the
 		// machine records into one shared bucket: two Claude Code windows
 		// interleave and per-session cost cannot be computed at all. Defaults to

core/config/config.go

@@ -990,6 +990,13 @@ type ListenerConfig struct {
 	// in #496.
 	SkipHosts []string `yaml:"skip_hosts" json:"skip_hosts"`
 
+	// ResponsesWebSockets is what the forward proxy does with a WebSocket upgrade on
+	// an OpenAI Responses API path (a GET with Upgrade: websocket on a path ending
+	// /responses — Codex's transport): one of the ResponsesWebSockets* values below.
+	// Empty means the default, ResponsesWebSocketsParse. See
+	// ResponsesWebSocketsMode.
+	ResponsesWebSockets string `yaml:"responses_websockets,omitempty" json:"responses_websockets,omitempty"`
+
 	// EgressAllowHosts is the forward proxy's deny-by-default destination
 	// allow list (#1483, MOCA MI1 §8.5): when non-empty, an outbound
 	// destination not on the list is refused with 403 destination_denied
@@ -1043,14 +1050,13 @@ type ListenerConfig struct {
 	// listener knob.
 	EgressAllowHosts []string `yaml:"egress_allow_hosts,omitempty" json:"egress_allow_hosts,omitempty"`
 
-	// DeclineResponsesWebSockets: whether the forward proxy answers a WebSocket
-	// upgrade on an OpenAI Responses API path (one ending /responses, on chatgpt.com
-	// or api.openai.com) with 426 itself, instead of forwarding the upgrade. nil
-	// means unset, and the default is on; explicit false forwards it. See
-	// DeclinesResponsesWebSockets for why on is the default.
+	// DeclineResponsesWebSockets is the boolean responses_websockets replaced. v0.9.4
+	// shipped it, so a config that sets it keeps working: when responses_websockets is
+	// unset, true reads as decline and false as forward — under #1488 a forwarded
+	// upgrade is a real one, which is what false asked for — and Validate warns,
+	// naming the new key. Setting both is refused, since they can disagree.
 	//
-	// A pointer for the reason SessionConfig.Enabled is one: with a plain bool,
-	// "unset" and "false" are the same value, and the default could not be on.
+	// Deprecated: use ResponsesWebSockets.
 	DeclineResponsesWebSockets *bool `yaml:"decline_responses_websockets,omitempty" json:"decline_responses_websockets,omitempty"`
 
 	// EgressGuard arms the SSRF dial guard on the forward proxy's every
@@ -1078,7 +1084,7 @@ type ListenerConfig struct {
 	// protect.
 	//
 	// A pointer so "absent" (off) stays distinguishable from an explicit
-	// enabled: false, mirroring DeclineResponsesWebSockets. Listener.* field:
+	// enabled: false, as SessionConfig.Enabled is. Listener.* field:
 	// changing it requires a restart, like every other listener knob.
 	EgressGuard *EgressGuardConfig `yaml:"egress_guard,omitempty" json:"egress_guard,omitempty"`
 }
@@ -1097,19 +1103,47 @@ type EgressGuardConfig struct {
 	PermitCIDRs []string `yaml:"permit_cidrs,omitempty" json:"permit_cidrs,omitempty"`
 }
 
-// DeclinesResponsesWebSockets reports whether the forward proxy answers a WebSocket
-// upgrade on a Responses API path with 426 rather than forwarding it.
+// Valid ListenerConfig.ResponsesWebSockets values.
+const (
+	// ResponsesWebSocketsParse carries the WebSocket and parses every turn on it the
+	// way an HTTPS Responses request is parsed. Where the proxy cannot do that — the
+	// request was not decrypted, or a plugin rewrites response bodies or redirects
+	// requests — it falls back to ResponsesWebSocketsDecline for that socket.
+	ResponsesWebSocketsParse = "parse"
+	// ResponsesWebSocketsDecline answers the upgrade with 426 Upgrade Required and
+	// contacts no origin; Codex reads that as "use HTTPS" and switches at once.
+	ResponsesWebSocketsDecline = "decline"
+	// ResponsesWebSocketsForward forwards the upgrade and splices the origin's 101, as
+	// the proxy does for every other WebSocket (#1488). The socket works, but its
+	// frames are opaque: no turn is parsed, priced or recorded, only the handshake's
+	// request row and a 101 row when the socket ends.
+	ResponsesWebSocketsForward = "forward"
+)
+
+// ResponsesWebSocketsMode is ListenerConfig.ResponsesWebSockets with the default
+// applied: parse, in every deployment.
 //
-// On unless set false, in every deployment. The proxy CAN forward a WebSocket (it
-// does for every other host, #1488), but a Responses session on one is opaque to
-// every parser — no token counts, no cost — so the 426 keeps Codex on HTTPS where
-// its traffic stays observable. That, and history: before forwarding existed the
-// stripped handshake drew a 405 that Codex retried for about six seconds before
-// falling back to HTTPS, while it reads a 426 as "use HTTP" and falls back at once.
-// False is the escape hatch for a client that reads 426 some other way — or wants
-// the WebSocket for real.
-func (l ListenerConfig) DeclinesResponsesWebSockets() bool {
-	return l.DeclineResponsesWebSockets == nil || *l.DeclineResponsesWebSockets
+// Parse is the default because it is the transport Codex asks for and the one it
+// performs best on: one socket for a whole session, with later turns sending only new
+// input instead of the whole conversation. Every turn on it is still parsed — model,
+// tokens, cost, tool calls — so carrying it costs Cortex no visibility, and where it
+// cannot be carried the socket is declined rather than broken. Decline and forward are
+// the escape hatches: decline keeps Codex on HTTPS without delay, and forward hands the
+// socket across as every other WebSocket is, working but opaque.
+//
+// A config that still sets the deprecated decline_responses_websockets, and not this
+// key, gets the mode that boolean meant (see DeclineResponsesWebSockets).
+func (l ListenerConfig) ResponsesWebSocketsMode() string {
+	if l.ResponsesWebSockets != "" {
+		return l.ResponsesWebSockets
+	}
+	if d := l.DeclineResponsesWebSockets; d != nil {
+		if *d {
+			return ResponsesWebSocketsDecline
+		}
+		return ResponsesWebSocketsForward
+	}
+	return ResponsesWebSocketsParse
 }
 
 // Proxy roles selectable via ListenerConfig.Roles in proxy-sidecar mode.