rad/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-03-05 21:45:28 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
42e22f3bde6c851422eb4f7b502457fe86ba91db
codex/docs/js_repl.md
Curtis 'Fjord' Hawthorne 42e22f3bde Add feature-gated freeform js_repl core runtime (#10674) 
## Summary

This PR adds an **experimental, feature-gated `js_repl` core runtime**
so models can execute JavaScript in a persistent REPL context across
tool calls.

The implementation integrates with existing feature gating, tool
registration, prompt composition, config/schema docs, and tests.

## What changed

- Added new experimental feature flag: `features.js_repl`.
- Added freeform `js_repl` tool and companion `js_repl_reset` tool.
- Gated tool availability behind `Feature::JsRepl`.
- Added conditional prompt-section injection for JS REPL instructions
via marker-based prompt processing.
- Implemented JS REPL handlers, including freeform parsing and pragma
support (timeout/reset controls).
- Added runtime resolution order for Node:
  1. `CODEX_JS_REPL_NODE_PATH`
  2. `js_repl_node_path` in config
  3. `PATH`
- Added JS runtime assets/version files and updated docs/schema.

## Why

This enables richer agent workflows that require incremental JavaScript
execution with preserved state, while keeping rollout safe behind an
explicit feature flag.

## Testing

Coverage includes:

- Feature-flag gating behavior for tool exposure.
- Freeform parser/pragma handling edge cases.
- Runtime behavior (state persistence across calls and top-level `await`
support).

## Usage

```toml
[features]
js_repl = true
```

Optional runtime override:

- `CODEX_JS_REPL_NODE_PATH`, or
- `js_repl_node_path` in config.

#### [git stack](https://github.com/magus/git-stack-cli)
- 👉 `1` https://github.com/openai/codex/pull/10674
- ⏳ `2` https://github.com/openai/codex/pull/10672
- ⏳ `3` https://github.com/openai/codex/pull/10671
- ⏳ `4` https://github.com/openai/codex/pull/10673
- ⏳ `5` https://github.com/openai/codex/pull/10670
2026-02-11 12:05:02 -08:00

2.0 KiB
Raw Blame History

JavaScript REPL (js_repl)

js_repl runs JavaScript in a persistent Node-backed kernel with top-level await.

Feature gate

js_repl is disabled by default and only appears when:

[features]
js_repl = true

Node runtime

js_repl requires a Node version that meets or exceeds codex-rs/node-version.txt.

Runtime resolution order:

  1. CODEX_JS_REPL_NODE_PATH environment variable
  2. js_repl_node_path in config/profile
  3. node discovered on PATH

You can configure an explicit runtime path:

js_repl_node_path = "/absolute/path/to/node"

Usage

  • js_repl is a freeform tool: send raw JavaScript source text.
  • Optional first-line pragma:
    • // codex-js-repl: timeout_ms=15000
  • Top-level bindings persist across calls.
  • Top-level static import declarations (for example import x from "pkg") are currently unsupported; use dynamic imports with await import("pkg").
  • Use js_repl_reset to clear kernel state.

Vendored parser asset (meriyah.umd.min.js)

The kernel embeds a vendored Meriyah bundle at:

  • codex-rs/core/src/tools/js_repl/meriyah.umd.min.js

Current source is meriyah@7.0.0 from npm (dist/meriyah.umd.min.js). Licensing is tracked in:

  • third_party/meriyah/LICENSE
  • NOTICE

How this file was sourced

From a clean temp directory:

tmp="$(mktemp -d)"
cd "$tmp"
npm pack meriyah@7.0.0
tar -xzf meriyah-7.0.0.tgz
cp package/dist/meriyah.umd.min.js /path/to/repo/codex-rs/core/src/tools/js_repl/meriyah.umd.min.js
cp package/LICENSE.md /path/to/repo/third_party/meriyah/LICENSE

How to update to a newer version

  1. Replace 7.0.0 in the commands above with the target version.
  2. Copy the new dist/meriyah.umd.min.js into codex-rs/core/src/tools/js_repl/meriyah.umd.min.js.
  3. Copy the package license into third_party/meriyah/LICENSE.
  4. Update the version string in the header comment at the top of meriyah.umd.min.js.
  5. Update NOTICE if the upstream copyright notice changed.
  6. Run the relevant js_repl tests.