Add feature-gated js_repl polling flow

git-stack-id: fjord/js_repl_seq---4hn_deh_pjc2v_
git-stack-title: Add feature-gated js_repl polling flow

Author: fjord-oai

codex-rs/core/config.schema.json

@@ -193,6 +193,9 @@
             "js_repl": {
               "type": "boolean"
             },
+            "js_repl_polling": {
+              "type": "boolean"
+            },
             "js_repl_tools_only": {
               "type": "boolean"
             },
@@ -1223,6 +1226,9 @@
         "js_repl": {
           "type": "boolean"
         },
+        "js_repl_polling": {
+          "type": "boolean"
+        },
         "js_repl_tools_only": {
           "type": "boolean"
         },

codex-rs/core/gpt-5.2-codex_prompt.md

@@ -12,6 +12,11 @@ You are Codex, based on GPT-5. You are running as a coding agent in the Codex CL
 - `codex.sh` requires a string command and resolves to `{ stdout, stderr, exitCode }`; `codex.tool` executes a normal tool call and resolves to the raw tool output object.
 - 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.
 - 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.
+<!-- js_repl_polling:start -->
+- Polling mode is two-step: (1) call `js_repl` with first-line pragma `// codex-js-repl: poll=true` to get an `exec_id`; (2) call `js_repl_poll` with that `exec_id` until `status` is `completed` or `error`.
+- `js_repl_poll` must not be called before a successful `js_repl` submission returns an `exec_id`.
+- If `js_repl` rejects your payload format, resend raw JS with the pragma; do not retry with JSON, quoted strings, or markdown fences.
+<!-- js_repl_polling:end -->
 <!-- js_repl_tools_only:start -->
 - Do not call tools directly; use `js_repl` + `codex.tool(...)`, and use `codex.sh(...)` for shell commands instead of direct shell tool calls.
 - Tools available via `codex.tool(...)`: {{JS_REPL_TOOL_LIST}}. MCP tools (if any) can also be called by name.

codex-rs/core/gpt_5_codex_prompt.md

@@ -12,6 +12,11 @@ You are Codex, based on GPT-5. You are running as a coding agent in the Codex CL
 - `codex.sh` requires a string command and resolves to `{ stdout, stderr, exitCode }`; `codex.tool` executes a normal tool call and resolves to the raw tool output object.
 - 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.
 - 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.
+<!-- js_repl_polling:start -->
+- Polling mode is two-step: (1) call `js_repl` with first-line pragma `// codex-js-repl: poll=true` to get an `exec_id`; (2) call `js_repl_poll` with that `exec_id` until `status` is `completed` or `error`.
+- `js_repl_poll` must not be called before a successful `js_repl` submission returns an `exec_id`.
+- If `js_repl` rejects your payload format, resend raw JS with the pragma; do not retry with JSON, quoted strings, or markdown fences.
+<!-- js_repl_polling:end -->
 <!-- js_repl_tools_only:start -->
 - Do not call tools directly; use `js_repl` + `codex.tool(...)`, and use `codex.sh(...)` for shell commands instead of direct shell tool calls.
 - Tools available via `codex.tool(...)`: {{JS_REPL_TOOL_LIST}}. MCP tools (if any) can also be called by name.

codex-rs/core/prompt.md

@@ -16,6 +16,11 @@ Within this context, Codex refers to the open-source agentic coding interface (n
 - `codex.sh` requires a string command and resolves to `{ stdout, stderr, exitCode }`; `codex.tool` executes a normal tool call and resolves to the raw tool output object.
 - 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.
 - 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.
+<!-- js_repl_polling:start -->
+- Polling mode is two-step: (1) call `js_repl` with first-line pragma `// codex-js-repl: poll=true` to get an `exec_id`; (2) call `js_repl_poll` with that `exec_id` until `status` is `completed` or `error`.
+- `js_repl_poll` must not be called before a successful `js_repl` submission returns an `exec_id`.
+- If `js_repl` rejects your payload format, resend raw JS with the pragma; do not retry with JSON, quoted strings, or markdown fences.
+<!-- js_repl_polling:end -->
 <!-- js_repl_tools_only:start -->
 - Do not call tools directly; use `js_repl` + `codex.tool(...)`, and use `codex.sh(...)` for shell commands instead of direct shell tool calls.
 - Tools available via `codex.tool(...)`: {{JS_REPL_TOOL_LIST}}. MCP tools (if any) can also be called by name.

codex-rs/core/prompt_with_apply_patch_instructions.md

@@ -16,6 +16,11 @@ Within this context, Codex refers to the open-source agentic coding interface (n
 - `codex.sh` requires a string command and resolves to `{ stdout, stderr, exitCode }`; `codex.tool` executes a normal tool call and resolves to the raw tool output object.
 - 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.
 - 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.
+<!-- js_repl_polling:start -->
+- Polling mode is two-step: (1) call `js_repl` with first-line pragma `// codex-js-repl: poll=true` to get an `exec_id`; (2) call `js_repl_poll` with that `exec_id` until `status` is `completed` or `error`.
+- `js_repl_poll` must not be called before a successful `js_repl` submission returns an `exec_id`.
+- If `js_repl` rejects your payload format, resend raw JS with the pragma; do not retry with JSON, quoted strings, or markdown fences.
+<!-- js_repl_polling:end -->
 <!-- js_repl_tools_only:start -->
 - Do not call tools directly; use `js_repl` + `codex.tool(...)`, and use `codex.sh(...)` for shell commands instead of direct shell tool calls.
 - Tools available via `codex.tool(...)`: {{JS_REPL_TOOL_LIST}}. MCP tools (if any) can also be called by name.

codex-rs/core/src/codex.rs

@@ -4709,7 +4709,11 @@ mod tests {
     use crate::config::ConfigBuilder;
     use crate::config::test_config;
     use crate::exec::ExecToolCallOutput;
+    use crate::features::Feature;
     use crate::function_tool::FunctionCallError;
+    use crate::models_manager::model_info::apply_js_repl_polling_section;
+    use crate::models_manager::model_info::apply_js_repl_section;
+    use crate::models_manager::model_info::apply_js_repl_tools_only_section;
     use crate::shell::default_user_shell;
     use crate::tools::format_exec_output_str;
 
@@ -4826,9 +4830,17 @@ mod tests {
         ];
 
         let (session, _turn_context) = make_session_and_context().await;
+        let config = test_config();
+        let js_repl_enabled = config.features.enabled(Feature::JsRepl);
+        let prompt_with_apply_patch_instructions = apply_js_repl_tools_only_section(
+            &apply_js_repl_polling_section(
+                &apply_js_repl_section(prompt_with_apply_patch_instructions, js_repl_enabled),
+                js_repl_enabled && config.features.enabled(Feature::JsReplPolling),
+            ),
+            js_repl_enabled && config.features.enabled(Feature::JsReplToolsOnly),
+        );
 
         for test_case in test_cases {
-            let config = test_config();
             let model_info = ModelsManager::construct_model_info_offline(test_case.slug, &config);
             if test_case.expects_apply_patch_instructions {
                 assert_eq!(

codex-rs/core/src/features.rs

@@ -80,6 +80,8 @@ pub enum Feature {
     // Experimental
     /// Enable JavaScript REPL tools backed by a persistent Node kernel.
     JsRepl,
+    /// Enable js_repl polling helpers and tool.
+    JsReplPolling,
     /// Only expose js_repl tools directly to the model.
     JsReplToolsOnly,
     /// Use the single unified PTY-backed exec tool.
@@ -326,6 +328,10 @@ impl Features {
             tracing::warn!("js_repl_tools_only requires js_repl; disabling js_repl_tools_only");
             features.disable(Feature::JsReplToolsOnly);
         }
+        if features.enabled(Feature::JsReplPolling) && !features.enabled(Feature::JsRepl) {
+            tracing::warn!("js_repl_polling requires js_repl; disabling js_repl_polling");
+            features.disable(Feature::JsReplPolling);
+        }
 
         features
     }
@@ -432,6 +438,16 @@ pub const FEATURES: &[FeatureSpec] = &[
         },
         default_enabled: false,
     },
+    FeatureSpec {
+        id: Feature::JsReplPolling,
+        key: "js_repl_polling",
+        stage: Stage::Experimental {
+            name: "JS REPL polling",
+            menu_description: "Allow js_repl to return an exec_id and poll for completion.",
+            announcement: "NEW! Try polling mode for JavaScript REPL long-running cells.",
+        },
+        default_enabled: false,
+    },
     FeatureSpec {
         id: Feature::JsReplToolsOnly,
         key: "js_repl_tools_only",

codex-rs/core/src/models_manager/model_info.rs

@@ -35,6 +35,8 @@ const GPT_5_2_CODEX_PERSONALITY_PRAGMATIC: &str =
     include_str!("../../templates/personalities/gpt-5.2-codex_pragmatic.md");
 const JS_REPL_SECTION_START: &str = "<!-- js_repl:start -->";
 const JS_REPL_SECTION_END: &str = "<!-- js_repl:end -->";
+const JS_REPL_POLLING_SECTION_START: &str = "<!-- js_repl_polling:start -->";
+const JS_REPL_POLLING_SECTION_END: &str = "<!-- js_repl_polling:end -->";
 const JS_REPL_TOOLS_ONLY_SECTION_START: &str = "<!-- js_repl_tools_only:start -->";
 const JS_REPL_TOOLS_ONLY_SECTION_END: &str = "<!-- js_repl_tools_only:end -->";
 
@@ -115,6 +117,10 @@ pub(crate) fn with_config_overrides(mut model: ModelInfo, config: &Config) -> Mo
         &model.base_instructions,
         config.features.enabled(Feature::JsRepl),
     );
+    model.base_instructions = apply_js_repl_polling_section(
+        &model.base_instructions,
+        config.features.enabled(Feature::JsRepl) && config.features.enabled(Feature::JsReplPolling),
+    );
     model.base_instructions = apply_js_repl_tools_only_section(
         &model.base_instructions,
         config.features.enabled(Feature::JsRepl)
@@ -128,6 +134,15 @@ pub(crate) fn apply_js_repl_section(input: &str, enabled: bool) -> String {
     apply_section(input, JS_REPL_SECTION_START, JS_REPL_SECTION_END, enabled)
 }
 
+pub(crate) fn apply_js_repl_polling_section(input: &str, enabled: bool) -> String {
+    apply_section(
+        input,
+        JS_REPL_POLLING_SECTION_START,
+        JS_REPL_POLLING_SECTION_END,
+        enabled,
+    )
+}
+
 pub(crate) fn apply_js_repl_tools_only_section(input: &str, enabled: bool) -> String {
     apply_section(
         input,