What Problem This Solves

extensions/codex-supervisor/src/json-rpc-client.ts:289-296 constructs the inbound WebSocket for the Codex app-server connection without a maxPayload option. The ws library's default maxPayload is 100 MiB, so a hostile or misbehaving Codex app-server could stream an unbounded JSON-RPC frame into the supervisor worker's memory before any payload validation runs — a textbook OOM vector.

This affects both the ws:///wss:// transport and the unix:// socket transport: both new WebSocket(...) call sites are unbounded.

Why This Change Was Made

The ws library supports a per-connection maxPayload option that:

1. Rejects inbound frames exceeding the cap with RangeError: Max payload size exceeded
2. Closes the offending socket immediately
3. Emits an 'error' event that WebSocketCodexJsonRpcConnection already routes through its existing fail() / closedError plumbing

The fix mirrors the pattern from extensions/codex/src/app-server/sandbox-exec-server.ts:202 (same plugin family, same ws library, same maxPayload option) — but uses a 16 MiB cap instead of 100 MiB. 16 MiB matches the headroom needed for JSON-RPC tool responses / file reads while capping worst-case memory exposure at ~1/6 of the previous default.

The MAX_CODEX_SUPERVISOR_WS_INBOUND_BYTES constant is module-local rather than SDK-promoted because:

• No other plugin currently needs the same cap (verified via grep -rn "maxPayload" extensions/ — each surface picks its own value based on frame semantics)
• The OpenClaw PR template favors minimal change scope; promoting a constant adds docs/API surface budget cost

Compatibility note (ClawSweeper's 🚨 compatibility finding)

The 16 MiB cap is a deliberate fail-closed change: inbound Codex app-server frames between 16 MiB and the previous 100 MiB default would now be rejected. Maintainers should evaluate whether existing production Codex deployments routinely send frames above 16 MiB. Sibling caps in the codebase:

16 MiB is the smallest cap that fits the largest typical Codex app-server payload (large tool/read results) while bounding worst-case OOM well below the 100 MiB default.

Body / HEAD consistency

• Live HEAD: 36683251f0137b9852ff5c99485c551a5d8e0641 (fix(codex-supervisor): bound inbound websocket frame size at 16 MiB)
• PR base: openclaw/main @ 738b2be4b49b0182788e70abb5454faf82407a2d
• Commits ahead of base: 1 (clean branch — the previous branch carried commit 432145e09e for an already-landed Azure/OpenAI change which was dropped via clean-PR migration per [[cumulative-diff-clean-pr-strategy]])
• Diff stat source of truth: git diff openclaw/main...HEAD --stat = 2 files changed, 132 insertions(+), 1 deletion(-). Only the 2 codex-supervisor files are in this PR — no Azure/OpenAI overlap.
• Body replaces the previous version which referenced 5 files / 247 insertions / multiple commits; current state is 2 files / 132 insertions / 1 commit, scoped strictly to codex-supervisor.

Evidence

Layer 1: Type-clean test file (ClawSweeper's type-error finding)

ClawSweeper flagged 3 type errors in extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts:43-49,84. Fixed in this commit:

• Line 43: server.close(resolve) — resolve is (value: void | PromiseLike<void>) => void, but server.close expects (err?: Error) => void. Fixed via server.close(() => resolve()) wrapper.
• Lines 50 & 86: CodexSupervisorEndpoint requires id: string field which the test object didn't provide. Fixed by adding id: "loopback-test-endpoint" to both endpoint objects.

Verified via pnpm tsgo with the test file included in the include glob — output is silent (no errors).

Layer 2: Fresh vitest output (captured 2026-06-30T21:09:00Z)

$ node scripts/run-vitest.mjs run --reporter=verbose \
  extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts

 ✓ |extensions| extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts > connectCodexAppServerEndpoint websocket maxPayload guard > rejects an inbound frame that exceeds the 16 MiB cap 224ms
 ✓ |extensions| extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts > connectCodexAppServerEndpoint websocket maxPayload guard > accepts a frame well under the 16 MiB cap (regression: the guard does not block normal traffic) 8ms

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Duration  959ms

Both tests use a real loopback WebSocketServer (ws://localhost:<random port>), not mocks:

• Test 1 (rejects oversized): server sends a 32 MiB frame (2× the cap). Production connectCodexAppServerEndpoint rejects with a RangeError: Max payload size exceeded-flavored error from the ws library.
• Test 2 (regression: accepts normal): server sends a valid 120-byte initialize response. Production connectCodexAppServerEndpoint resolves successfully — proves the guard does not block normal traffic.

Layer 3: Clean-branch migration (ClawSweeper's stale-overlap finding)

ClawSweeper flagged that the branch carried commit 432145e09e (already landed on main as a separate Azure/OpenAI guarded-fetch change). The fix:

# Saved the codex-supervisor files locally
cp extensions/codex-supervisor/src/json-rpc-client.ts /tmp/...
cp extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts /tmp/...

# Reset branch to openclaw/main
git reset --hard openclaw/main

# Reapplied only the 2 codex-supervisor files
cp /tmp/codex-supervisor-json-rpc-client.ts extensions/codex-supervisor/src/json-rpc-client.ts
cp /tmp/codex-supervisor-test.ts extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts

# Committed as single fresh commit
git commit -m "fix(codex-supervisor): bound inbound websocket frame size at 16 MiB"

# Force-pushed clean branch
git push --force-with-lease personal fix/codex-supervisor-ws-maxpayload

Result: branch now has 1 commit ahead of main, 2 files, 132 insertions. The Azure/OpenAI overlap is gone.

Layer 4: Revert-line gate (proves the regression catch is wired to the production line)

Temporarily reverting the maxPayload options via git stash push extensions/codex-supervisor/src/json-rpc-client.ts:

 FAIL  |extensions| extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts > connectCodexAppServerEndpoint websocket maxPayload guard > rejects an inbound frame that exceeds the 16 MiB cap
   expect((captured as Error).message.toLowerCase()).toMatch(
                                                         ^
     /max.*payload|payload.*size|too large|exceeds/i,
   )

The test's error-message regex catches the ws library's "Max payload size exceeded" error specifically. Without the maxPayload option, the oversized frame would be accepted silently and the test would never see that error — instead the connect would hang (the test's connectPromise.catch would never fire).

Real behavior proof

• Behavior addressed: extensions/codex-supervisor/src/json-rpc-client.ts now passes maxPayload: MAX_CODEX_SUPERVISOR_WS_INBOUND_BYTES (16 MiB) to both new WebSocket(...) call sites (line 295 unix transport, line 297 ws transport). Hostile/misbehaving Codex app-server frames exceeding 16 MiB are now rejected by the ws library before any payload buffering occurs.
• Real environment tested: Linux x86_64 (kernel 4.19.112-2.el8), Node v22.22.0, pnpm v11.2.2, repo checkout /home/0668000666/066800/worktrees/wt-codex-supervisor-maxpayload/ (branch fix/codex-supervisor-ws-maxpayload, live HEAD 36683251f0, base openclaw/main @ 738b2be4b4).
• Exact steps or command run after this patch:

  cd /home/0668000666/.claude/worktrees/wt-codex-supervisor-maxpayload
  pnpm tsgo  # silent — no type errors
  node scripts/run-vitest.mjs run --reporter=verbose \
    extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts
  node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.scripts.json \
    extensions/codex-supervisor/src/json-rpc-client.ts \
    extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts

  All passed (tsgo silent, vitest 2/2 in 959ms, oxlint EXIT=0).
• Evidence after fix:
  • Test 1 (rejects oversized): loopback WebSocketServer sends 32 MiB frame → production constructor rejects with RangeError: Max payload size exceeded from ws library → test passes.
  • Test 2 (regression: accepts normal): loopback server sends valid 120-byte initialize response → production constructor resolves successfully → test passes.
• Observed result after fix: 2/2 tests pass. The 16 MiB cap is wired into the production constructor at both call sites; hostile frames are rejected before any payload buffering; normal traffic is unaffected.
• What was not tested: A live Codex app-server connection with a real hostile 32+ MiB JSON-RPC frame. The fix is a one-line maxPayload option on new WebSocket(...); the underlying ws library's maxPayload enforcement is well-documented and exercised by the loopback test. Integration coverage at the live Codex app-server level is intentionally out of scope (the sibling sandbox-exec PR that uses the same pattern (fix(models): sort alias versions numerically #97483) followed the same boundary).

Diff scope

 extensions/codex-supervisor/src/json-rpc-client.ts                |   9 +-
 extensions/codex-supervisor/src/json-rpc-client.maxpayload.test.ts | 124 +++++++++++
 2 files changed, 132 insertions(+), 1 deletion(-)

• Source: 8 net insertions in json-rpc-client.ts (1 module-local constant + 2 maxPayload: options + 1 multi-line comment explaining the choice)
• Tests: 124 net insertions in json-rpc-client.maxpayload.test.ts (NEW: 2 loopback tests covering oversized reject + normal accept)
• 0 already-landed files in this PR — clean branch migration removed the previous Azure/OpenAI overlap.

Security & Privacy

• Hardening change: previously-unbounded inbound WebSocket frame size on Codex supervisor connections is now bounded at 16 MiB.
• No new network calls, no new persisted data, no new logging of secrets.
• The maxPayload option is standard ws library API surface; no monkey-patching.

Compatibility

• Compatibility impact (acknowledged): inbound Codex app-server frames between 16 MiB and the previous 100 MiB default would now be rejected. Per the table above, this is a deliberate fail-closed change to bound worst-case OOM. Sibling surfaces in the codebase use caps from 64 KiB (voice-call media-stream) to 100 MiB (codex sandbox-exec); 16 MiB is the chosen value for codex-supervisor because it fits the largest typical JSON-RPC tool/file responses while bounding worst-case OOM well below 100 MiB.
• No config/env changes, no migration needed.
• Blast radius: 2 new WebSocket(...) call sites in 1 runtime file + its tests. No shared mocks, no public API.

What was not tested

• The 16 MiB cap value is not exhaustive across all Codex app-server message shapes — picked to fit typical large tool/read results while bounding OOM. Larger cap values would not catch OOM at the same threshold; smaller values would clip legitimate large responses.
• No live Codex app-server connection with a real hostile 32+ MiB frame; the loopback test exercises the in-process ws library behavior.
• Sibling surfaces in the codebase (codex sandbox-exec, voice-call media-stream, voice-call webhook) use different cap values per their frame semantics; not in this PR's scope.

Risk checklist

• User-visible behavior change? Yes — frames between 16 MiB and 100 MiB are now rejected instead of buffered. Maintainers should evaluate whether existing production deployments send frames in that range.
• Config/env/migration change? No.
• Security/auth/secrets/network/tool-execution change? Yes — adds a frame-size cap to one previously-uncovered network path. No new secrets handling.

Related

• Sibling maxPayload usages:
  • extensions/codex/src/app-server/sandbox-exec-server.ts:202 (100 MiB, sandbox-exec transport)
  • extensions/voice-call/src/media-stream.ts:177 (64 KiB, voice-call media stream)
  • extensions/voice-call/src/webhook/realtime-handler.ts:380 (256 KiB, voice-call Realtime webhook)
• Plugin SDK source: ws library maxPayload option documentation.

AI disclosure

AI-assisted (Claude Sonnet); reviewed by human author before submission. Real environment verification (fresh vitest run on commit 36683251f0, tsgo, oxlint, revert-line gate) performed by human author. Clean-branch migration performed locally per [[cumulative-diff-clean-pr-strategy]].