Skip to content

feat(link): a Child carries Codex's Responses WebSocket over its link when the Home advertises it (behind a closed Child gate) - #8619

Merged
lidge-jun merged 12 commits into
devfrom
feat/link-websocket-child-t6-2
Nov 13, 2026
Merged

lidge-jun merged 12 commits into
devfrom
feat/link-websocket-child-t6-2

Conversation

@lidge-jun

Copy link
Copy Markdown
Owner

Stacked on #8614 (base: its head 7934512). Review this PR as the commits after that head.

Summary

A Remote Link Child answers Codex's Responses WebSocket upgrade with 426. Codex then sends every model request over HTTP through the link, and each request re-sends the whole conversation. #8593 added the Home side and #8614 the Child's pieces: the advertisement state, the Home-leg transport and the framer. This PR wires them in. When the Child's release gate is open and the Home advertised the feature on the last relay answer the Child applied, the Child accepts Codex's upgrade and relays whole text messages over the link's authenticated connection. Both release gates stay closed, so nothing changes for anyone yet.

When the Child tries the upgrade (src/client/link-websocket.ts, src/client/link-ingress.ts). Only when linkWebsocketChildReady() is true and the link's advertised state is on. In every other case the ingress answers today's 426, byte for byte, and opens no connection. A tried upgrade passes these checks in order:

  1. no Origin header at all (a non-local one still gets today's 403 first);
  2. the link key is available;
  3. the Child's caps: 8 sockets open or setting up, 4 setting up, and a 32 MiB reservation from a 256 MiB budget;
  4. the tunnel gate. A Child-initiated tunnel that is connecting or reconnecting is held up to 3 s and then answered 503 with code link_websocket_unavailable and no Retry-After. This is the only transient answer, and never one of the three 503 codes codex-rs treats as terminal. A failed tunnel gets 426, and a Home-initiated link goes straight on. An ownership proof that hit its deadline gets one fresh proof, as an HTTP request does, and every proof is raced against the setup budget;
  5. one preflight and the upgrade on one authenticated connection (feat(link): teach a Child its Home's link WebSocket state and open the Home leg (not wired yet) #8614). The transport checks the Child gate itself before any I/O and bounds the upgrade on its own.

Steps 3 to 5 share an 8 s budget, below Codex's 15 s connect timeout. Every other failure, the budget included, is the same 426, so that Codex session uses HTTP. The local 101 carries x-codex-websocket-max-message-bytes: 8388608, so Codex sends a larger request over HTTP instead.

Relay (src/client/machine-listener.ts gives the link-mode listener a websocket handler: 8 MiB messages, an 8 MiB backpressure limit that never closes the socket, no idle timeout, no compression). The Child never parses a message or writes one of its own:

  • Text passes both ways unchanged.
  • A binary message from Codex closes both legs with 1003.
  • A Home message over 4 MiB + 64 KiB, or any frame the framer refuses, closes Codex with 1011 and the Home with the framer's code. Messages completed earlier in the same chunk are delivered first.
  • Close codes are relayed (1000-1003, 1007-1014, 3000-4999). 1005, 1006, 1015 and a dropped connection become 1011.
  • Pings stay on their own hop.
  • A second message from Codex while the first is still unflushed toward the Home closes both legs: 1013 to Codex, 1001 to the Home. Bun cannot pause delivery, so the queue never grows.
  • The Child stops reading the Home leg while more than 1 MiB waits toward Codex, and resumes on Bun's drain.
  • A close either side starts is ended by the Home's answer or after 5 s. A socket keeps its slot and its reservation until its Home connection has actually closed. A close decided before Bun opened Codex's socket is applied when the socket opens.
  • Any stop of the listener, graceful or forced, first aborts every upgrade still in setup and closes every link socket with 1001 on both legs. A graceful drain therefore never waits on an idle Codex socket.

A turn in flight when the tunnel reconnects. The Home leg ends without a close frame, so the Child closes Codex's socket with 1011. The Home cancels the cut turn and records its activity hold (#8593). The Child never re-sends a frame or a request; Codex alone retries. While the tunnel reconnects, each retry gets the 503 above, at a cost of one retry from Codex's budget. If the tunnel is back within the budget, the next attempt runs on the WebSocket and starts with a full request. If not, Codex switches the session to HTTP and resends the same request once, and the HTTP relay holds it for the tunnel as today.

Child activity. A turn running on a link socket is busy in the Home's activity book, and a socket lost mid-turn leaves a durable hold (#8593). Activity-gated syncs and restarts therefore wait for it. The Child's part is to close the Home leg as soon as Codex's socket goes. A test drives both through a real Home.

Byte accounting (#8584). A link socket counts as one request in the Child's traffic book. Message payload bytes count toward the Home once the socket write completed, and from the Home per complete message. Framing, the handshake and control frames are not counted, as HTTP headers are not. The socket is complete when a close ended it. HTTP requests are counted exactly as before. Per-body zstd (#8594) stays HTTP-only: WebSocket messages go as they are, and permessage-deflate is refused.

Diagnostics. Only fixed words go to the existing allowlisted sink: link_ws_open, link_ws_close (client, home, home_dropped, binary, protocol, overload, stopped) and link_ws_fallback (origin, credential, cap, memory, tunnel_failed, tunnel_connecting_timeout, preflight, not_advertised, home_refused, handshake, timeout, aborted). No key, content or address is written. The dashboard's diagnostics table filters unknown events, so it does not show these yet.

Version mixes.

  • New Child, old Home: no state pair, so the Child stays off and answers 426 with no I/O.
  • Old Child, new Home: the old Child answers 426 locally and ignores the pair.
  • A Home that switches off mid-session: it fences the socket, Codex's retry gets 426, and the request completes over HTTP.
  • A Home that restarts or drops: Codex reconnects; if the Home is back and advertising, the session continues on the WebSocket, otherwise 426 and HTTP.

Also here.

What keeps this inert. linkWebsocketChildReady() is false, and Homes advertise nothing while their own gate is closed (#8593). With either closed, the upgrade gets today's 426 with no network I/O; a characterization test checks the bytes and the connection count. The listener's new websocket handler is only reachable through server.upgrade, which only an admitted upgrade calls. The stop wrapper's closeAll() has nothing to close. Not in this PR: the Child's ?transport=1 counters and the Child-local opt-out (D4), which come next; the lightweight Rust ocx-child (it keeps its 426); the feature id link-responses-ws/1, which comes with the change that opens the gates.

Verification

Tests that failed first (on the #8614 head for the slice, and on the commit before each review fix; output kept outside the repository):

  • tests/clients/link-ws-relay.test.ts (28 cases, against a raw-TCP stand-in Home):
    • the 101 with the 8 MiB header, and text both ways with the link key and never Codex's credential;
    • a local Origin, Home refusals (401, 426, 503), a broken 101, and a Home that stopped advertising before this upgrade's own preflight, each answered 426;
    • close relays (4401, 1012-1014, no code, a dropped Home) and the bounded Child close;
    • binary, an oversized message each way, the coalesced delivered-before-refused case (also through a HomeLeg fed in one call), uplink overload, downlink pause and resume with nothing dropped, pings;
    • runtime stop; caps, the setup cap and the memory budget;
    • a closing socket keeping its slot; a stop aborting setups in the tunnel hold and at the Home; Codex leaving during setup; the setup budget; a stalled ownership check;
    • the tunnel gate's 503 (exact body, no Retry-After, a 3 s hold), a failed tunnel, a Home-initiated link, a deadline retry;
    • byte accounting, fixed-word diagnostics, a Home gone before Bun opens the socket.
  • tests/clients/link-ws-fallback.test.ts, with a client that follows codex-rs's retry and fallback policy:
    • the 503 sequence recovering on the WebSocket;
    • the 503 sequence ending on HTTP with the request sent once;
    • a Home switching off mid-session ending on HTTP, after which the session stays on HTTP;
    • a dropped Home reconnecting on a new socket;
    • an older Home's 404 and a full Home's 426.
  • tests/e2e-style/link-ws-child-home.test.ts (a real scratch Home with its gate opened for the test): a Child-relayed turn is the link's activity while it runs and not after; a Codex socket lost mid-turn leaves the Home's hold.
  • tests/clients/link-ws-transport.test.ts: the closed Child gate refuses before any I/O; an unanswered upgrade ends at the budget; an error on the handed-off socket is recorded.

Characterization (passes before and after): a closed Child gate or a never-advertising Home answers today's 426 byte for byte with no connection to the tunnel port; a non-local Origin keeps its 403.

Release gate: tests/e2e-style/link-websocket-release-gate.test.ts replaces its "belongs to the Child lane" skip with two cases that drive the pinned Codex binary through the real Child listener and a scratch Home, with a tunnel gate the test drives. Without the pinned binary they are skipped with the U13 label. As a smoke check only (not release evidence), I ran both with the codex-cli 0.167.2 binary on the build machine: two 503s and then the turn on the WebSocket; and, separately, every upgrade within Codex's budget answered 503, then the request once over HTTP. Both completed.

Commands (Bun 1.4.4, TMPDIR=/tmp):

  • bun run typecheck: exit 0.
  • bun run privacy:scan: exit 0.
  • bun run structure:check: exit 0.
  • bun scripts/test.ts --parallel=2 tests/clients/ tests/e2e-style/link-ws-child-home.test.ts tests/e2e-style/link-websocket-release-gate.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/structure-ssot.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/lab/core-lab-boundary.test.ts (including tests/clients/link-boundary.test.ts): 3506 pass, 74 skip, 3 fail, exit 1. The three failures are environment-only: the ocx-child Rust conformance and end-to-end tests need cargo build, and the build machine has no default Rust toolchain. This PR changes no Rust code.

NOT RUN: the full suite (resource limits on the build machine; CI covers it); the Autobahn client conformance run and the Child's transport-only RSS acceptance, both of which the Child gate waits for; the release-gate cases with the pinned binary (U13); the two ocx-child Rust tests above.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed. (structure/remote-link.md covers the Child side. Nothing user-visible changes while the gates are closed, so docs-site/ waits for the change that opens them.)
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (A local process reaches the Home only through the same link key, tunnel admission and authenticated connection as HTTP; browsers are refused by the Origin rule; nothing is logged.)

Implemented by Claude Opus 5.5 (anthropic/claude-opus-5-5) in GOAT through the Codex harness; in-lane review by GPT-6.1 Terra (xhigh). Received as a git bundle from the VM that built it and pushed by the coordinator.

…s Home leg (not wired yet)

A Child relays Codex's model requests to its Home over HTTP only, so
every request re-sends the whole conversation through the link. This is
the first Child-side piece of carrying the Responses WebSocket instead.

- Every relay-auth preflight takes a number when it starts; a verified
  answer's x-opencodex-link-ws-state applies only when its number is
  higher than the last applied one for the link, so a late answer never
  overwrites a newer one. No pair, or a pair whose proof fails, is off.
- openLinkWebsocket runs the preflight and the upgrade on one
  authenticated connection, proceeds only on that answer's own verified
  on, and accepts only a complete 101 on that socket.
- A client RFC 6455 framer for the Home leg: Bun resolves ws to its
  built-in shim, whose framer is not implemented.

Nothing calls the transport yet and a Child-side release gate stays
closed, so Codex's upgrade still gets today's 426.
… order and text exact

Review round 1 of the Child's link WebSocket pieces:
- the relay-transport hook (preflight numbers, the state pair checked on
  every verified answer, the exports the Home leg needs) was missing from
  the previous commit, so link-ws-transport.ts could not load;
- evicting a link from the 256-entry book no longer drops its ordering:
  an answer for a link without an entry applies only when its preflight
  started after every evicted entry's last applied one;
- a leading U+FEFF in a text message or close reason is kept;
- fragments are written into one reassembly buffer of the maximum message
  size, so a fragmented message holds at most that much.
…nk when the Home advertises it

A Child answered Codex's upgrade with 426, so every model request went
over HTTP and re-sent the whole conversation. With the Child's release
gate open (it stays closed) and the Home advertising the feature on its
last applied relay answer, the Child now accepts the upgrade and relays
whole text messages over the link's authenticated socket.

- Fallbacks: a local Origin, no link key, the caps (8 open, 4 setting
  up), the 256 MiB memory budget, a failed tunnel, a preflight that is
  refused or not on, a Home refusal, a broken 101 and the 8 s setup
  budget all answer today's 426. A Child-initiated tunnel that is still
  reconnecting after a 3 s hold answers 503 link_websocket_unavailable.
- Relay: binary from Codex closes both legs (1003); a Home message over
  4 MiB + 64 KiB closes Codex with 1011; close codes are relayed with
  1005/1006/1015 as 1011; a second unflushed message from Codex closes
  both legs (1013/1001); the Home leg pauses above 1 MiB buffered
  toward Codex. The local 101 advertises the 8 MiB message limit.
- Any listener stop closes link sockets with 1001 on both legs.
- A socket counts as one request in the Child's traffic book (payload
  bytes); fixed-word diagnostics link_ws_open/close/fallback.
- The release gate's 503 sequence now runs the real Child listener.
…er links from voiding an answer

Review round 2:
- the reassembly buffer of a fragmented message is dropped once that
  message is complete, so it never coexists with the next message's own
  buffer; heldBytes() lets a test check the bound;
- an evicted link keeps its own watermark (at most 1,024), so answers for
  links that were never evicted are not compared against other links'
  numbers; only a dropped watermark raises a shared floor.
…lay registered close codes

Review round 1 of the Child relay:
- a listener stop aborts every upgrade still in its tunnel hold or at the
  Home, and keeps nothing set up after the stop began;
- a close decided before Bun opened Codex's socket is applied when it
  opens, so a Home that is gone by then never leaves Codex waiting;
- a socket keeps its slot and memory reservation until its Home
  connection has actually closed, and a Home-started close is bounded
  by the same 5 s as a Child-started one;
- every tunnel ownership check is raced against the 8 s setup budget;
- close codes 1012-1014 are valid on the wire and relayed both ways.
… the same chunk

Review round 2: the framer now appends events to the caller's array as
they complete, so when a later frame in the same TCP chunk is refused,
the relay still delivers the messages before it (a response.completed
included) in wire order, and only then closes both legs.
…ade, and never leaves an early error unhandled

Final-review notes on the previous slice and review round 3:
- openLinkWebsocket refuses with 'disabled' before any I/O while the
  Child's release gate is closed, whatever the caller does;
- the upgrade after a verified preflight has its own 8 s bound
  ('timeout'), so a Home that never answers it cannot hold the
  connection;
- the socket handed off after a 101 gets an error listener until its
  owner adds one;
- tests: a 64-bit length with a non-zero high word is 1009, and the
  delivered-before-refused case is also fed to the relay in one piece
  through the bytes coalesced with the 101.
…call

Review round 4: the socket test can split the frames across reads, so a
unit test now builds a HomeLeg whose head holds both frames and checks
that attach() delivers the completed message before closing with 1011.
…ild-t6-1b

# Conflicts:
#	scripts/test-layout/layout-clients.json
@lidge-jun lidge-jun added the enhancement New feature or request label Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

…k-websocket-child-t6-2

# Conflicts:
#	scripts/test-layout/layout-clients.json
#	structure/remote-link.md
Base automatically changed from feat/link-websocket-child to dev November 13, 2026 02:37
The squash's tree equals the merge of 1dd540d with dev 20fb0d3, so this commit records the squash as an ancestor without changing any file.
…d-t6-2

Brings in dev 20fb0d3 and the squash of the lower slice; no file of this slice is edited (git merge-tree, no conflicts).
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 03:44
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 03:44
@lidge-jun
lidge-jun merged commit 09f9d43 into dev Nov 13, 2026
35 checks passed
@lidge-jun
lidge-jun deleted the feat/link-websocket-child-t6-2 branch November 13, 2026 03:44
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T03:47:45.018244Z 8c42897 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

lidge-jun added a commit that referenced this pull request Nov 13, 2026
…8619)

The squash's tree equals the merge of 8c42897 with dev 6ee1b91, so this commit records the squash as an ancestor without changing any file.
lidge-jun added a commit that referenced this pull request Nov 13, 2026
…d-t6-3

Brings in dev 6ee1b91 and the squash of the lower slice; no file of this slice is edited (git merge-tree, no conflicts).

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8c42897609

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +274 to +275
// Complete when a close ended it, from either side; a drop, an overload or a refused message is incomplete.
this.flow.end(reason === "home" || reason === "client" || reason === "stopped");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Account for pending uplink writes before marking a socket complete

When Codex disconnects or the listener stops while a message is still queued toward a stalled Home, this marks the traffic flow complete immediately. If the close-handshake timer subsequently destroys the Home socket, the pending write fails and its callback never adds those payload bytes, even though a prefix may have reached the Home. The traffic snapshot therefore reports incomplete: 0 alongside an undercounted toHomeBytes, violating the counter contract in src/link/traffic.ts that completed requests have their uploads counted in full. Track pending write settlement and mark the flow incomplete if shutdown discards an upload, as the HTTP relay already does.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant