open-design/docs/testing/codex-patch-streaming.md

Codex file preview compatibility and validation

OD consumes the official item/fileChange/patchUpdated notification from the installed Codex CLI's built-in app-server. It does not require a companion binary. Configuration is passed on thread/start and thread/resume, without rewriting the user's persistent Codex configuration.

Version boundary

• 0.123.0 is the first stable release with app-server forwarding: release changelog, upstream #18289.
• 0.122.0 contains an internal patch event but does not forward it to app-server clients. Enabling the internal flag alone cannot provide OD previews.
• OD reads the server version from the first token of initialize.userAgent. Stable versions >= 0.123.0 receive config: { "features.apply_patch_streaming_events": true }. Older, unrecognized, and prerelease builds receive no override and retain completion-only file events. Other versions in the user-agent string are not treated as the server version.
• Patch streaming does not require experimentalApi. The existing thread-visibility policy independently enables that capability for owned paginated histories. Missing preview notifications preserve the existing final-file behavior.
• This feature only covers structured apply_patch input. It does not expose incremental arguments of exec_command or shell heredocs.

Automated acceptance

Run from the repository root with an ordinary installed Codex binary:

OD_E2E_CODEX_BIN="$(command -v codex)" corepack pnpm --filter @open-design/e2e test tests/dialog/codex-patch-stream.test.ts

The test is explicitly skipped without OD_E2E_CODEX_BIN. It starts the shared tools-dev harness with an isolated Codex configuration and a local Responses fixture; no provider account is required. It holds back the second half of a roughly 125 KB patch until OD reports the real file target. Delaying command stdout would not test this requirement. Assertions cover:

• The actual provider user-agent matches the requested CLI version.
• A Write preview arrives while patch arguments are still incomplete.
• The written file exactly matches the expected content.
• The final tool call and result share the preview's identity, with no duplicates.
• The run succeeds and a follow-up resumes the same Codex session.

Focused daemon tests cover the 0.122/0.123 feature boundary, unknown/prerelease versions, start/resume configuration, relative versus absolute paths, changing file order, repeated snapshots, failed execution, cancellation, late events, legacy fallback, and bounded preview payloads:

corepack pnpm --filter @open-design/daemon exec vitest run tests/codex-app-server-patch-stream.test.ts tests/codex-app-server-session.test.ts tests/codex-app-server-normalize.test.ts tests/codex-app-server-parity.test.ts tests/codex-app-server-command-output-stream.test.ts tests/codex-app-server-transport-switch.test.ts tests/codex-app-server-protocol-contract.test.ts

Local validation on 2026-09-11

• Ordinary CLI 0.149.1 and installed 0.153.4 passed the automated acceptance, including file integrity, matching tool identities, and resume.
• A separate browser check with 0.153.4 streamed 124,764 bytes in 40 chunks over 40.097 seconds. OD emitted its first file preview 7 ms after the first argument chunk. At 15 seconds the browser already displayed the file row while the arguments remained incomplete. The final file matched exactly. These timings use a controlled local provider, not a live model benchmark.
• The downloaded official 0.123.0 macOS binaries exited with code 137 even for --version on this machine. The version boundary is verified by the release and tagged source, not by a successful 0.123.0 runtime test. This remains a validation gap; the 0.149.1 result must not be relabeled as a 0.123.0 pass.