This repository tracks the plan and research for a wasm-compatible Codex agent core that can run in a browser environment.

Upstream Codex is kept as a git submodule at external/codex so implementation and tests can stay close to the original source.

git submodule update --init --recursive

• PLAN.md

  • Implementation outline for the wasm agent core.
  • Focuses on session/turn handling, model event streams, tool orchestration, approval flow, and host capability traits.

• AGENTS.md

  • Project instructions for future implementation work.
  • Defines the upstream reuse priority and required test strategy.

• docs/wasm-core-harness.md

  • Two-layer test strategy: Rust unit/compile gate plus Bun/Playwright browser integration.
  • Describes how to compare our wasm core against upstream Codex oracle behavior, including the tool-backed native core oracle runner.

• docs/codex-rs-core-wasm-feasibility.md

  • Evaluates whether codex-rs/core can be compiled or refactored to WebAssembly.
  • Lists reusable parts, native blockers, and required browser abstractions.

• docs/browser-runtime-architecture.md

  • Earlier browser runtime architecture research.
  • Useful background for host adapters, but not the primary wasm core plan.

Do not compile external/codex/codex-rs/core wholesale to wasm. Instead, build a narrow wasm-compatible core that imports or mirrors upstream Codex behavior wherever practical:

1. import external
2. copy/paste raw code
3. mock/inject host capabilities
4. edit Codex source only for small feature gates
5. implement behavior ourselves only as a last resort

The core should own agent behavior only. Browser UI, product packaging, model proxy services, sandbox parity, git integration, and runtime persistence adapters stay outside the core crate.

bun run check
cargo test -p codex-browser-core
scripts/test-integration.sh

bun run check includes formatting, TypeScript/Rust type checks, linting, and an upstream drift check for copied apply-patch grammar, unified exec constants, copied truncation helper bodies, and TS oracle truncation goldens.

Default conformance/e2e runs intentionally avoid the no_tool fixture; streamed text and reasoning coverage are wrapped in exec_command tool turns. Native upstream core checks start from tool-backed cases such as streamed_assistant_text_delta, reasoning_delta, early_stream_close_retry, unsupported_custom_tool, unsupported_function_tool, exec_success, exec_native_truncation, exec_denied, multiple_tool_calls, early_stream_close_tool_retry, parallel_tool_calls_disabled, apply_patch_add_update_delete, apply_patch_move, apply_patch_end_of_file, apply_patch_multiple_chunks, and invalid_apply_patch. Browser-only oracle cases cover additional tool-backed boundaries such as client tool_search, invalid exec arguments, sandbox escalation rejection, write_stdin input/poll, scripted exec truncation, and invalid UTF-8 exec output.

Canonical Playwright traces also compare scripted HostExec request payloads and HostApprovals request/decision payloads, so tool-backed cases validate both model-visible behavior and the browser host boundary. Browser wasm stream tests also cover approval callback rejection becoming a model-visible denied tool output without invoking HostExec.

Provider compatibility fallback is isolated to the live provider adapter. The default tool mode keeps upstream-style custom/freeform apply_patch; selecting applyPatchFunction rewrites only live provider request/response wire shapes so providers that cannot emit custom_tool_call can still smoke-test patch turns without changing conformance specs.

Browser adapter e2e also runs WebContainerHostExec directly against a real WebContainer for long-running process start, stdin write, polling, TTY resize, kill, and cleanup after exit/kill. The web app e2e cases are split by behavior and each starts from at least one tool call, covering reload restore, empty workspace restore, large binary snapshot restore, OPFS snapshot edge restore, multi-session history, recently updated history ordering, history rename persistence, rapid history restore serialization, and corrupt/missing snapshot fallback.