Skip to content

feat(ocx-child): carry Codex's Responses WebSocket over the Remote Link when the Home advertises it (closed gate) - #8653

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

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

Conversation

@lidge-jun

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

Copy link
Copy Markdown
Owner

Summary

The lightweight Rust Child (native/ocx-child) answers Codex's Responses WebSocket upgrade with a fixed 426. Codex then uses HTTP for the whole session and re-sends the full conversation through the link tunnel on every model request. The TypeScript Child already carries that WebSocket over the link's authenticated connection when the Home advertises it (#8614, #8619, #8620); disposable cloud machines run ocx-child, so they kept paying the full HTTP cost.

This change gives ocx-child the same path behind its own closed release gate:

  • Advertisement (link_ws_advert.rs): every relay-auth preflight of the serving process (relayed HTTP requests, the parity report, the /readyz probe) takes a sequence number before it is written. Its answer's x-opencodex-link-ws-state and x-opencodex-link-ws-proof count only as exactly one of each, with the proof an HMAC under the 32 bytes decoded from the fingerprint, equal to the Home's linkWebsocketStateProof, compared in constant time; both sides check the same vectors in tests/fixtures/link/link-ws-state-proof.json. An answer applies only to its own link id and only above the last number applied for it (8 links, per-link watermarks). Lifecycle commands run in their own process and teach the server nothing.
  • Upgrade (link_ws.rs): with the gate open and a verified on for the current link, a valid Codex handshake without Origin takes a slot (8 open or setting up, 4 setting up, 32 MiB of a 256 MiB budget), then makes one preflight and the upgrade on one connection inside one 8 s deadline, cancellable by stop. The upgrade proceeds only on that answer's own verified on. The Home leg carries Codex's headers minus its handshake, the hop-by-hop and Connection-nominated set, Origin, Host, framing, caller credentials and the relay's internal headers; the link key is added through the existing wiped request-head pattern. The Home's 101 counts only with Upgrade, Connection, the right accept value and no extension or subprotocol. Every failure before the local 101 is today's 426.
  • Relay: one RFC 6455 frame reader for both roles (link_ws_frame.rs) with the TypeScript Child's bounds (8 MiB from Codex, 4 MiB + 64 KiB from the Home, fragment cap, held bytes bounded). Each socket has two threads, and each frame write is one operation with an absolute deadline (data 600 s, control 30 s) registered before its write lock, plus a 300 s no-progress write timeout. One reaper thread enforces every deadline by shutting sockets down without taking a write lock. One idempotent terminal transition closes both legs within 5 s (close frames best effort): Codex's close without a status reaches the Home as an empty close, Codex's drop ends the Home connection without one, Home close codes are relayed, and binary closes both legs with 1003. Serve shutdown aborts setups, closes every socket with 1001 (best effort, each close given at most 1 s, all at once, so a stop ends well inside the 3 s that detach, restart and sync wait for the port) and waits until every slot is free. A panic in either of a socket's threads still ends both connections, unregisters the socket and frees its slot, and a relay worker or control thread that panics still returns its admission slot.
  • Review fixes (the slice's review found two P2s, both fixed test-first): the local 101 is written under Codex's write lock inside its own operation deadline and no frame ever reaches Codex before it; a stop that claims a socket between registration and the 101 leaves the 101 unwritten, and the worker answers today's 426 as best effort (the stop also shuts Codex's connection down, so Codex may see it close with nothing written instead); every setup write (the preflight when it has a whole-request deadline, and the upgrade head) gives each write call only the time left before the deadline (relay::write_all_before), so a Home that drains slowly cannot stretch setup past 8 s. Preflights without a deadline write as before.
  • Fallback and a turn in flight: ocx-child has no tunnel supervisor, so it has no reconnect 503 of its own (the existing child_busy/child_starting 503s apply to upgrades as to HTTP). If the tunnel or Home drops mid-turn, Codex gets 1011 and retries on its own; nothing is replayed by the Child, so no request is duplicated.

What keeps it inert: link_ws_advert::gate_open is false in every build without the link-ws-test-gate Cargo feature, whatever the profile; only a build with the feature reads OCX_CHILD_TEST_LINK_WS_READY. build:ocx-child (cargo build --release --locked) passes no features. With the gate closed, or before the Home's verified on, the upgrade gets today's 426 byte for byte with no network I/O. A later change opens the gate.

Differences from the TypeScript Child (on purpose, for this runtime):

  • no connecting or draining 503: ocx-child has no tunnel supervisor (its existing child_busy/child_starting 503s apply to upgrades as to HTTP);
  • TCP backpressure: a slow peer blocks the writer, where the TypeScript Child sends 1013 to Codex and 1001 to the Home on overload;
  • write deadlines (600 s data, 30 s control, 300 s without progress) close a socket, where the TypeScript Child never closes on a timer;
  • Codex's drop and a close without a status reach the Home as in the TypeScript Child since fix(link): drain Child link sockets before a restart stops the tunnel, and count only sockets Codex opened #8658 (a drop cuts the Home connection without a close frame; a close without a status is an empty close frame). The TypeScript Child also drains on a supervisor stop and answers upgrades with a temporary 503 then; ocx-child answers 426 once a stop has begun;
  • 8 links kept in the advertisement table against 256;
  • no Child-local opt-out, counters or traffic book.

Release evidence: scripts/test.ts is one of the 26 job-selection files .github/scripts/release-evidence-policy.json pins, and this PR changes it: the two TypeScript wrappers that run ocx-child's Cargo tests (tests/clients/link-ocx-child-ws-gate.test.ts without the feature, tests/clients/link-ocx-child-ws-feature.test.ts with it) are listed in SERIAL_FULL_SUITE_FILES, so each runs alone under the batch runner's 120 s process deadline. One new entry of kind ci is appended at the end of the policy, with the same keys, version 1 and windowsShards 14 as dev's newest ci entry and the same 26 paths in the same order; only scripts/test.ts differs, carrying this tree's blob, and every other pinned blob equals the tree's. Every earlier entry is byte-identical. The entry admits lane=all dispatch runs on dev commits that carry this exact scripts/test.ts, with the same job list and the same 14 Windows shards; it admits nothing else.

Left for the change that opens the gate: the 30 s control-frame deadline is registered before the write lock, so a pong or close waiting behind a long data write can cut a healthy socket (a waiting control write should inherit the remaining deadline of the write holding the lock, or only the latest ping should be answered); every frame write wakes the reaper twice (register and clear); an Autobahn run of the frame reader in both roles; an RSS acceptance against the 32 MiB reservation; the pinned-Codex release-gate scenarios run through ocx-child; and a pure-move split of link_ws.rs. Also the Child-local opt-out, macOS and Windows runs, user docs, and adding tests/fixtures/link/link-ws-state-proof.json to the Rust CI path filter.

Unchanged: HTTP relaying, its headers and limits, and the 426 body. Lifecycle commands behave as before; their preflights now write through write_all_before, with the same effective timeout. Outside the new modules, relay.rs carries the upgrade path, the worker permits and the stop (+150/-19), lib.rs and Cargo.toml register the modules and the test feature, and daemon.rs send_attested_shutdown is now pub for the shutdown test. ocx-child has no Child-local opt-out, counters or byte book for the link WebSocket, as it has none for HTTP.

Verification

Tests (each behaviour commit was test-first; the later test commits cover paths that already existed):

  • Framing: both roles, masking, control and continuation rules, length encodings, limits and UTF-8, events before a fault kept, held-byte bound.
  • Advertisement: the TypeScript proof vector, exactly one verified on, ordering per link, eviction keeping ordering, and the gate staying closed without the feature (run in the no-feature build).
  • Relay, in process (mock Home and Codex on loopback): frames both ways with the link key and a first frame coalesced with the head; refusal, a silent Home and a broken 101 get 426; 1003; close relays; caps and the slot held until the Home connection closed; the setup deadline; stop with 1001; pings per hop; write bounds; a Home close while the worker is blocked; stop between the 101 and the start; spawn failure; a failed local 101; the close-claim race against the worker's cleanup (mutation-checked: it fails when cleanup may retire a claimed close); a close behind a blocked data write returning at the close deadline; maximum messages crossing both ways; pings during large messages; Codex lost while a write to it is blocked; stop with writes blocked both ways on several sockets.
  • Real binary (native/ocx-child/tests/link_websocket.rs, feature build): today's 426 and no Home connection without the gate; frames both ways with it; a failed preflight teaching nothing and a later one teaching on with the parity loop stopped; a Home that switches off answered by the upgrade's own preflight with 426, the turn then completing on HTTP; /readyz teaching on; the authenticated shutdown closing both legs with 1001.
  • Review fixes: a stop claim before the local 101 leaves it unwritten and Codex gets no frame; through the real stop the 426 is best effort and nothing hangs; a setup write ends at the absolute deadline however slowly the Home drains.
  • Final-review fixes (T6-4-2): a stop with a Codex that does not read, under the default limits, ends in about 1 s (failed first at 5.0 s); a panic in the worker unregisters the socket and frees its slot, and a panic in the Home reader ends the socket and lets the worker return (both failed first: the socket stayed registered; the worker hung); a relay worker or control thread that panics returns its admission slot (failed first: the guards did not exist); the state-proof vectors are read by both the Rust and the TypeScript test from one file; the relay and advertisement unit tests share one lock; the stop test's hook fires only once the writer is past its closing check (checked by mutation: with the stop bound raised to 5 s the test fails at 5.0 s).
  • CI wiring: tests/clients/link-ocx-child-ws-gate.test.ts pins the feature wiring and runs both Cargo modes (skipped where cargo is missing, like the conformance test); it makes the run without the feature and tests/clients/link-ocx-child-ws-feature.test.ts the run with it, one Cargo run per file; both are listed in SERIAL_FULL_SUITE_FILES, so each runs alone under the batch runner's 120 s process deadline, with its Cargo run bounded at 100 s. (scripts/ci/test-durations.tsv is generated from CI logs and is left alone.)

Commands (exit codes) on 1e96467 (the T6-4-3 head f8cc664; a merge of dev f23910a (#8416), whose only conflict, structure/remote-link.md, keeps both sides; the structure sentence fix; the release-evidence entry; a merge of dev 3762722 (#8658 and others), whose conflicts in the two layout maps are resolved as the union):

  • The ocx-child CI step exactly, on stable rustc 1.100.0: cargo fmt --manifest-path native/ocx-child/Cargo.toml --check exit 0; cargo clippy --locked --manifest-path native/ocx-child/Cargo.toml --all-targets -- -D warnings exit 0; cargo test --locked --manifest-path native/ocx-child/Cargo.toml exit 0 (54 lib tests, all suites green)
  • That step builds without features; the link-ws-test-gate build is exercised only by the Bun wrapper tests/clients/link-ocx-child-ws-feature.test.ts. Run here on stable: cargo clippy ... --all-targets --features link-ws-test-gate -- -D warnings exit 0; cargo test ... --features link-ws-test-gate exit 0 (53 lib tests, 4 real-binary link WebSocket tests)
  • Gates-job checks: node --test .github/scripts/release-evidence.test.cjs exit 0 (26 pass); node .github/scripts/release-evidence.cjs policy-check exit 0; bun run typecheck exit 0; bun run privacy:scan exit 0; bun run skill:surface:check exit 0; bun run structure:check exit 0
  • bun install --frozen-lockfile: exit 0
  • bun scripts/test.ts --parallel=2 over tests/clients/link-ocx-child-ws-gate, link-ocx-child-ws-feature, link-ocx-child-conformance, link-ocx-child-e2e, link-ephemeral-child-discovery, link-child-plant-foundations, link-boundary, link-ws-relay-edges, tests/ci-workflows/test-runner, ci-workflows/ci-scope-gaps, tests/test-layout, test-layout-tooling, ci-workflows/file-size-ratchet, ci-workflows/structure-ssot: exit 0 (259 pass, 4 skip, all Windows-only, 0 fail)
  • Release-evidence entry rechecked on this tree: dev's policy is unchanged (15 entries; every earlier entry byte-identical), the new entry's 26 pinned blobs all equal git rev-parse HEAD:<path>, and scripts/test.ts is 0e4e9f6bafaecdb328fae154a826d56ac214a9b1

A test-only fix found while running the CI step (2ea43f0, in T6-4-3): the four flood tests now shut their own end of the flooding socket before joining the flood thread, so a test never waits about 107 s for the kernel to drop an orphaned connection.

Review: a gpt-6.1-terra reviewer (xhigh, read-only) reviewed the whole diff; round 1 found two P2 (stop vs the local 101; setup write deadline), both accepted and fixed with tests that failed first (a_stop_before_the_local_101_answers_426_and_writes_codex_no_close_frame: Codex read a close frame where the 101 or 426 belongs; a_setup_write_ends_at_the_absolute_deadline_however_the_home_drains: injected clock, one byte per write); round 2 on the fix: no findings. The coordinator's fresh final review of d9c6b31 approved with nits (one P2 reachable only with the gate open, and P3s); each is fixed in its own commit, test-first where there is behaviour, and a gpt-6.1-terra round on those commits found one P2 (the gate test's two Cargo runs inside one 120 s batch process) and two P3s (the stop test's hook could fire before the closing check; a panicking relay worker leaked its admission permit), all fixed; the next round found none. A round on the flood-test fix found none either. A round on this hand-over's delta (the two dev merges, the structure sentence and the release-evidence entry, reviewed as a security item) found none. Open P0-P2: 0. The design addendum had nine review rounds before implementation.

#8612 (owner record, detach --expect-link, recover) is on dev and merged here without conflicts: it changed cli.rs, codex_home.rs, platform.rs and a new test, none of which this PR touches (this PR adds link_ws*.rs and changes Cargo.toml, lib.rs, relay.rs, daemon.rs). Both add entries to scripts/test-layout/layout-clients.json and tests/fixtures/test-layout-expected.json and paragraphs to structure/remote-link.md. This hand-over also edits native/ocx-child/src/daemon.rs only by the one visibility change already in T6-4-1.

No docs-site page changes (the gate is closed; user docs come with the change that opens it).

NOT RUN: the full bun run test suite (4-core VM rule: focused files only); macOS/Windows; an opened gate against a live Home; tests/ci-workflows/docs-spanish-localization.test.ts. With #8630 the Rust suites also run in PR CI.

Checklist

  • Tests in their domain folders with layout entries
  • structure/remote-link.md updated
  • Inert by default (closed gate)

…(not wired yet)

ocx-child answers Codex's Responses WebSocket upgrade with 426, so the
saving of the link WebSocket does not reach Children that run it. This
is the first piece of carrying it there: one frame reader for both legs
(masked frames from Codex, unmasked from the Home) with the same bounds
as the TypeScript Child's framer, and the writers. Nothing calls it yet.
…ed gate (not wired yet)

- link_ws_advert: the state proof (same HMAC as the Home), exactly one
  state and proof header, per-link ordering by preflight number with
  watermarks for evicted links, memory only.
- The gate is closed in every build without the link-ws-test-gate Cargo
  feature; only a test build with it reads OCX_CHILD_TEST_LINK_WS_READY.
… the Home advertises it (closed gate)

With ocx-child's gate open (only a link-ws-test-gate build can open it)
and the Home's verified on applied for the current link, the upgrade on
/v1/responses now opens the Home leg on one authenticated connection
and relays whole text messages both ways; every failure is today's 426.

Two threads per socket, every frame write a bounded operation under a
per-socket write lock, one reaper thread enforcing every deadline by
shutting both sockets down, an idempotent terminal transition with a
5 s close bound, and a registry whose stop aborts setups and closes
sockets with 1001. Slots are held until nothing can use the sockets.
…op before start, spawn failure

A failed spawn of the Home reader thread before the local 101 now leaves
Codex's connection to its owner, which answers today's 426, and only
shuts the Home connection down.
…x-child

# Conflicts:
#	scripts/test-layout/layout-clients.json
#	tests/fixtures/test-layout-expected.json
@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.

@github-actions github-actions Bot added the enhancement New feature or request label Nov 13, 2026
…Cargo runs bounded inside the batch deadline
…x-child

# Conflicts:
#	scripts/test-layout/layout-clients.json
… a test never waits for the kernel to drop an orphaned connection
…x-child

# Conflicts:
#	structure/remote-link.md
…e gate-opening change still owes, without citing notes outside the repository
…rappers in the release evidence policy, keeping the earlier entries
…x-child

# Conflicts:
#	scripts/test-layout/layout-clients.json
#	tests/fixtures/test-layout-expected.json
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 08:46
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 08:46
@lidge-jun
lidge-jun merged commit c9fe14a into dev Nov 13, 2026
40 checks passed
@lidge-jun
lidge-jun deleted the feat/link-websocket-ocx-child branch November 13, 2026 08:46
@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-13T08:48:20.886680Z 1e96467 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

Copy link
Copy Markdown
Owner Author

Maintainer integration record for this squash merge.

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

The layout maps (layout.json, layout-clients.json, test-layout-expected.json) are the union of both sides, checked key by key. structure/remote-link.md keeps both sides: this branch's paragraph is dev's plus the U11, real-Child, restart and Autobahn sentences. The gate file keeps this branch's version, in which #8668's labels and binary copy live in tests/helpers/link-gate-codex.ts.
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