Skip to content

fix(streaming): prevent Darwin rewrite stalls - #947

Draft
WZBbiao wants to merge 2 commits into
lidge-jun:devfrom
WZBbiao:fix/codex-0146-local-provider-compat
Draft

fix(streaming): prevent Darwin rewrite stalls#947
WZBbiao wants to merge 2 commits into
lidge-jun:devfrom
WZBbiao:fix/codex-0146-local-provider-compat

Conversation

@WZBbiao

@WZBbiao WZBbiao commented Aug 3, 2026

Copy link
Copy Markdown

Summary

  • Prevent Codex Desktop turns on macOS from remaining in Thinking when passthrough SSE needs a client-facing payload rewrite.
  • Route rewrite-required traffic on Windows and Darwin through the existing bounded eager single-reader relay, with the rewrite applied inline.
  • Preserve the current runtime/config policy for ordinary no-rewrite streams and preserve existing Linux behavior.
  • Document the transport-safety exception in the architecture source of truth and all existing troubleshooting locales.

Root cause and safety

Codex Desktop requests that advertise the image_gen namespace require OpenCodex to restore client-facing tool payloads. On Darwin, the ReadableStream.tee() plus JS-pull rewrite chain can stall before forwarding its first large SSE event. The upstream can return a complete stream while the WebSocket bridge sends zero frames, leaving Codex in Thinking until its 300-second retry.

This change reuses the relay already required for Windows rewrite traffic. Raw upstream bytes still feed inspection, request-log metadata, and continuation state before the client-only transform. The incomplete rewrite frame remains charged to the turn translator budget, and cancellation/error teardown releases that charge. streamMode cannot pin the known-bad rewrite chain, while ordinary streams remain configurable exactly as before.

Verification

  • bun test tests/bun-stream-caps.test.ts tests/passthrough-abort.test.ts tests/relay-eager.test.ts tests/responses-image-gen-repair.test.ts - 78 passed, 0 failed.
  • bun run prepush from a clean /tmp worktree - 7,591 passed, 8 skipped, 0 failed; typecheck, GUI lint, full tests, privacy scan, and React Doctor all passed.
  • bun run build:gui - passed.
  • cd docs-site && bun install --frozen-lockfile && bun run build - 216 pages built.
  • bun scripts/darwin-eager-abort-stress.ts --seed 260801 --per-class 67 --deadline-ms 240000 - PASS-WITH-CAVEAT: 67/67 before-first-byte and 67/67 mid-frame aborts completed without crash or hang; the real socket probe reported all 67 backpressure cases unreachable. Deterministic relay tests cover queue-full pause, cancel wakeup, abort wakeup, and budget release.
  • Real Codex 0.146.0 with WebSockets enabled completed once with turn.completed under both pinned legacy-tee and installed auto configurations; no five-minute reconnect or duplicate upstream request occurred.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs and architecture notes were updated.
  • No authentication, credential, request logging, or unsafe-default behavior changed.

Summary by CodeRabbit

  • Bug Fixes

    • Improved streaming reliability for payload-rewrite requests on Windows and macOS by automatically using a bounded relay, regardless of streaming mode.
    • Preserved safe cancellation, buffering, rewrite limits, and completion behavior during interrupted streams.
    • Clarified platform-specific handling for ordinary streams and automatic mode.
  • Documentation

    • Updated troubleshooting and streaming documentation across supported languages to explain relay selection and platform behavior.

@github-actions github-actions Bot added the bug Something isn't working label Aug 3, 2026
@coderabbitai

coderabbitai Bot commented Aug 3, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 449e721f-61b4-4f7f-9c31-7a117a78f4e0

📥 Commits

Reviewing files that changed from the base of the PR and between e247a0d and 2c18223.

📒 Files selected for processing (2)
  • tests/relay-eager.test.ts
  • tests/responses-image-gen-repair.test.ts

📝 Walkthrough

Walkthrough

The change extends eager SSE relay selection from Windows-only payload rewrites to Windows and Darwin. It updates stream-policy documentation and adds coverage for platform selection, large payloads, cancellation cleanup, and completion events.

Changes

Cross-platform rewrite relay

Layer / File(s) Summary
Rewrite safety policy
src/lib/bun-stream-caps.ts, tests/bun-stream-caps.test.ts
requiresEagerRewriteRelay replaces the Windows-only helper and returns true for rewrite traffic on Windows and Darwin. Tests cover supported platforms, Linux, and no-rewrite cases.
Eager relay routing
src/server/responses/core.ts, src/server/index.ts, src/server/relay-eager.ts, structure/04_transports-and-sidecars.md
Passthrough SSE responses select the eager relay for Windows and Darwin rewrite traffic. The relay retains inline rewriting, bounded buffering, continuation ordering, cancellation draining, and rewrite-budget handling.
Relay validation and documentation
tests/relay-eager.test.ts, tests/passthrough-abort.test.ts, tests/responses-image-gen-repair.test.ts, docs-site/src/content/docs/*/troubleshooting/windows-memory.md
Tests cover partial-frame cancellation, large rewritten payloads, platform-specific selection, payload preservation, and single completion events. Troubleshooting pages document the platform-specific streamMode behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant responsesCore
  participant requiresEagerRewriteRelay
  participant relayEager
  Client->>responsesCore: Request passthrough SSE with payload rewrite
  responsesCore->>requiresEagerRewriteRelay: Check platform and rewrite requirement
  requiresEagerRewriteRelay-->>responsesCore: Select eager relay on Windows or Darwin
  responsesCore->>relayEager: Rewrite and stream with bounded buffering
  relayEager-->>Client: Deliver rewritten SSE events
Loading

Possibly related PRs

Suggested reviewers: ingwannu, wibias, lidge-jun

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies the streaming fix and the Darwin rewrite stall addressed by the pull request.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@WZBbiao

WZBbiao commented Aug 3, 2026

Copy link
Copy Markdown
Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: e247a0d43d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@coderabbitai coderabbitai 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.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/relay-eager.test.ts`:
- Around line 273-280: Replace the fixed settle(60) wait in the reader.cancel
test with a promise resolved by hooks.onDone, awaiting that promise before
assertions; retain a separate timeout that fails if relay completion hangs. Keep
the existing abort, budget, cancellation, completion, and synthetic-record
assertions unchanged.
- Around line 258-266: Ensure the test scope around relaySseEagerBounded
disposes the caller-owned budget by adding budget.dispose() in a finally block.
Use the existing budget created by createTranslatorBudget and preserve cleanup
even when the relay assertions or execution fail.

In `@tests/responses-image-gen-repair.test.ts`:
- Around line 347-350: Update the large-payload assertion in the response test
to verify that clientBody contains largeEcho, rather than only comparing their
lengths. Keep the existing isEagerRelaySseResponse assertion unchanged and
preserve the test’s large-payload scenario.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 44347c50-36ae-4a17-9fe3-c404609fe8ca

📥 Commits

Reviewing files that changed from the base of the PR and between 6a7351b and e247a0d.

📒 Files selected for processing (14)
  • docs-site/src/content/docs/ja/troubleshooting/windows-memory.md
  • docs-site/src/content/docs/ko/troubleshooting/windows-memory.md
  • docs-site/src/content/docs/ru/troubleshooting/windows-memory.md
  • docs-site/src/content/docs/troubleshooting/windows-memory.md
  • docs-site/src/content/docs/zh-cn/troubleshooting/windows-memory.md
  • src/lib/bun-stream-caps.ts
  • src/server/index.ts
  • src/server/relay-eager.ts
  • src/server/responses/core.ts
  • structure/04_transports-and-sidecars.md
  • tests/bun-stream-caps.test.ts
  • tests/passthrough-abort.test.ts
  • tests/relay-eager.test.ts
  • tests/responses-image-gen-repair.test.ts

Comment thread tests/relay-eager.test.ts Outdated
Comment thread tests/relay-eager.test.ts Outdated
Comment thread tests/responses-image-gen-repair.test.ts Outdated
@WZBbiao

WZBbiao commented Aug 3, 2026

Copy link
Copy Markdown
Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 2c182230da

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@WZBbiao

WZBbiao commented Aug 3, 2026

Copy link
Copy Markdown
Author

Maintainer action required: GitHub is holding the fork workflows at action_required with zero jobs, so the PR remains UNSTABLE even though every visible check is green.

Please approve and run both workflows. The exact head 2c182230dab8cf09ecf2250a81a32de193d7d91d has already passed the repository pre-push gate locally in an isolated worktree: 7,591 passed, 8 skipped, 0 failed; TypeScript, GUI lint, privacy scan, and React Doctor all passed. CodeRabbit has no remaining actionable comments, all review threads are resolved, and Codex reviewed this head with no major issues.

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

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant