Code Mode and JavaScript REPL

Relevant source files

• codex-rs/code-mode-protocol/src/description.rs
• codex-rs/code-mode-protocol/src/session.rs
• codex-rs/code-mode/Cargo.toml
• codex-rs/code-mode/src/cell_actor/callbacks.rs
• codex-rs/code-mode/src/cell_actor/callbacks_tests.rs
• codex-rs/code-mode/src/cell_actor/conversions.rs
• codex-rs/code-mode/src/cell_actor/mod.rs
• codex-rs/code-mode/src/cell_actor/tests.rs
• codex-rs/code-mode/src/cell_actor/types.rs
• codex-rs/code-mode/src/lib.rs
• codex-rs/code-mode/src/remote_session/connection/driver/delegate_runtime.rs
• codex-rs/code-mode/src/remote_session/connection/driver_tests.rs
• codex-rs/code-mode/src/remote_session/connection/reader.rs
• codex-rs/code-mode/src/runtime/callbacks.rs
• codex-rs/code-mode/src/runtime/globals.rs
• codex-rs/code-mode/src/runtime/mod.rs
• codex-rs/code-mode/src/runtime/value.rs
• codex-rs/code-mode/src/service.rs
• codex-rs/code-mode/src/service_contract_tests.rs
• codex-rs/code-mode/src/service_tests.rs
• codex-rs/code-mode/src/session_runtime/mod.rs
• codex-rs/code-mode/src/session_runtime/tests.rs
• codex-rs/code-mode/src/session_runtime/types.rs
• codex-rs/code-mode/src/v8_init.rs
• codex-rs/code-mode/tests/jit.rs
• codex-rs/core/src/stream_events_utils_tests.rs
• codex-rs/core/src/tools/code_mode/execute_handler.rs
• codex-rs/core/src/tools/code_mode/execute_spec.rs
• codex-rs/core/src/tools/code_mode/mod.rs
• codex-rs/core/src/tools/code_mode/wait_handler.rs
• codex-rs/core/src/tools/context.rs
• codex-rs/core/src/tools/context_tests.rs
• codex-rs/core/src/tools/handlers/dynamic.rs
• codex-rs/core/src/tools/handlers/mcp.rs
• codex-rs/core/src/tools/parallel.rs
• codex-rs/core/src/tools/registry.rs
• codex-rs/core/src/tools/registry_tests.rs
• codex-rs/core/src/tools/router.rs
• codex-rs/core/src/tools/router_tests.rs
• codex-rs/core/src/tools/spec_plan.rs
• codex-rs/core/src/tools/spec_plan_tests.rs
• codex-rs/core/src/tools/tool_dispatch_trace_tests.rs
• codex-rs/core/tests/suite/code_mode.rs

This page documents the JavaScript execution systems in Codex, focusing on the yielding execution model of Code Mode, its orchestration of nested tools, and the integration of V8 isolates for stateful REPL interactions.

---

Overview and Feature Gates

Code Mode and its associated REPL capabilities are controlled by feature flags and runtime configurations. These flags determine the availability of tools and the visibility of nested tool definitions to the model.

Feature / State	Effect
Feature::CodeMode	Enables the exec and wait tools for yielding JavaScript execution. codex-rs/core/tests/suite/code_mode.rs193
ToolMode::CodeMode	A runtime state for a turn where the model is expected to use JavaScript for tool interaction. codex-rs/core/src/tools/code_mode/mod.rs160-161
Feature::CodeModeBufferedExec	Enables a specific yield time override (default 30s) for buffered execution. codex-rs/core/src/tools/code_mode/mod.rs57-63

Sources: codex-rs/core/tests/suite/code_mode.rs193 codex-rs/core/src/tools/code_mode/mod.rs57-63 codex-rs/core/src/tools/code_mode/mod.rs160-161

---

Code Mode System

Purpose and Architecture

Code Mode provides a yielding execution model for JavaScript. It allows scripts to run in a V8 isolate, yield control back to the model (for example, to wait for an external event or async tool output), and maintain execution state across multiple turns using CellId management. codex-rs/core/src/tools/code_mode/mod.rs76-82

Code Mode System Architecture (Natural Language to Code Entity Space)

Sources: codex-rs/core/src/tools/code_mode/mod.rs76-82 codex-rs/core/src/tools/code_mode/mod.rs103-111 codex-rs/code-mode/src/service.rs114-136 codex-rs/code-mode/src/service.rs87-89

Tool Registration and Specs

Code Mode tools are registered via CodeModeExecuteHandler and CodeModeWaitHandler. The exec tool allows execution of JS in a persistent session, while wait allows polling for results from yielded scripts. codex-rs/core/src/tools/code_mode/mod.rs50-52

Constant	Value	Handler Class	Purpose
PUBLIC_TOOL_NAME	"exec"	CodeModeExecuteHandler	Execute JS in a V8 isolate. Supports raw source text. codex-rs/core/src/tools/code_mode/mod.rs54
WAIT_TOOL_NAME	"wait"	CodeModeWaitHandler	Resume or poll a yielded cell using a cell_id. codex-rs/core/src/tools/code_mode/mod.rs55

Pragma and Parameters: The exec tool supports yielding execution where a script can be suspended and resumed. The DEFAULT_WAIT_YIELD_TIME_MS is used to define how long a cell should run before yielding control. codex-rs/core/src/tools/code_mode/mod.rs56

Sources: codex-rs/core/src/tools/code_mode/mod.rs50-56 codex-rs/core/src/tools/spec_plan.rs10-11

---

Tool Orchestration and Nested Calls

Code Mode acts as an orchestrator for other tools, allowing complex logic to be defined in JS and executed against the Codex toolset.

Nested Tool Discovery

Tools are exposed to the V8 environment via the CodeModeDispatchBroker, which provides the infrastructure for these nested calls, ensuring that tools executed from within Code Mode are routed correctly back to the core session. codex-rs/core/src/tools/code_mode/mod.rs89-93

CodeModeSessionDelegate and Tool Invocation

The CodeModeDispatchBroker acts as the bridge between the V8 isolate and the Codex tool registry. codex-rs/core/src/tools/code_mode/mod.rs152-173

1. Tool Dispatch: When the JS script executes a tool, the request is routed through the CodeModeDispatchWorker. codex-rs/core/src/tools/code_mode/mod.rs158-173
2. Context Management: The ExecContext holds references to the Session and TurnContext required to resolve tool permissions and state. codex-rs/core/src/tools/code_mode/mod.rs71-74

Nested Tool Data Flow (Natural Language to Code Entity Space)

Sources: codex-rs/core/src/tools/code_mode/mod.rs152-173 codex-rs/core/src/tools/router.rs180-199 codex-rs/core/src/tools/code_mode/mod.rs71-74

---

Execution Management and State

Cell Management

The CodeModeService manages the lifecycle of execution cells. codex-rs/core/src/tools/code_mode/mod.rs76-82 It tracks active cells and provides methods to execute, wait, and terminate them by interacting with the CodeModeSession. codex-rs/core/src/tools/code_mode/mod.rs103-125

Multi-Session Support

To maintain state across different exec calls within the same session, the CodeModeService maintains a CodeModeSession created by a CodeModeSessionProvider. codex-rs/core/src/tools/code_mode/mod.rs77-78 This allows the JS environment to persist variable bindings and stored values between turns. codex-rs/code-mode/src/service.rs74-85

Truncation and Sanitization

Results from Code Mode are subject to:

• Truncation: Output is limited using TruncationPolicy and truncate_function_output_items_with_policy to prevent context window overflow. codex-rs/core/src/tools/code_mode/mod.rs44-46
• Image Sanitization: Image detail requests are filtered based on session permissions using can_request_original_image_detail. codex-rs/core/src/tools/code_mode/mod.rs28-29

---

JavaScript REPL Integration

The system supports a persistent REPL-like experience where variable bindings and state are maintained across calls.

• Yield Control Pattern: Scripts can yield control back to the model while remaining active in the background. This is handled by the wait tool and the WaitOutcome logic. codex-rs/core/src/tools/code_mode/mod.rs113-119 codex-rs/code-mode/src/service.rs158-193
• Grace Periods: The system implements a YIELD_GRACE_PERIOD (1 second) for long-running scripts (over 10 seconds) to allow clean yielding. codex-rs/code-mode/src/service.rs32-42
• Parallelism: Code Mode execution interacts with the ToolCallRuntime, which manages whether tool calls can run in parallel or must be serialized using parallel_execution locks. codex-rs/core/src/tools/parallel.rs42-49 codex-rs/core/src/tools/parallel.rs133-137

Sources: codex-rs/core/src/tools/code_mode/mod.rs113-119 codex-rs/core/src/tools/parallel.rs42-49 codex-rs/core/src/tools/parallel.rs133-137 codex-rs/code-mode/src/service.rs32-42 codex-rs/code-mode/src/service.rs158-193