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
bschoepke/ps-repl
codex/docs/js_repl.md
Curtis 'Fjord' Hawthorne eb77db2957 Log js_repl nested tool responses in rollout history (#12837) 
## Summary

- add tracing-based diagnostics for nested `codex.tool(...)` calls made
from `js_repl`
- emit a bounded, sanitized summary at `info!`
- emit the exact raw serialized response object or error string seen by
JavaScript at `trace!`
- document how to enable these logs and where to find them, especially
for `codex app-server`

## Why

Nested `codex.tool(...)` calls inside `js_repl` are a debugging
boundary: JavaScript sees the tool result, but that result is otherwise
hard to inspect from outside the kernel.

This change adds explicit tracing for that path using the repo’s normal
observability pattern:
- `info` for compact summaries
- `trace` for exact raw payloads when deep debugging is needed

## What changed

- `js_repl` now summarizes nested tool-call results across the response
shapes it can receive:
  - message content
  - function-call outputs
  - custom tool outputs
  - MCP tool results and MCP error results
  - direct error strings
- each nested `codex.tool(...)` completion logs:
  - `exec_id`
  - `tool_call_id`
  - `tool_name`
  - `ok`
  - a bounded summary struct describing the payload shape
- at `trace`, the same path also logs the exact serialized response
object or error string that JavaScript received
- docs now include concrete logging examples for `codex app-server`
- unit coverage was added for multimodal function output summaries and
error summaries

## How to use it

### Summary-only logging

Set:

```sh
RUST_LOG=codex_core::tools::js_repl=info
```

For `codex app-server`, tracing output is written to the server process
`stderr`.

Example:

```sh
RUST_LOG=codex_core::tools::js_repl=info \
LOG_FORMAT=json \
codex app-server \
2> /tmp/codex-app-server.log
```

This emits bounded summary lines for nested `codex.tool(...)` calls.

### Full raw debugging

Set:

```sh
RUST_LOG=codex_core::tools::js_repl=trace
```

Example:

```sh
RUST_LOG=codex_core::tools::js_repl=trace \
LOG_FORMAT=json \
codex app-server \
2> /tmp/codex-app-server.log
```

At `trace`, you get:
- the same `info` summary line
- a `trace` line with the exact serialized response object seen by
JavaScript
- or the exact error string if the nested tool call failed

### Where the logs go

For `codex app-server`, these logs go to process `stderr`, so redirect
or capture `stderr` to inspect them.

Example:

```sh
RUST_LOG=codex_core::tools::js_repl=trace \
LOG_FORMAT=json \
/Users/fjord/code/codex/codex-rs/target/debug/codex app-server \
2> /tmp/codex-app-server.log
```

Then inspect:

```sh
rg "js_repl nested tool call" /tmp/codex-app-server.log
```

Without an explicit `RUST_LOG` override, these `js_repl` nested
tool-call logs are typically not visible.
2026-02-26 10:12:28 -08:00

4.4 KiB
Raw Permalink 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

js_repl_tools_only can be enabled to force direct model tool calls through js_repl:

[features]
js_repl = true
js_repl_tools_only = true

When enabled, direct model tool calls are restricted to js_repl and js_repl_reset; other tools remain available via await codex.tool(...) inside js_repl.

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"

Module resolution

js_repl resolves bare specifiers (for example await import("pkg")) using an ordered search path. Path-style specifiers (./, ../, absolute paths, file: URLs) are rejected.

Module resolution proceeds in the following order:

  1. CODEX_JS_REPL_NODE_MODULE_DIRS (PATH-delimited list)
  2. js_repl_node_module_dirs in config/profile (array of absolute paths)
  3. Thread working directory (cwd, always included as the last fallback)

For CODEX_JS_REPL_NODE_MODULE_DIRS and js_repl_node_module_dirs, module resolution is attempted in the order provided with earlier entries taking precedence.

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 the kernel state.

Helper APIs inside the kernel

js_repl exposes these globals:

  • codex.tmpDir: per-session scratch directory path.
  • codex.tool(name, args?): executes a normal Codex tool call from inside js_repl (including shell tools like shell / shell_command when available).
  • Each codex.tool(...) call emits a bounded summary at info level from the codex_core::tools::js_repl logger. At trace level, the same path also logs the exact raw response object or error string seen by JavaScript.
  • To share generated images with the model, write a file under codex.tmpDir, call await codex.tool("view_image", { path: "/absolute/path" }), then delete the file.

Avoid writing directly to process.stdout / process.stderr / process.stdin; the kernel uses a JSON-line transport over stdio.

Debug logging

Nested codex.tool(...) diagnostics are emitted through normal tracing output instead of rollout history.

  • info level logs a bounded summary.
  • trace level also logs the exact serialized response object or error string seen by JavaScript.

For codex app-server, these logs are written to the server process stderr.

Examples:

RUST_LOG=codex_core::tools::js_repl=info \
LOG_FORMAT=json \
codex app-server \
2> /tmp/codex-app-server.log

RUST_LOG=codex_core::tools::js_repl=trace \
LOG_FORMAT=json \
codex app-server \
2> /tmp/codex-app-server.log

In both cases, inspect /tmp/codex-app-server.log or whatever sink captures the process stderr.

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.