feat: add managed remote websocket app-server connections

- Added Codex.AppServer.connect_remote/2 to support managed remote
  websocket connections. This includes transport policy checks for safe
  websocket usage, auth-token transport validation, and support for
  auth_token/auth_token_env.
- Realtime: Session now defers follow-up response.create requests until the
  current response finishes (response.done), preventing overlapping turns
  from causing premature creation.
- Realtime: Diagnostics probe uses a schema-compatible turn and treats
  unknown_parameter-style schema drift as a protocol-incompatible skip
  reason rather than a hard failure.
- OAuth: Canonicalize ChatGPT plan strings (e.g., "hc" -> "enterprise",
  "education" -> "edu") before SDK processing.
- CLI: Interactive, resume, and fork helpers now support --remote and
  --remote-auth-token-env. Added support for websocket auth flags in
  Codex.CLI.app_server/1.
- AppServer: Added experimentalFeature/enablement/set support.

Author: nshkrdotcom

CHANGELOG.md

@@ -7,12 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `Codex.AppServer.connect_remote/2` for managed remote websocket app-server
+  connections, including auth-token transport policy checks and pid-compatible
+  reuse of the existing request/helper surface.
+
 ### Changed
 
 - Release notes and package-facing docs now call out the final Phase 4
   ownership boundary explicitly: `cli_subprocess_core` owns every
   subprocess-backed Codex lifecycle, while `codex_sdk` keeps Codex-native
   semantics such as app-server, MCP, realtime, and voice.
+- App-server and CLI parity now cover `experimentalFeature/enablement/set`,
+  current websocket auth flags for `codex app-server`, root `--remote` /
+  `--remote-auth-token-env` passthrough on interactive session wrappers, and
+  `resume --include-non-interactive`.
+- Realtime diagnostics now use a schema-compatible probe and Realtime session
+  sequencing now defers follow-up `response.create` calls until the active
+  response completes.
+
+### Fixed
+
+- ChatGPT plan claims now normalize to the SDK's canonical lowercase strings,
+  including `hc -> "enterprise"` and `education -> "edu"`, before auth/status
+  structs and app-server external-auth payloads are built.
 
 ## [0.15.0] - 2026-03-19
 

README.md

@@ -25,8 +25,8 @@ An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and
 ## Features
 
 - **End-to-End Codex Lifecycle**: Spawn, resume, and manage full Codex threads with rich turn instrumentation.
-- **Multi-Transport Support**: Default `:exec` compatibility selector for the core-backed exec JSONL lane (`codex exec --json`) plus stateful app-server JSON-RPC over stdio (`codex app-server`) with multi-modal `UserInput` blocks.
-- **CLI Passthrough and PTY Sessions**: `Codex.CLI` can launch root `codex`, `cloud`, `completion`, `features`, `mcp`, `sandbox`, `resume`, `fork`, `app-server`, and other command-surface workflows directly.
+- **Multi-Transport Support**: Default `:exec` compatibility selector for the core-backed exec JSONL lane (`codex exec --json`) plus stateful app-server JSON-RPC via managed local stdio children or managed remote websockets.
+- **CLI Passthrough and PTY Sessions**: `Codex.CLI` can launch root `codex`, `cloud`, `completion`, `features`, `mcp`, `sandbox`, `resume`, `fork`, `app-server`, and other command-surface workflows directly, including remote-root and websocket-auth app-server flags.
 - **Native OAuth**: `Codex.OAuth` provides SDK-managed browser/device login, refresh, status, and logout with upstream-compatible `auth.json` persistence or memory-only sessions.
 - **Upstream Compatibility**: Mirrors Codex CLI flags (profile/OSS/full-auto/color/search/config overrides/review/resume) and handles app-server protocol drift (e.g. MCP list method rename fallbacks).
 - **Streaming & Structured Output**: Real-time events, per-thread output schemas, reasoning summary/content preservation, and typed app-server deltas.
@@ -107,6 +107,11 @@ Environment-aware OAuth behavior matches current native-app guidance:
 - SSH/headless/container environments prefer device code
 - CI and other non-interactive environments never auto-start login; existing credentials are used or the call fails clearly
 
+ChatGPT plan types are normalized before they surface through SDK auth/status
+structs or app-server external-auth forwarding. In particular, `hc` and
+`enterprise` normalize to `"enterprise"`, while `education` and `edu`
+normalize to `"edu"`.
+
 If `cli_auth_credentials_store = "keyring"` is set in config and keyring support is unavailable,
 the SDK logs a warning and skips file-based tokens (remote model fetch falls back to bundled models).
 When `cli_auth_credentials_store = "auto"` and keyring is unavailable, the SDK falls back to file-based auth.
@@ -254,6 +259,28 @@ tmp_home = Path.join(System.tmp_dir!(), "codex-sdk-app-server-home")
 `cwd` and `process_env` apply to the app-server child process. Per-thread working
 directories still belong on `working_directory` / `cwd` thread params.
 
+For a managed remote app-server websocket instead of a local `codex app-server`
+child, use `Codex.AppServer.connect_remote/2`:
+
+```elixir
+{:ok, conn} =
+  Codex.AppServer.connect_remote(
+    "wss://app-server.example/ws",
+    auth_token_env: "CODEX_REMOTE_AUTH_TOKEN",
+    client_name: "my_app",
+    experimental_api: true
+  )
+```
+
+`connect_remote/2` keeps the same pid contract as `connect/2`, so the existing
+`Codex.AppServer.*` request helpers, `disconnect/1`, `alive?/1`, `subscribe/2`,
+`unsubscribe/1`, and `respond/3` work unchanged. Bearer auth headers are only
+attached for `wss://` or loopback `ws://` endpoints; plain non-loopback
+`ws://` plus `auth_token` or `auth_token_env` is rejected. Remote OAuth only
+supports `oauth: [storage: :memory]`; persistent child-login preflight
+(`:file` / `:auto`) is not available because remote mode does not spawn a local
+child or child `CODEX_HOME`.
+
 `connect/2` also supports OAuth-aware child auth bootstrapping:
 
 ```elixir
@@ -293,6 +320,7 @@ App-server-only APIs include:
 
 - `Codex.AppServer.thread_list/2`, `thread_archive/2`, `thread_read/3`, `thread_fork/3`, `thread_rollback/3`, `thread_loaded_list/2`
 - `Codex.AppServer.model_list/2`, `config_read/2`, `config_write/4`, `config_batch_write/3`, `config_requirements/1`
+- `Codex.AppServer.experimental_feature_list/2`, `experimental_feature_enablement_set/2`
 - `Codex.AppServer.fs_read_file/2`, `fs_write_file/3`, `fs_create_directory/3`, `fs_get_metadata/2`, `fs_read_directory/2`, `fs_remove/3`, `fs_copy/4`
 - `Codex.AppServer.plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
 - `Codex.AppServer.skills_config_write/3`, `collaboration_mode_list/1`, `apps_list/2`
@@ -321,6 +349,21 @@ inside this repository.
 App-server v2 input blocks support `text`, `image`, `localImage`, `skill`, and `mention`.
 Legacy app-server v1 conversation flows are available via `Codex.AppServer.V1`.
 
+Experimental feature enablement is forwarded without a stale local allowlist:
+
+```elixir
+{:ok, %{"data" => features}} = Codex.AppServer.experimental_feature_list(conn)
+
+{:ok, _} =
+  Codex.AppServer.experimental_feature_enablement_set(conn,
+    apps: true,
+    plugins: false
+  )
+```
+
+The SDK forwards the `enablement` map as given and lets the server validate the
+current supported keys.
+
 ### Raw CLI Passthrough and Interactive Sessions
 
 Use `Codex.CLI.run/2` when you want literal command-surface parity with the upstream terminal client, and `Codex.CLI.interactive/2` or `Codex.CLI.start/2` when you need a long-running or PTY-backed session.
@@ -380,6 +423,16 @@ IO.puts(session_result.stdout)
 
 This layer is also the simplest way to reach CLI-only workflows such as `codex completion`, `codex cloud`, `codex execpolicy`, `codex features`, `codex mcp-server`, and the root interactive client without dropping down to `System.cmd/3` yourself.
 
+Current upstream parity helpers also include:
+
+- `Codex.CLI.interactive/2`, `resume/2`, and `fork/2` accept `remote:` and `remote_auth_token_env:`
+- `Codex.CLI.resume/2` accepts `include_non_interactive: true`
+- `Codex.CLI.app_server/1` forwards websocket auth flags: `ws_auth`, `ws_token_file`, `ws_shared_secret_file`, `ws_issuer`, `ws_audience`, and `ws_max_clock_skew_seconds`
+
+`ws_auth` atoms normalize to upstream CLI values such as
+`:capability_token -> capability-token` and
+`:signed_bearer_token -> signed-bearer-token`.
+
 ### Streaming Responses
 
 For real-time processing of events as they occur:
@@ -511,6 +564,13 @@ For bidirectional voice interactions using the OpenAI Realtime API:
 - Auth precedence for realtime/voice API keys is:
   `CODEX_API_KEY` -> `auth.json` `OPENAI_API_KEY` -> `OPENAI_API_KEY`.
 
+`Codex.Realtime.Diagnostics.probe_text_turn/1` now uses a minimal
+schema-compatible probe and treats `unknown_parameter`-style schema drift as a
+protocol-incompatible skip reason instead of a hard failure. `Codex.Realtime.Session`
+also defers follow-up `response.create` calls until the active response reaches
+`response.done`, so overlapping user input and tool output no longer trigger
+premature create requests.
+
 ```elixir
 alias Codex.Realtime
 

guides/03-api-guide.md

@@ -104,6 +104,13 @@ Key entry points:
 - `interactive/2` — launches the root `codex` client (prompt mode or full interactive mode)
 - wrappers for `app`, `app_server`, `apply`, `cloud`, `cloud_list`, `cloud_exec`, `completion`, `debug_app_server_send_message_v2`, `execpolicy_check`, `features_*`, `login`, `logout`, `mcp_*`, `mcp_server`, `resume`, `fork`, and `sandbox`
 
+Current parity notes:
+
+- `interactive/2`, `resume/2`, and `fork/2` accept `remote:` plus `remote_auth_token_env:`
+- `resume/2` accepts `include_non_interactive: true`
+- `app_server/1` accepts websocket auth options: `ws_auth`, `ws_token_file`, `ws_shared_secret_file`, `ws_issuer`, `ws_audience`, and `ws_max_clock_skew_seconds`
+- `ws_auth` atoms normalize to the upstream CLI spellings such as `:capability_token -> capability-token`
+
 `run/2` and the synchronous wrappers execute through the shared
 `CliSubprocessCore.Command` lane.
 
@@ -163,7 +170,7 @@ such as `codex completion`, `codex cloud`, `codex execpolicy`, and
 The SDK supports both upstream external transports:
 
 - **Exec JSONL (default `:exec` compatibility selector)**: `codex exec --json`
-- **App-server JSON-RPC (optional)**: `codex app-server` (newline-delimited JSON over stdio)
+- **App-server JSON-RPC (optional)**: managed local `codex app-server` over stdio or managed remote app-server over websocket
 
 Select transport per-thread via `Codex.Thread.Options.transport`:
 
@@ -180,6 +187,23 @@ temporary `CODEX_HOME`, pass `cwd:` and `process_env:` to `connect/2`. Those
 launch options affect the child process; per-thread cwd still belongs on thread
 params.
 
+For a managed remote app-server websocket, use `connect_remote/2` instead of
+`connect/2`:
+
+```elixir
+{:ok, conn} =
+  Codex.AppServer.connect_remote(
+    "wss://app-server.example/ws",
+    auth_token_env: "CODEX_REMOTE_AUTH_TOKEN",
+    experimental_api: true
+  )
+```
+
+Remote connections keep the same pid-compatible request surface as local ones.
+Bearer headers are only attached for `wss://` or loopback `ws://` endpoints.
+Remote OAuth only supports `oauth: [storage: :memory]`; `:file` / `:auto`
+storage is rejected because remote mode does not prepare a child `CODEX_HOME`.
+
 `connect/2` also accepts `oauth:` for child-auth-aware startup:
 
 ```elixir
@@ -200,6 +224,7 @@ conversation APIs.
 The direct `Codex.AppServer` surface also includes upstream v2 filesystem,
 plugin, and thread-shell helpers:
 
+- `experimental_feature_list/2` and `experimental_feature_enablement_set/2`
 - `fs_read_file/2`, `fs_write_file/3`, `fs_create_directory/3`, `fs_get_metadata/2`,
   `fs_read_directory/2`, `fs_remove/3`, `fs_copy/4`
 - `plugin_list/2`, `plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
@@ -211,6 +236,10 @@ plus per-turn `service_tier` on `Codex.Thread.run/3` / `run_streamed/3`.
 `plugin_install/4` and `plugin_uninstall/3` accept `force_remote_sync: true`,
 and raw plugin maps preserve newer upstream fields such as `needsAuth`.
 
+`experimental_feature_enablement_set/2` forwards the supplied `enablement` map
+without a local allowlist and lets the connected server validate the active
+feature keys.
+
 ## Codex.Subagents
 
 `Codex.Subagents` wraps the deterministic pieces of a subagent workflow that

guides/05-app-server-transport.md

@@ -1,11 +1,11 @@
-# App-server Transport (JSON-RPC over stdio)
+# App-server Transport (JSON-RPC over stdio or websocket)
 
 This guide covers using the **stateful** `codex app-server` transport from Elixir via `Codex.AppServer`.
 
 The SDK supports two external Codex transports:
 
 - **Exec JSONL (default `:exec` compatibility selector)**: `codex exec --json`
-- **App-server JSON-RPC (optional)**: `codex app-server` (newline-delimited JSON messages over stdio)
+- **App-server JSON-RPC (optional)**: managed local `codex app-server` over stdio or managed remote app-server over websocket
 
 Use app-server when you need upstream v2 APIs that are not exposed via exec JSONL (threads list/archive, skills/models/config APIs, server-driven approvals, etc.).
 
@@ -30,6 +30,10 @@ If you need the literal command surface instead of the managed JSON-RPC connecti
 `Codex.CLI.app_server/1` launches a raw `codex app-server` subprocess session and
 `Codex.CLI.run/2` can be used for one-shot passthrough commands.
 
+`Codex.CLI.app_server/1` also forwards the current websocket auth flags:
+`ws_auth`, `ws_token_file`, `ws_shared_secret_file`, `ws_issuer`,
+`ws_audience`, and `ws_max_clock_skew_seconds`.
+
 ## Connect / Disconnect
 
 `Codex.AppServer.connect/2` starts a supervised `codex app-server` subprocess and performs the required `initialize` → `initialized` handshake automatically.
@@ -48,6 +52,25 @@ Pass `experimental_api: true` when you need upstream experimental fields such as
 :ok = Codex.AppServer.disconnect(conn)
 ```
 
+For a managed remote websocket connection, use `Codex.AppServer.connect_remote/2`:
+
+```elixir
+{:ok, conn} =
+  Codex.AppServer.connect_remote(
+    "wss://app-server.example/ws",
+    auth_token_env: "CODEX_REMOTE_AUTH_TOKEN",
+    client_name: "my_app",
+    experimental_api: true
+  )
+
+:ok = Codex.AppServer.disconnect(conn)
+```
+
+Remote mode does not take `Codex.Options` because it does not spawn a local
+`codex` child. The returned pid stays compatible with the rest of the
+`Codex.AppServer` API surface, including `subscribe/2`, `unsubscribe/1`,
+`respond/3`, request helpers, and `disconnect/1`.
+
 ### Child cwd and environment isolation
 
 `Codex.AppServer.connect/2` can also isolate the managed child process itself:
@@ -74,6 +97,10 @@ These launch options apply to the app-server child process. Per-thread working
 directories still belong on `thread/start`, `thread/resume`, or
 `Codex.Thread.Options`.
 
+For `connect_remote/2`, `cwd` and `process_env` are only used to resolve auth
+context for SDK-managed OAuth helpers. They do not launch or mutate a child
+process because remote mode has no local child.
+
 ### OAuth-aware connect
 
 Persistent child auth:
@@ -105,6 +132,22 @@ Notes:
   `chatgptAuthTokens`, and starts a connection-owned refresh responder
 - set `auto_refresh: false` when you want to handle
   `account/chatgptAuthTokens/refresh` yourself via `subscribe/2`
+- remote websocket mode only supports `storage: :memory`; persistent
+  `:file` / `:auto` child-login preflight is rejected because there is no child
+  `CODEX_HOME` to prepare
+
+### Remote auth-token transport policy
+
+Remote websocket auth supports both `auth_token:` and `auth_token_env:`.
+Bearer headers are only attached when the websocket URL is:
+
+- `wss://...`
+- loopback `ws://127.0.0.1/...`
+- loopback `ws://localhost/...`
+
+If you configure an auth token for a non-loopback plain `ws://` URL,
+`connect_remote/2` returns `{:error, {:invalid_remote_auth_transport, url}}`
+instead of sending credentials over an unsafe transport.
 
 ### Client identity
 
@@ -168,12 +211,15 @@ App-server enables additional APIs that are not available via exec JSONL. Exampl
 {:ok, %{"data" => skills}} =
   Codex.AppServer.skills_list(conn, cwds: ["/path/to/project"], force_reload: true)
 {:ok, %{"data" => models}} = Codex.AppServer.model_list(conn, limit: 25)
+```
 
 When you need feature-flag gating or to load the underlying `SKILL.md` contents,
 use `Codex.Skills.list/2` and `Codex.Skills.load/2`, which honor `features.skills`.
 
+```elixir
 {:ok, %{"config" => config}} = Codex.AppServer.config_read(conn, include_layers: false)
 {:ok, _} = Codex.AppServer.config_write(conn, "features.web_search_request", true)
+{:ok, _} = Codex.AppServer.experimental_feature_enablement_set(conn, apps: true, plugins: false)
 
 {:ok, %{"data" => threads, "nextCursor" => cursor}} = Codex.AppServer.thread_list(conn, limit: 10)
 
@@ -191,6 +237,7 @@ IO.puts(Base.decode64!(encoded_back))
 
 Additional v2 APIs include:
 
+- `Codex.AppServer.experimental_feature_list/2` and `experimental_feature_enablement_set/2`
 - `Codex.AppServer.thread_read/3`, `thread_fork/3`, `thread_shell_command/3`, `thread_rollback/3`, `thread_loaded_list/2`
 - `Codex.AppServer.fs_read_file/2`, `fs_write_file/3`, `fs_create_directory/3`, `fs_get_metadata/2`, `fs_read_directory/2`, `fs_remove/3`, `fs_copy/4`
 - `Codex.AppServer.plugin_read/3`, `plugin_install/4`, `plugin_uninstall/3`
@@ -208,6 +255,10 @@ Current upstream routing and sync controls are also covered:
 `!` workflow, so treat it with the same care you would give shell access in the
 interactive CLI.
 
+`experimental_feature_enablement_set/2` forwards the `enablement` map as given.
+The SDK does not keep a stale local allowlist; the connected app-server remains
+the source of truth for supported feature keys.
+
 When `include_layers: true`, `config_read/2` returns a `layers` list. Recent Codex versions encode each layer's `name` as a tagged union (`ConfigLayerSource`), for example:
 
 ```elixir

guides/06-realtime-and-voice.md

@@ -21,6 +21,11 @@ helps CLI/app-server flows; realtime and voice still need an API key or an
 
 If your account has no credits, direct API calls may return `insufficient_quota` (HTTP 429). If your account lacks access to realtime models, calls may fail with `model_not_found`. When the upstream Realtime service itself returns a generic `server_error`, the realtime examples now run a minimal raw-WebSocket probe first and print `SKIPPED` with the detected `session_id` so you can report the exact upstream failure cleanly.
 
+`Codex.Realtime.Diagnostics.probe_text_turn/1` keeps that probe minimal and now
+classifies `unknown_parameter`-style schema mismatches as a
+`realtime_protocol_incompatible` skip reason instead of a hard failure. This
+helps distinguish upstream schema drift from auth/quota/runtime failures.
+
 Custom trust roots use `CODEX_CA_CERTIFICATE` first and `SSL_CERT_FILE` second. Blank values are
 ignored. The same PEM bundle is applied to HTTPS requests and secure realtime websockets.
 
@@ -80,6 +85,11 @@ chunks
 end)
 ```
 
+If you queue additional text input or tool output while a response is still
+active, `Codex.Realtime.Session` defers the follow-up `response.create` until
+the current response reaches `response.done`. That keeps overlapping turns from
+issuing premature create requests.
+
 ### Receiving events
 
 Realtime events are delivered as `{:session_event, event}`: