Add js_repl host helpers and exec end events

codex-rs/core/src/project_doc.rs

@@ -42,13 +42,13 @@ fn render_js_repl_instructions(config: &Config) -> Option<String> {
     let mut section = String::from("## JavaScript REPL (Node)\n");
     section.push_str("- Use `js_repl` for Node-backed JavaScript with top-level await in a persistent kernel. `codex.state` persists for the session (best effort) and is cleared by `js_repl_reset`.\n");
     section.push_str("- `js_repl` is a freeform/custom tool. Direct `js_repl` calls must send raw JavaScript tool input (optionally with first-line `// codex-js-repl: timeout_ms=15000`). Do not wrap code in JSON (for example `{\"code\":\"...\"}`), quotes, or markdown code fences.\n");
-    section.push_str("- Helpers available in `js_repl`: `codex.state` and `codex.tmpDir`.\n");
+    section.push_str("- Helpers: `codex.state`, `codex.tmpDir`, and `codex.tool(name, args?)`.\n");
+    section.push_str("- `codex.tool` executes a normal tool call and resolves to the raw tool output object. Use it for shell and non-shell tools alike.\n");
+    section.push_str("- 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.\n");
     section.push_str("- Top-level bindings persist across cells. If you hit `SyntaxError: Identifier 'x' has already been declared`, reuse the binding, pick a new name, wrap in `{ ... }` for block scope, or reset the kernel with `js_repl_reset`.\n");
     section.push_str("- Top-level static import declarations (for example `import x from \"pkg\"`) are currently unsupported in `js_repl`; use dynamic imports with `await import(\"pkg\")` instead.\n");
 
-    section.push_str(
-        "- Avoid direct access to `process.stdout` / `process.stderr` / `process.stdin`; it can corrupt the JSON line protocol. Use `console.log`.",
-    );
+    section.push_str("- Avoid direct access to `process.stdout` / `process.stderr` / `process.stdin`; it can corrupt the JSON line protocol. Use `console.log` and `codex.tool(...)`.");
 
     Some(section)
 }
@@ -409,7 +409,7 @@ mod tests {
         let res = get_user_instructions(&cfg, None)
             .await
             .expect("js_repl instructions expected");
-        let expected = "## JavaScript REPL (Node)\n- Use `js_repl` for Node-backed JavaScript with top-level await in a persistent kernel. `codex.state` persists for the session (best effort) and is cleared by `js_repl_reset`.\n- `js_repl` is a freeform/custom tool. Direct `js_repl` calls must send raw JavaScript tool input (optionally with first-line `// codex-js-repl: timeout_ms=15000`). Do not wrap code in JSON (for example `{\"code\":\"...\"}`), quotes, or markdown code fences.\n- Helpers available in `js_repl`: `codex.state` and `codex.tmpDir`.\n- Top-level bindings persist across cells. If you hit `SyntaxError: Identifier 'x' has already been declared`, reuse the binding, pick a new name, wrap in `{ ... }` for block scope, or reset the kernel with `js_repl_reset`.\n- Top-level static import declarations (for example `import x from \"pkg\"`) are currently unsupported in `js_repl`; use dynamic imports with `await import(\"pkg\")` instead.\n- Avoid direct access to `process.stdout` / `process.stderr` / `process.stdin`; it can corrupt the JSON line protocol. Use `console.log`.";
+        let expected = "## JavaScript REPL (Node)\n- Use `js_repl` for Node-backed JavaScript with top-level await in a persistent kernel. `codex.state` persists for the session (best effort) and is cleared by `js_repl_reset`.\n- `js_repl` is a freeform/custom tool. Direct `js_repl` calls must send raw JavaScript tool input (optionally with first-line `// codex-js-repl: timeout_ms=15000`). Do not wrap code in JSON (for example `{\"code\":\"...\"}`), quotes, or markdown code fences.\n- Helpers: `codex.state`, `codex.tmpDir`, and `codex.tool(name, args?)`.\n- `codex.tool` executes a normal tool call and resolves to the raw tool output object. Use it for shell and non-shell tools alike.\n- 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.\n- Top-level bindings persist across cells. If you hit `SyntaxError: Identifier 'x' has already been declared`, reuse the binding, pick a new name, wrap in `{ ... }` for block scope, or reset the kernel with `js_repl_reset`.\n- Top-level static import declarations (for example `import x from \"pkg\"`) are currently unsupported in `js_repl`; use dynamic imports with `await import(\"pkg\")` instead.\n- Avoid direct access to `process.stdout` / `process.stderr` / `process.stdin`; it can corrupt the JSON line protocol. Use `console.log` and `codex.tool(...)`.";
         assert_eq!(res, expected);
     }
 

codex-rs/core/src/tools/handlers/js_repl.rs

@@ -1,22 +1,98 @@
 use async_trait::async_trait;
 use serde_json::Value as JsonValue;
 use std::sync::Arc;
+use std::time::Duration;
+use std::time::Instant;
 
+use crate::exec::ExecToolCallOutput;
+use crate::exec::StreamOutput;
 use crate::features::Feature;
 use crate::function_tool::FunctionCallError;
+use crate::protocol::ExecCommandSource;
 use crate::tools::context::ToolInvocation;
 use crate::tools::context::ToolOutput;
 use crate::tools::context::ToolPayload;
+use crate::tools::events::ToolEmitter;
+use crate::tools::events::ToolEventCtx;
+use crate::tools::events::ToolEventFailure;
+use crate::tools::events::ToolEventStage;
 use crate::tools::handlers::parse_arguments;
 use crate::tools::js_repl::JS_REPL_PRAGMA_PREFIX;
 use crate::tools::js_repl::JsReplArgs;
 use crate::tools::registry::ToolHandler;
 use crate::tools::registry::ToolKind;
 use codex_protocol::models::FunctionCallOutputBody;
+use codex_protocol::models::FunctionCallOutputContentItem;
 
 pub struct JsReplHandler;
 pub struct JsReplResetHandler;
 
+fn join_outputs(stdout: &str, stderr: &str) -> String {
+    if stdout.is_empty() {
+        stderr.to_string()
+    } else if stderr.is_empty() {
+        stdout.to_string()
+    } else {
+        format!("{stdout}\n{stderr}")
+    }
+}
+
+fn build_js_repl_exec_output(
+    output: &str,
+    error: Option<&str>,
+    duration: Duration,
+) -> ExecToolCallOutput {
+    let stdout = output.to_string();
+    let stderr = error.unwrap_or("").to_string();
+    let aggregated_output = join_outputs(&stdout, &stderr);
+    ExecToolCallOutput {
+        exit_code: if error.is_some() { 1 } else { 0 },
+        stdout: StreamOutput::new(stdout),
+        stderr: StreamOutput::new(stderr),
+        aggregated_output: StreamOutput::new(aggregated_output),
+        duration,
+        timed_out: false,
+    }
+}
+
+async fn emit_js_repl_exec_begin(
+    session: &crate::codex::Session,
+    turn: &crate::codex::TurnContext,
+    call_id: &str,
+) {
+    let emitter = ToolEmitter::shell(
+        vec!["js_repl".to_string()],
+        turn.cwd.clone(),
+        ExecCommandSource::Agent,
+        false,
+    );
+    let ctx = ToolEventCtx::new(session, turn, call_id, None);
+    emitter.emit(ctx, ToolEventStage::Begin).await;
+}
+
+async fn emit_js_repl_exec_end(
+    session: &crate::codex::Session,
+    turn: &crate::codex::TurnContext,
+    call_id: &str,
+    output: &str,
+    error: Option<&str>,
+    duration: Duration,
+) {
+    let exec_output = build_js_repl_exec_output(output, error, duration);
+    let emitter = ToolEmitter::shell(
+        vec!["js_repl".to_string()],
+        turn.cwd.clone(),
+        ExecCommandSource::Agent,
+        false,
+    );
+    let ctx = ToolEventCtx::new(session, turn, call_id, None);
+    let stage = if error.is_some() {
+        ToolEventStage::Failure(ToolEventFailure::Output(exec_output))
+    } else {
+        ToolEventStage::Success(exec_output)
+    };
+    emitter.emit(ctx, stage).await;
+}
 #[async_trait]
 impl ToolHandler for JsReplHandler {
     fn kind(&self) -> ToolKind {
@@ -36,6 +112,7 @@ impl ToolHandler for JsReplHandler {
             turn,
             tracker,
             payload,
+            call_id,
             ..
         } = invocation;
 
@@ -55,12 +132,45 @@ impl ToolHandler for JsReplHandler {
             }
         };
         let manager = turn.js_repl.manager().await?;
+        let started_at = Instant::now();
+        emit_js_repl_exec_begin(session.as_ref(), turn.as_ref(), &call_id).await;
         let result = manager
             .execute(Arc::clone(&session), Arc::clone(&turn), tracker, args)
-            .await?;
+            .await;
+        let result = match result {
+            Ok(result) => result,
+            Err(err) => {
+                let message = err.to_string();
+                emit_js_repl_exec_end(
+                    session.as_ref(),
+                    turn.as_ref(),
+                    &call_id,
+                    "",
+                    Some(&message),
+                    started_at.elapsed(),
+                )
+                .await;
+                return Err(err);
+            }
+        };
+
+        let content = result.output;
+        let items = vec![FunctionCallOutputContentItem::InputText {
+            text: content.clone(),
+        }];
+
+        emit_js_repl_exec_end(
+            session.as_ref(),
+            turn.as_ref(),
+            &call_id,
+            &content,
+            None,
+            started_at.elapsed(),
+        )
+        .await;
 
         Ok(ToolOutput::Function {
-            body: FunctionCallOutputBody::Text(result.output),
+            body: FunctionCallOutputBody::ContentItems(items),
             success: Some(true),
         })
     }
@@ -175,7 +285,12 @@ fn reject_json_or_quoted_source(code: &str) -> Result<(), FunctionCallError> {
 
 #[cfg(test)]
 mod tests {
+    use std::time::Duration;
+
     use super::parse_freeform_args;
+    use crate::codex::make_session_and_context_with_rx;
+    use crate::protocol::EventMsg;
+    use crate::protocol::ExecCommandSource;
     use pretty_assertions::assert_eq;
 
     #[test]
@@ -221,4 +336,43 @@ mod tests {
             "js_repl is a freeform tool and expects raw JavaScript source. Resend plain JS only (optional first line `// codex-js-repl: ...`); do not send JSON (`{\"code\":...}`), quoted code, or markdown fences."
         );
     }
+
+    #[tokio::test]
+    async fn emit_js_repl_exec_end_sends_event() {
+        let (session, turn, rx) = make_session_and_context_with_rx().await;
+        super::emit_js_repl_exec_end(
+            session.as_ref(),
+            turn.as_ref(),
+            "call-1",
+            "hello",
+            None,
+            Duration::from_millis(12),
+        )
+        .await;
+
+        let event = tokio::time::timeout(Duration::from_secs(5), async {
+            loop {
+                let event = rx.recv().await.expect("event");
+                if let EventMsg::ExecCommandEnd(end) = event.msg {
+                    break end;
+                }
+            }
+        })
+        .await
+        .expect("timed out waiting for exec end");
+
+        assert_eq!(event.call_id, "call-1");
+        assert_eq!(event.turn_id, turn.sub_id);
+        assert_eq!(event.command, vec!["js_repl".to_string()]);
+        assert_eq!(event.cwd, turn.cwd);
+        assert_eq!(event.source, ExecCommandSource::Agent);
+        assert_eq!(event.interaction_input, None);
+        assert_eq!(event.stdout, "hello");
+        assert_eq!(event.stderr, "");
+        assert!(event.aggregated_output.contains("hello"));
+        assert_eq!(event.exit_code, 0);
+        assert_eq!(event.duration, Duration::from_millis(12));
+        assert!(event.formatted_output.contains("hello"));
+        assert!(!event.parsed_cmd.is_empty());
+    }
 }