Skip to content

feat(link): Child link WebSocket counters and a Child-local opt-out - #8620

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

lidge-jun merged 18 commits into
devfrom
feat/link-websocket-child-t6-3

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Builds on #8619 (T6-2, merged as 09f9d43: the Child carries Codex's Responses WebSocket over its link). This PR was stacked on that branch and reviewed as the commits after its head e0a6924; it was tied to the squash and retargeted to dev before merging.

Summary

Two small pieces the link WebSocket design asks of the Child, both inert while the release gates stay closed.

Counters (design 9.3). GET /api/link/status?transport=1 on a Child's machine listener adds websocket: { open, settingUp, upgrades, fallbacks{reason}, closes{reason}, fromCodexBytes, toCodexBytes } from createLinkWebsocketRelay().counters() (src/client/link-websocket.ts).

  • fallbacks uses the relay's closed set of reasons, including tunnel_connecting_timeout for each 503 sent while the tunnel reconnects.
  • closes uses the closed set of close reasons.
  • fromCodexBytes is the message payload Codex sent on link sockets, counted on arrival whether forwarded or not (design L2). toCodexBytes is what the Child sent to Codex.
  • The counters are in memory and display only, and reset at restart.
  • With the Child gate closed, nothing is counted.
  • With the gate open, the Child-local opt-out and an unadvertised Home are counted in memory (local_optout, not_advertised) without writing a diagnostic.
  • Without the query, the status document is unchanged.

Child-local opt-out (owner decision D4, recommended default "follow the Home"). linkResponsesWebsocketOptOut: true in a Child's config.json keeps that Child on HTTP whatever its Home advertises: Codex's upgrade gets today's 426 with no network I/O. The Child reads the key once when its listener starts, and only true opts out; anything else follows the Home. The new fallback word local_optout joins the diagnostics allowlist.

What keeps this inert. The Child's release gate is closed and Homes advertise nothing, so every upgrade still gets today's 426 and nothing is counted. The status document changes only with the new opt-in query. The new config key is read only by a Child's listener and changes nothing while the gate is closed. docs-site/ will document the key with the change that opens the gates; structure/config.md and structure/remote-link.md describe it now.

Verification

Tests that failed first (tests/clients/link-ws-child-status.test.ts, against a raw-TCP stand-in Home and the real machine listener):

  • ?transport=1 adds the counters after one socket session and one refused upgrade, with the exact values; the document without the query is unchanged, before and after;
  • linkResponsesWebsocketOptOut: true answers 426 with no connection to the Home and counts local_optout;
  • each 503 while the tunnel reconnects counts as tunnel_connecting_timeout (added in review).

"An opt-out set to anything but true follows the Home" passes before and after.

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/config/ 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: 4455 pass, 84 skip, 16 fail, exit 1. All 16 failures are environment-only and fail the same way on origin/dev: 13 in tests/config/serving-runtimes.test.ts (23 pass / 13 fail on both origin/dev and this head, run alone), and the three ocx-child Rust tests that need cargo build, with no Rust toolchain on the build machine.

NOT RUN: the full suite (resource limits on the build machine; CI covers it). The environment-only failures above were run, and they fail identically without this change.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed. (structure/ now; docs-site/ with the gate-opening change, since nothing user-visible changes before it.)
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (The counters hold counts and byte totals only: no key, content, link id or address.)

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.
- GET /api/link/status?transport=1 on a Child adds its own link
  WebSocket counters: open and setting-up sockets, upgrades, fallbacks
  and closes by reason, and message bytes from and to Codex (design 9.3).
  In memory, display only; without the query the document is unchanged.
- linkResponsesWebsocketOptOut: true in a Child's config keeps that Child
  on HTTP whatever its Home advertises (owner decision D4), counted as
  local_optout. Anything else follows the Home.

Both gates stay closed, so neither changes what a Child does today.
Review round 1 of the Child counters: the tunnel_connecting_timeout path
answers 503 without going through the 426 fallback, so it now counts
itself in fallbacks.
…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
# Conflicts:
#	scripts/test-layout/layout-clients.json
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).
…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).
@lidge-jun
lidge-jun changed the base branch from feat/link-websocket-child-t6-2 to dev November 13, 2026 03:44
…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.
…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).
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 05:05
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 05:05
@lidge-jun
lidge-jun merged commit 7316cb7 into dev Nov 13, 2026
56 of 58 checks passed
@lidge-jun
lidge-jun deleted the feat/link-websocket-child-t6-3 branch November 13, 2026 05:05
@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-13T05:07:20.773330Z 2bbfe37 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.

@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: 2bbfe37c4f

ℹ️ 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 +305 to +306
const transport = url.searchParams.get("transport") === "1" && linkWebsocket ? { websocket: linkWebsocket.counters() } : {};
return Response.json({ ...status, joinAvailable: false, ...transport }, { headers: { "Cache-Control": "no-store" } });

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Document the Child transport status API in docs-site

For a connected Child, GET /api/link/status?transport=1 now exposes a new response shape even while the WebSocket release gate is closed: this branch checks only the query and the existence of the relay, not its readiness. Deferring all public documentation until the gates open therefore leaves an already-accessible API undocumented. A repository-wide search of docs-site/ found no transport=1 documentation. Add public documentation for the query, counter meanings, and restart/reset semantics in this change; structure/ documentation alone does not satisfy src/AGENTS.md's requirement to document user-visible behavior in docs-site/.

AGENTS.md reference: src/AGENTS.md:L29-L29

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