Add stdio exec-server client transport by starr-openai · Pull Request #20664 · openai/codex

starr-openai · 2026-05-01T19:10:28Z

Why

Configured environments need to connect to exec-server instances that are not necessarily already listening on a websocket URL. A command-backed stdio transport lets Codex start an exec-server process, speak JSON-RPC over its stdio streams, and clean up that child process with the client lifetime.

Stack position: this is PR 2 of 5. It builds on the server-side stdio listener from PR 1 and provides the client transport used by later environment/config PRs.

What Changed

Add ExecServerTransport variants for websocket URLs and stdio shell commands.
Add stdio command connection support for ExecServerClient.
Move websocket/stdio transport setup into client_transport.rs so client.rs stays focused on shared JSON-RPC client, session, HTTP, and notification behavior.
Tie stdio child process cleanup to the JSON-RPC connection lifetime with a RAII lifetime guard.
Keep existing websocket environment behavior by adapting URL-backed remotes to ExecServerTransport::WebSocketUrl.

Stack

1. Add stdio exec-server listener #20663 - Add stdio exec-server listener
2. This PR: Add stdio exec-server client transport #20664 - Add stdio exec-server client transport
1. Make environment providers own default selection #20665 - Make environment providers own default selection
1. Add CODEX_HOME environments TOML provider #20666 - Add CODEX_HOME environments TOML provider
1. Load configured environments from CODEX_HOME #20667 - Load configured environments from CODEX_HOME

Split from original draft: #20508

Validation

Not run locally; this was split out of the original draft stack and then refactored to separate transport setup from the base client.

## Why This stack adds configured exec-server environments, including environments reached over stdio. Before client-side stdio transports or config can use that path, the exec-server binary itself needs a first-class stdio listen mode so it can speak the same JSON-RPC protocol over stdin/stdout that it already speaks over websockets. **Stack position:** this is PR 1 of 5. It is the server-side transport foundation for the stack. ## What Changed - Accept `stdio` and `stdio://` for `codex exec-server --listen`. - Promote the existing stdio `JsonRpcConnection` helper from test-only code into normal exec-server transport code. - Add parse coverage for stdio listen URLs while preserving the existing websocket default. ## Stack - **1. This PR:** #20663 - Add stdio exec-server listener - 2. #20664 - Add stdio exec-server client transport - 3. #20665 - Make environment providers own default selection - 4. #20666 - Add CODEX_HOME environments TOML provider - 5. #20667 - Load configured environments from CODEX_HOME Split from original draft: #20508 ## Validation Not run locally; this was split out of the original draft stack. --------- Co-authored-by: Codex <noreply@openai.com>

Allow exec-server clients to connect through a shell command over stdio. The connection can now retain a drop resource so the spawned child is terminated when the JSON-RPC client is dropped. Co-authored-by: Codex <noreply@openai.com>

Co-authored-by: Codex <noreply@openai.com>

Use the existing process-group cleanup pattern for stdio command transports so wrapper shell children are terminated with the client lifetime. Add a regression test that drops the client after spawning a background shell child through the command-backed transport. Co-authored-by: Codex <noreply@openai.com>

Keep environment transport connection policy on ExecServerClient instead of the transport enum, and replace the JSON-RPC connection tuple alias with named connection parts. Co-authored-by: Codex <noreply@openai.com>

jif-oai · 2026-05-05T08:44:23Z


+/// Stdio connection arguments for a command-backed exec-server.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct StdioExecServerConnectArgs {


A single shell string means callers have to hand-roll quoting, and we lose any way to control argv/env/cwd... is it on purpose?

jif-oai · 2026-05-05T08:48:38Z

+    #[cfg(not(windows))]
+    {
+        let mut command = Command::new("sh");
+        command.arg("-lc").arg(shell_command);


Are we sure we want a login shell here? For example, what if the .profile has any kind of echo "hello world" (as lots of people do)
Then the stdout become

hello world {"id":1,"result":{"sessionId":"..."}}

and so we break the JSON-RPC

And I think this problem might become true in multiple other cases...

jif-oai · 2026-05-05T08:49:21Z

+            JsonRpcConnection::from_stdio(
+                stdout,
+                stdin,
+                format!("exec-server stdio command `{shell_command}`"),


Can we avoid putting the raw command in the connection label? Any token/env/... assignment in the command now gets echoed back through transport errors/logs

jif-oai · 2026-05-05T08:50:05Z

+
+    let should_escalate = match terminate_process_group(process_group_id) {
+        Ok(exists) => exists,
+        Err(err) => {


(found by Codex)
If killpg(SIGTERM) fails with anything other than “not found”, we just log it and then hand the child to wait(). i.e. dead lock

jif-oai · 2026-05-05T08:50:58Z

    disconnected_rx: watch::Receiver<bool>,
    next_request_id: AtomicI64,
    transport_tasks: Vec<JoinHandle<()>>,
+    _transport_lifetime: Option<TransportLifetime>,


This keeps the child alive for the cached client lifetime, not the live connection lifetime. Is it on purpose?

jif-oai · 2026-05-05T08:51:37Z

            .expect("json-rpc line should write");
    }

+    #[cfg(not(windows))]


Could we add a windows test as well? Not sure this is a big deal for now but it might become one

starr-openai force-pushed the starr/exec-env-stdio-stack-2-client branch 7 times, most recently from 1a11c8b to 751ed42 Compare May 1, 2026 22:02

starr-openai force-pushed the starr/exec-env-stdio-stack-1-server branch from b8272bb to 80a3c55 Compare May 4, 2026 17:35

Base automatically changed from starr/exec-env-stdio-stack-1-server to main May 4, 2026 18:40

starr-openai and others added 4 commits May 4, 2026 11:41

Add stdio exec-server client transport

92534cb

Allow exec-server clients to connect through a shell command over stdio. The connection can now retain a drop resource so the spawned child is terminated when the JSON-RPC client is dropped. Co-authored-by: Codex <noreply@openai.com>

Make exec-server RPC client Send-safe

9501c27

Co-authored-by: Codex <noreply@openai.com>

Remove duplicate stdio client test import

cec0aca

Co-authored-by: Codex <noreply@openai.com>

Clarify exec-server transport lifetime ownership

4c6d799

Co-authored-by: Codex <noreply@openai.com>

starr-openai force-pushed the starr/exec-env-stdio-stack-2-client branch from 3d9bb84 to 4c6d799 Compare May 4, 2026 18:41

starr-openai force-pushed the starr/exec-env-stdio-stack-2-client branch from 7bc1d8f to 309db97 Compare May 4, 2026 19:17

starr-openai marked this pull request as ready for review May 4, 2026 19:26

Simplify exec-server transport internals

ca3a581

Keep environment transport connection policy on ExecServerClient instead of the transport enum, and replace the JSON-RPC connection tuple alias with named connection parts. Co-authored-by: Codex <noreply@openai.com>

jif-oai reviewed May 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add stdio exec-server client transport#20664

Add stdio exec-server client transport#20664
starr-openai wants to merge 6 commits intomainfrom
starr/exec-env-stdio-stack-2-client

starr-openai commented May 1, 2026 •

edited

Loading

Uh oh!

jif-oai May 5, 2026

Uh oh!

jif-oai May 5, 2026

Uh oh!

jif-oai May 5, 2026

Uh oh!

jif-oai May 5, 2026

Uh oh!

jif-oai May 5, 2026

Uh oh!

jif-oai May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

starr-openai commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What Changed

Stack

Validation

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jif-oai May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

starr-openai commented May 1, 2026 •

edited

Loading