Honor authoritative model payloads in Codex SDK

Keep caller-supplied model payloads authoritative across the\nCodex options surface and replace timing-based realtime test\nsynchronization with concrete websocket send acknowledgements.\n\nThis preserves the shared-core handoff and fixes async suite\nflakes without hiding them behind sync execution.

Author: nshkrdotcom

CHANGELOG.md

@@ -32,6 +32,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- App-server connections no longer live-echo child stderr during healthy
+  operation; retained stderr is still preserved for typed failure reporting.
 
 ## [0.15.0] - 2026-03-19
 

README.md

@@ -148,6 +148,11 @@ and `reasoning_effort` from the authoritative shared `model_payload`.
 `Codex.Models` is now a read-only projection of the shared core catalog. It no
 longer owns a separate catalog or a separate fallback/defaulting path.
 
+If a caller supplies an explicit `model_payload`, that payload stays
+authoritative. Repo-local env defaults such as `CODEX_MODEL`,
+`CODEX_PROVIDER_BACKEND`, and `CODEX_OLLAMA_BASE_URL` are fallback inputs only
+when the payload was not supplied explicitly.
+
 Operationally, that means:
 
 - explicit request wins first

guides/03-api-guide.md

@@ -43,8 +43,8 @@ public API surfaces are projections and consumers of that shared contract.
 
 Primary entrypoints:
 
-- `Codex.Options.new/1` resolves the shared `model_payload` via
-  `CliSubprocessCore.ModelRegistry.build_arg_payload/3`
+- `Codex.Options.new/1` normalizes mixed raw-versus-payload input through
+  `CliSubprocessCore.ModelInput.normalize/3`
 - `Codex.Models.default_model/0` returns the current shared core default
 - `Codex.Models.list_visible/1` returns the shared visible Codex catalog
 - `Codex.Models.default_reasoning_effort/1` projects reasoning defaults from
@@ -57,6 +57,8 @@ Operational notes:
   from the core registry contract
 - runtime CLI rendering consumes resolved state and does not invent fallback
   models locally
+- repo-local env defaults are only consulted when `model_payload` was not
+  supplied explicitly
 
 Example:
 

lib/codex/app_server/connection.ex

@@ -287,7 +287,7 @@ defmodule Codex.AppServer.Connection do
         {:codex_io_transport, ref, {:stderr, data}},
         %State{raw_session: %RawSession{transport_ref: ref}} = state
       ) do
-    Logger.debug("codex app-server stderr: #{String.trim(IO.iodata_to_binary(data))}")
+    _ = data
     {:noreply, state}
   end
 
@@ -344,7 +344,7 @@ defmodule Codex.AppServer.Connection do
         {:stderr, ref, data},
         %State{raw_session: %RawSession{transport_ref: ref}} = state
       ) do
-    Logger.debug("codex app-server stderr: #{String.trim(IO.iodata_to_binary(data))}")
+    _ = data
     {:noreply, state}
   end
 

lib/codex/options.ex

@@ -225,16 +225,27 @@ defmodule Codex.Options do
   end
 
   defp apply_model_env_defaults(attrs) when is_map(attrs) do
-    attrs
-    |> put_missing_attr(
-      :env_model,
-      System.get_env("CODEX_MODEL") ||
-        System.get_env("OPENAI_DEFAULT_MODEL") ||
-        System.get_env("CODEX_MODEL_DEFAULT")
-    )
-    |> put_missing_attr(:provider_backend, System.get_env("CODEX_PROVIDER_BACKEND"))
-    |> put_missing_attr(:oss_provider, System.get_env("CODEX_OSS_PROVIDER"))
-    |> put_missing_attr(:ollama_base_url, System.get_env("CODEX_OLLAMA_BASE_URL"))
+    if explicit_model_payload?(attrs) do
+      attrs
+    else
+      attrs
+      |> put_missing_attr(
+        :env_model,
+        System.get_env("CODEX_MODEL") ||
+          System.get_env("OPENAI_DEFAULT_MODEL") ||
+          System.get_env("CODEX_MODEL_DEFAULT")
+      )
+      |> put_missing_attr(:provider_backend, System.get_env("CODEX_PROVIDER_BACKEND"))
+      |> put_missing_attr(:oss_provider, System.get_env("CODEX_OSS_PROVIDER"))
+      |> put_missing_attr(:ollama_base_url, System.get_env("CODEX_OLLAMA_BASE_URL"))
+    end
+  end
+
+  defp explicit_model_payload?(attrs) when is_map(attrs) do
+    case Map.get(attrs, :model_payload, Map.get(attrs, "model_payload")) do
+      nil -> false
+      _payload -> true
+    end
   end
 
   defp put_missing_attr(attrs, _key, nil), do: attrs

test/codex/app_server/connection_test.exs

@@ -2,6 +2,8 @@ defmodule Codex.AppServer.ConnectionTest do
   use ExUnit.Case, async: true
   @moduletag capture_log: true
 
+  import ExUnit.CaptureLog
+
   alias CliSubprocessCore.RawSession
   alias Codex.AppServer.Connection
   alias Codex.AppServer.Protocol
@@ -159,6 +161,30 @@ defmodule Codex.AppServer.ConnectionTest do
     assert raw_session.stdin_mode == :raw
   end
 
+  test "healthy child stderr does not produce live debug logs", %{codex_opts: codex_opts} do
+    {:ok, conn} =
+      Connection.start_link(codex_opts,
+        transport: {AppServerSubprocess, owner: self()},
+        init_timeout_ms: 200
+      )
+
+    assert_receive {:app_server_subprocess_started, ^conn, transport_ref}
+    assert_receive {:app_server_subprocess_send, ^conn, init_line}
+    assert {:ok, %{"id" => 0}} = Jason.decode(init_line)
+    send(conn, {:stdout, transport_ref, Protocol.encode_response(0, %{})})
+    assert :ok == Connection.await_ready(conn, 200)
+    assert_receive {:app_server_subprocess_send, ^conn, _initialized_line}
+
+    log =
+      capture_log([level: :debug], fn ->
+        send(conn, {:codex_io_transport, transport_ref, {:stderr, "non-fatal child stderr"}})
+        Process.sleep(20)
+      end)
+
+    refute log =~ "codex app-server stderr:"
+    assert Process.alive?(conn)
+  end
+
   test "launch options reject invalid child env overrides", %{codex_opts: codex_opts} do
     assert {:error, {:invalid_env, ["/tmp/not-a-keyword"]}} =
              Connection.start_link(codex_opts,

test/codex/options_test.exs

@@ -6,7 +6,17 @@ defmodule Codex.OptionsTest do
   import Codex.Test.ModelFixtures
 
   setup do
-    env_keys = ~w(CODEX_MODEL CODEX_MODEL_DEFAULT CODEX_API_KEY CODEX_HOME OPENAI_BASE_URL)
+    env_keys =
+      ~w(
+        CODEX_MODEL
+        CODEX_MODEL_DEFAULT
+        CODEX_PROVIDER_BACKEND
+        CODEX_OSS_PROVIDER
+        CODEX_OLLAMA_BASE_URL
+        CODEX_API_KEY
+        CODEX_HOME
+        OPENAI_BASE_URL
+      )
 
     original_env =
       env_keys
@@ -193,6 +203,43 @@ defmodule Codex.OptionsTest do
                })
     end
 
+    test "does not treat env defaults as active config when model_payload is explicit" do
+      payload =
+        Selection.new(%{
+          provider: :codex,
+          requested_model: "llama3.2",
+          resolved_model: "llama3.2",
+          resolution_source: :explicit,
+          reasoning: "high",
+          reasoning_effort: nil,
+          normalized_reasoning_effort: nil,
+          model_family: "llama",
+          catalog_version: nil,
+          visibility: :public,
+          provider_backend: :oss,
+          model_source: :external,
+          env_overrides: %{"CODEX_OSS_BASE_URL" => "http://127.0.0.1:22434"},
+          settings_patch: %{},
+          backend_metadata: %{
+            "provider_backend" => "oss",
+            "oss_provider" => "ollama",
+            "external_model" => "llama3.2",
+            "support_tier" => "runtime_validated_only"
+          },
+          errors: []
+        })
+
+      System.put_env("CODEX_MODEL", "gpt-5.4")
+      System.put_env("CODEX_PROVIDER_BACKEND", "openai")
+      System.put_env("CODEX_OSS_PROVIDER", "other")
+      System.put_env("CODEX_OLLAMA_BASE_URL", "http://127.0.0.1:11434")
+
+      assert {:ok, opts} = Options.new(%{model_payload: payload})
+      assert opts.model_payload == payload
+      assert opts.model == "llama3.2"
+      assert opts.reasoning_effort == :high
+    end
+
     test "does not crash when CODEX_MODEL points at a cross-catalog model under api auth" do
       auth_path = Path.join(System.get_env("CODEX_HOME"), "auth.json")
       File.write!(auth_path, ~s({"OPENAI_API_KEY":"sk-test"}))

test/codex/realtime/session_test.exs

@@ -250,6 +250,7 @@ defmodule Codex.Realtime.SessionTest do
       :ok = Session.subscribe(session, self())
       :ok = Session.send_message(session, "first")
       :ok = MockWebSocket.clear_sent_messages(mock_ws)
+      drain_websocket_sent_messages()
 
       :ok = Session.send_message(session, "second")
 
@@ -272,9 +273,7 @@ defmodule Codex.Realtime.SessionTest do
       )
 
       assert_receive {:session_event, %Events.AgentEndEvent{}}
-
-      messages = MockWebSocket.get_sent_messages(mock_ws)
-      assert Enum.any?(messages, &(&1["type"] == "response.create"))
+      assert_receive {:websocket_sent, %{"type" => "response.create"}}
 
       Session.close(session)
     end
@@ -306,6 +305,7 @@ defmodule Codex.Realtime.SessionTest do
       :ok = Session.subscribe(session, self())
       :ok = Session.send_message(session, "start")
       :ok = MockWebSocket.clear_sent_messages(mock_ws)
+      drain_websocket_sent_messages()
 
       tool_call =
         ModelEvents.tool_call(
@@ -316,17 +316,18 @@ defmodule Codex.Realtime.SessionTest do
         )
 
       send(session, {:model_event, tool_call})
-      Process.sleep(50)
 
-      messages = MockWebSocket.get_sent_messages(mock_ws)
-
-      assert Enum.any?(messages, fn msg ->
-               msg["type"] == "conversation.item.create" and
-                 get_in(msg, ["item", "type"]) == "function_call_output" and
-                 get_in(msg, ["item", "call_id"]) == "call_overlap"
-             end)
+      assert_receive {:websocket_sent,
+                      %{
+                        "type" => "conversation.item.create",
+                        "item" => %{
+                          "type" => "function_call_output",
+                          "call_id" => "call_overlap"
+                        }
+                      }},
+                     1_000
 
-      refute Enum.any?(messages, &(&1["type"] == "response.create"))
+      refute_receive {:websocket_sent, %{"type" => "response.create"}}, 50
 
       send(
         session,
@@ -338,9 +339,7 @@ defmodule Codex.Realtime.SessionTest do
       )
 
       assert_receive {:session_event, %Events.AgentEndEvent{}}
-
-      messages = MockWebSocket.get_sent_messages(mock_ws)
-      assert Enum.any?(messages, &(&1["type"] == "response.create"))
+      assert_receive {:websocket_sent, %{"type" => "response.create"}}
 
       Session.close(session)
     end
@@ -1130,4 +1129,12 @@ defmodule Codex.Realtime.SessionTest do
       false
     end
   end
+
+  defp drain_websocket_sent_messages do
+    receive do
+      {:websocket_sent, _message} -> drain_websocket_sent_messages()
+    after
+      0 -> :ok
+    end
+  end
 end

test/support/mock_websocket.ex

@@ -81,8 +81,7 @@ defmodule Codex.Test.MockWebSocket do
   """
   @spec send_frame(GenServer.server(), {:text, String.t()}) :: :ok
   def send_frame(pid, {:text, json}) do
-    GenServer.cast(pid, {:send_to_server, Jason.decode!(json)})
-    :ok
+    GenServer.call(pid, {:send_to_server, Jason.decode!(json)})
   end
 
   @doc """
@@ -118,6 +117,11 @@ defmodule Codex.Test.MockWebSocket do
   end
 
   @impl true
+  def handle_call({:send_to_server, message}, _from, state) do
+    send(state.test_pid, {:websocket_sent, message})
+    {:reply, :ok, %{state | sent_messages: [message | state.sent_messages]}}
+  end
+
   def handle_call(:get_sent_messages, _from, state) do
     {:reply, Enum.reverse(state.sent_messages), state}
   end