Add exec-server stub server and protocol docs by starr-openai · Pull Request #15089 · openai/codex

starr-openai · 2026-03-18T20:41:04Z

Stacked PR 1/3.

This is the initialize-only exec-server stub slice: binary/client scaffolding and protocol docs, without exec/filesystem implementation.

This adds the standalone exec-server stdio JSON-RPC crate and its smoke tests without wiring it into the CLI or unified-exec yet. Co-authored-by: Codex <noreply@openai.com>

Document the standalone exec-server crate, its stdio JSON-RPC transport, and the current request/response and notification payloads. Co-authored-by: Codex <noreply@openai.com>

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

Keep only the standalone handshake transport in the first PR. Leave exec RPC behavior unimplemented here so the working process implementation can land in a separate follow-up.\n\nCo-authored-by: Codex <noreply@openai.com>

Move process-oriented client helpers and exports into the exec follow-up. Keep the first PR focused on spawning the stub server and running the initialize handshake.\n\nCo-authored-by: Codex <noreply@openai.com>

github-actions · 2026-03-18T20:41:47Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76071974bb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-18T20:47:45Z

codex-rs/exec-server/src/server.rs

+            continue;
+        }
+
+        let message = serde_json::from_str::<JSONRPCMessage>(&line)?;


Handle malformed JSON without exiting server

run_main deserializes each input line with serde_json::from_str(...)? in the main loop. A single malformed line propagates an error out of run_main, so the binary exits and drops the stdio session instead of replying with a JSON-RPC error and continuing. This lets one bad client message take down the whole server process.

Useful? React with 👍 / 👎.

Introduce API-agnostic server envelope parsing/encoding and a tiny method-registration router in the initialize-only exec-server slice. Co-authored-by: Codex <noreply@openai.com>

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

pakrym-oai · 2026-03-18T22:06:11Z

codex-rs/exec-server/src/bin/codex-exec-server.rs

+
+#[derive(Debug, Parser)]
+struct ExecServerArgs {
+    /// Transport endpoint URL. Supported values: `stdio://` (default),


we should test over the same protocol that we use in prod (I assume ws?)

not blocking

pakrym-oai · 2026-03-18T22:07:00Z

codex-rs/exec-server/src/protocol.rs

+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct InitializeResponse {
+    pub protocol_version: String,


I'd nix versioning until we know what we are actually doing with it.

bolinfest · 2026-03-18T23:18:51Z

codex-rs/exec-server/src/server/processor.rs

+
+    while let Some(event) = incoming_rx.recv().await {
+        match event {
+            JsonRpcConnectionEvent::Message(message) => match message {


JsonRpcConnectionEvent doesn't exist in app server so I'm surprised to see this here.

bolinfest · 2026-03-18T23:19:51Z

codex-rs/exec-server/src/server/registry.rs

+use crate::rpc::RpcRouter;
+use crate::server::ExecServerHandler;
+
+pub(crate) fn build_router() -> RpcRouter<ExecServerHandler> {


I tend to favor a match statement in a loop?

bolinfest · 2026-03-18T23:20:30Z

codex-rs/exec-server/src/server/transport.rs

+
+#[allow(clippy::print_stderr)]
+fn print_websocket_startup_banner(addr: SocketAddr) {
+    eprintln!("codex-exec-server listening on ws://{addr}");


We try to ban println and eprintln (there's a lint to block them). Favor the tracing crate.

bolinfest · 2026-03-18T23:20:56Z

codex-rs/exec-server/src/server/transport.rs

+    eprintln!("codex-exec-server listening on ws://{addr}");
+}
+
+#[cfg(test)]


Look at core as an example: we do something slightly non-standard and create separate _tests.rs files.

bolinfest · 2026-03-18T23:22:14Z

codex-rs/exec-server/README.md

+
+## Transport
+
+The server speaks newline-delimited JSON-RPC 2.0 over stdio.


Not quite? Or does it?

bolinfest · 2026-03-18T23:22:24Z

codex-rs/exec-server/README.md

+- `stdout`: one JSON-RPC message per line
+- `stderr`: reserved for logs / process errors
+
+Like the app-server transport, messages on the wire omit the `"jsonrpc":"2.0"`


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

starr-openai · 2026-03-18T23:46:29Z

I have read the CLA Document and I hereby sign the CLA

starr-openai · 2026-03-18T23:48:30Z

recheck

Handle malformed JSON-RPC input by replying with an invalid-request error and keeping the connection open, and trim stale transport wording in the README. Co-authored-by: Codex <noreply@openai.com>

Remove dead stub-only dependencies and disable doctests for the exec-server library target so cargo-shear stays green. Co-authored-by: Codex <noreply@openai.com>

starr-openai and others added 5 commits March 18, 2026 10:29

Add codex-exec-server crate

144c359

This adds the standalone exec-server stdio JSON-RPC crate and its smoke tests without wiring it into the CLI or unified-exec yet. Co-authored-by: Codex <noreply@openai.com>

docs(exec-server): add protocol README

949932c

Document the standalone exec-server crate, its stdio JSON-RPC transport, and the current request/response and notification payloads. Co-authored-by: Codex <noreply@openai.com>

Add Bazel package for exec-server

40cc199

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

Trim exec-server PR to stub server slice

2958067

Keep only the standalone handshake transport in the first PR. Leave exec RPC behavior unimplemented here so the working process implementation can land in a separate follow-up.\n\nCo-authored-by: Codex <noreply@openai.com>

Keep first exec-server PR initialize-only

7607197

Move process-oriented client helpers and exports into the exec follow-up. Keep the first PR focused on spawning the stub server and running the initialize handshake.\n\nCo-authored-by: Codex <noreply@openai.com>

chatgpt-codex-connector bot reviewed Mar 18, 2026

View reviewed changes

starr-openai and others added 5 commits March 18, 2026 13:59

Add generic RPC server glue to exec-server stub

16ff474

Introduce API-agnostic server envelope parsing/encoding and a tiny method-registration router in the initialize-only exec-server slice. Co-authored-by: Codex <noreply@openai.com>

Add generic exec-server RPC foundation

0a846a2

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

Wire notification sender into exec-server RPC foundation

c5dbe42

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

Remove outer handler mutex from exec-server RPC base

66f49ea

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

Test generic exec-server RPC response matching

43b112c

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

pakrym-oai reviewed Mar 18, 2026

View reviewed changes

pakrym-oai approved these changes Mar 18, 2026

View reviewed changes

bolinfest reviewed Mar 18, 2026

View reviewed changes

starr-openai and others added 2 commits March 18, 2026 23:30

exec-server: simplify stub json-rpc transport shape

2661dc5

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

exec-server: address transport review feedback

3b4a522

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

starr-openai and others added 2 commits March 18, 2026 23:53

exec-server: keep malformed-json connections alive

2ed509d

Handle malformed JSON-RPC input by replying with an invalid-request error and keeping the connection open, and trim stale transport wording in the README. Co-authored-by: Codex <noreply@openai.com>

exec-server: trim unused stub dependencies

866743d

Remove dead stub-only dependencies and disable doctests for the exec-server library target so cargo-shear stays green. Co-authored-by: Codex <noreply@openai.com>

starr-openai enabled auto-merge (squash) March 19, 2026 00:23

starr-openai merged commit 81996fc into main Mar 19, 2026
33 checks passed

starr-openai deleted the starr/exec-server-stub-fresh branch March 19, 2026 00:30

github-actions bot locked and limited conversation to collaborators Mar 19, 2026


		## Transport

		The server speaks newline-delimited JSON-RPC 2.0 over stdio.

Conversation

starr-openai commented Mar 18, 2026

Uh oh!

github-actions bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

starr-openai commented Mar 18, 2026

Uh oh!

starr-openai commented Mar 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 18, 2026 •

edited

Loading