Skip to content

feat(link): teach a Child its Home's link WebSocket state and open the Home leg (not wired yet) - #8614

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

lidge-jun merged 4 commits into
devfrom
feat/link-websocket-child

Conversation

@lidge-jun

Copy link
Copy Markdown
Owner

Summary

A Remote Link Child answers Codex's Responses WebSocket upgrade with 426, so Codex sends every model request over HTTP through the link and re-sends the whole conversation each time. The Home side merged in #8593 behind a closed release gate. This is the first Child-side piece (lane T6 of the link WebSocket design). It adds three parts that nothing calls yet; a Child behaves exactly as before.

Learning the Home's state (src/client/link-ws-advertisement.ts, hook in src/client/link-relay-transport.ts). A Home with the feature on adds x-opencodex-link-ws-state: on and an HMAC proof bound to the nonce and both identities to every verified relay-auth 204 (#8593). Every preflight the Child starts (data requests, catalog reads, the parity report, the readiness probe) now takes a number from one process counter, and noteHomeConnection applies the answer's state only when its number is higher than the last one applied for that link. A late reply to an earlier preflight therefore never overwrites a newer answer, whichever Home or Home process sent it. An evicted link keeps its own watermark (at most 1,024), so an answer still in flight when its link was evicted cannot land as the newest, and other links' traffic never voids an answer for a link it did not evict. An answer without the pair, or whose proof does not verify, applies as off. The state is in memory only, so a restart starts from off; a relink is a new link id; at most 256 links are kept.

Opening the Home leg (src/client/link-ws-transport.ts). openLinkWebsocket runs one relay-auth preflight and the upgrade on one SingleConnectionAgent connection, never a second. It proceeds only when that preflight's own answer is a verified on. The upgrade carries the session nonce, the link key as a Bearer and a fresh Sec-WebSocket-Key, and drops Origin, Sec-WebSocket-Extensions and Sec-WebSocket-Protocol. A 101 counts only on the authenticated socket, with Upgrade: websocket, a Connection naming upgrade, the right accept value, and no extension or subprotocol. A 101 that the HTTP parser does not treat as an upgrade (no Upgrade header) is a broken handshake too. Every failure is one closed word (credential, preflight, not_advertised, home_refused, handshake, aborted) and destroys the connection. Nothing retries.

A client framer (src/client/link-ws-framer.ts). The Home leg runs on the socket the preflight authenticated, so a WebSocket client that opens its own connection cannot be used. Under Bun, ws resolves to Bun's built-in shim, and its Receiver and Sender throw "Not supported yet in Bun" (checked on Bun 1.4.4). The framer therefore implements the client state machine the design lists:

  • masked client frames;
  • RSV bits zero; opcodes 0, 1, 2, 8, 9 and 10 only;
  • control frames of at most 125 bytes, never fragmented;
  • continuation frames only inside a message;
  • minimal length encodings, with the 64-bit top bit zero;
  • UTF-8 validation of whole text messages and close reasons;
  • wire-valid close codes only, and masked server frames refused;
  • a message limit, checked before a payload is held, and a fragment limit;
  • at most the message limit plus a 14-byte header held at once: an unfragmented message gets its own buffer, and a fragmented one is written in place into one reassembly buffer that is dropped when the message completes.

Each violation maps to the close code to send (1002, 1007 or 1009).

Limits and a Child release gate (src/client/link-websocket-limits.ts). The Child's caps, budgets and timeouts from the design are named in one place. linkWebsocketChildReady() is false and stays false until the framer's client conformance run (Autobahn fuzzingserver) and the Child's memory acceptance have passed, so a Home that opens its own gate cannot switch on an untested Child framer.

Why this is inert. Nothing in the listener or the ingress calls openLinkWebsocket; Codex's upgrade still gets the same 426. The only change on the existing path is in link-relay-transport.ts: each preflight takes a number, and a verified answer's state pair is checked and recorded in memory. The relay's requests, headers, bodies and outcomes are unchanged. Homes send the pair only while their feature is on, which their own closed gate prevents today.

Not in this PR: the ingress and listener wiring, the 503 sequence while the Child's tunnel reconnects, and byte accounting for sockets (next PR). The feature id link-responses-ws/1 will be added with the change that opens the release gates; adding it now would change every Child's peer report and the compatibility verdict Homes show.

Verification

Tests that failed first (the three files fail on origin/dev because the modules do not exist; output kept outside the repository):

  • tests/clients/link-ws-advertisement.test.ts: a verified on only with a proof bound to this nonce, key and link; an earlier preflight's late answer never applied; more than four toggles in scrambled order ending on the last one sent; a relink and a restart; no convergence without traffic; with real preflights against a stand-in Home, the readiness probe and a data request both teach the state, a 204 without the pair or with a bad proof is off, a data request answered 404 (an older Home without the parity route) still teaches it, and Home A's answer delayed past Home B's is ignored.
  • tests/clients/link-ws-transport.test.ts: the upgrade on the authenticated connection with the key, the nonce and a clean header set; frames both ways, with bytes coalesced into the 101 read first; no upgrade when this answer is off, has no pair or has a bad proof; refused or unreachable preflights; a Home refusal; six invalid 101 shapes each destroy the connection; an abort while the Home holds the upgrade, and before anything is sent; a target without its identity sends nothing.
  • tests/clients/link-ws-framer.test.ts: every rule above, chunked and coalesced input, fragments with an interleaved ping, a character split across fragments, a leading U+FEFF kept in text and close reasons, the held-bytes bound across a fragmented message followed by a near-limit one, and writing at each length form.

Added in review (each failed first on the code before its fix): an advertisement answer still in flight when its link was evicted is ignored; other links' evictions never void an answer; a leading U+FEFF is kept; the held-bytes bound.

The stand-in Home (tests/fixtures/link-ws-standin-home.ts) is a raw TCP server, so a test controls every byte of the relay-auth answer, the 101 and the frames; a session nonce is valid only on the connection that made it, as on a real Home.

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/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 (206 files, including tests/clients/link-boundary.test.ts), run on this head alone: 3467 pass, 67 skip, 3 fail, exit 1. The three failures are environment-only: link-ocx-child-conformance (one case) and link-ocx-child-e2e (two cases) need cargo build of native/ocx-child, and this machine has no default Rust toolchain ("rustup could not choose a version of cargo to run"). This PR changes no Rust code and nothing those tests exercise.

NOT RUN: the full suite (resource limits on the build machine; CI covers it); the Autobahn client conformance run (no Docker here; it is the release gate the Child-side gate waits for); 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 has the Child-side paragraph. Nothing user-visible changes, so docs-site/ is unchanged.)
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (The link key is sent only on the connection whose preflight proof verified, and only when that answer's own state proof verifies; 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.
…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.
@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.

…ild-t6-1b

# Conflicts:
#	scripts/test-layout/layout-clients.json
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 02:37
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 02:37
@lidge-jun
lidge-jun merged commit b059991 into dev Nov 13, 2026
33 checks passed
@lidge-jun
lidge-jun deleted the feat/link-websocket-child branch November 13, 2026 02:37
@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-13T02:40:06.875430Z 1dd540d 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
…t-child-t6-3

Brings in dev 20fb0d3 and the squash b059991 (#8614) through the lower slice's tie; no file of this slice is edited (git merge-tree, no conflicts).
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