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.
This commit is contained in:
Curtis 'Fjord' Hawthorne
2026-02-26 10:12:28 -08:00
committed by GitHub
parent d3603ae5d3
commit eb77db2957
2 changed files with 338 additions and 19 deletions

View File

@@ -65,10 +65,38 @@ For `CODEX_JS_REPL_NODE_MODULE_DIRS` and `js_repl_node_module_dirs`, module reso
- `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:
```sh
RUST_LOG=codex_core::tools::js_repl=info \
LOG_FORMAT=json \
codex app-server \
2> /tmp/codex-app-server.log
```
```sh
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: