Adopt core model normalization in codex_sdk

Delegate mixed raw/payload model input normalization to\nCliSubprocessCore.ModelInput and keep model_payload\nauthoritative.\n\nUpdate Ollama docs, examples, and tests, and switch\nDialyzer to analyze the sibling core workspace app live\ninstead of through a stale PLT snapshot.

Author: nshkrdotcom

README.md

@@ -140,11 +140,13 @@ The authoritative path is:
 - `CliSubprocessCore.ModelRegistry.validate/2`
 - `CliSubprocessCore.ModelRegistry.default_model/2`
 - `CliSubprocessCore.ModelRegistry.build_arg_payload/3`
+- `CliSubprocessCore.ModelInput.normalize/3`
 
-`Codex.Options.new/1` resolves a shared `model_payload`, then projects the
-current `model` and `reasoning_effort` from that 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.
+`Codex.Options.new/1` now delegates mixed-input normalization to
+`CliSubprocessCore.ModelInput.normalize/3`, then projects the current `model`
+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.
 
 Operationally, that means:
 
@@ -173,12 +175,22 @@ That causes the shared core registry to:
 
 - validate the Ollama runtime
 - validate the local model id
-- enforce the Codex OSS default and reasoning rules
+- keep `gpt-oss:20b` as the default validated OSS model when no explicit model
+  is supplied
 - return a payload that renders `--oss --local-provider ollama --model llama3.2`
 
 The SDK does not infer those flags on its own.
 - CLI argument rendering only emits `--model` from a non-empty resolved value
 
+If `ollama_base_url:` is supplied, that endpoint is carried inside the
+payload-owned env overrides as `CODEX_OSS_BASE_URL`. The exec and app-server
+transports both consume that payload data directly instead of keeping a second
+raw base-url path alive downstream.
+
+When the chosen local model is outside Codex's built-in model metadata catalog,
+the upstream CLI may warn that it is using fallback metadata. That is an
+upstream degraded-mode distinction, not a hard model rejection in `codex_sdk`.
+
 For the stateful app-server transport, the same resolved payload is rendered into
 supported `codex app-server --config ...` startup overrides plus `thread/start`
 `modelProvider` selection. The SDK does not pass unsupported exec-only OSS flags

examples/README.md

@@ -39,18 +39,24 @@ Run the same CLI-backed example set against local Codex OSS + Ollama:
 
 ```bash
 ./examples/run_all.sh --ollama
+./examples/run_all.sh --ollama --ollama-model gpt-oss:20b
 ./examples/run_all.sh --ollama --ollama-model llama3.2
 ```
 
 `--ollama` sets:
 
 - `CODEX_PROVIDER_BACKEND=oss`
 - `CODEX_OSS_PROVIDER=ollama`
-- `CODEX_MODEL=llama3.2` by default
+- `CODEX_MODEL=gpt-oss:20b` by default
 
 The runner checks that the requested Ollama model is installed before starting
 the examples.
 
+`gpt-oss:20b` remains the default validated Codex/Ollama example model, but
+the runner also accepts other installed Ollama models such as `llama3.2`.
+Those non-default models may trigger upstream fallback metadata warnings and
+can behave less reliably under the full Codex agent prompt/tool stack.
+
 In `--ollama` mode, the runner:
 
 - executes the full CLI-backed example suite against the local Ollama-backed Codex route

examples/run_all.sh

@@ -10,7 +10,7 @@ Usage: bash examples/run_all.sh [--ollama] [--ollama-model MODEL] [--help]
 
 Options:
   --ollama               Run all examples against local Codex OSS + Ollama.
-  --ollama-model MODEL   Override the Ollama model. Default: llama3.2
+  --ollama-model MODEL   Override the Ollama model. Default: gpt-oss:20b
   --help                 Show this help text.
 EOF
 }
@@ -53,7 +53,7 @@ else
 fi
 
 if [[ "${CODEX_PROVIDER_BACKEND:-}" == "oss" && "${CODEX_OSS_PROVIDER:-}" == "ollama" ]]; then
-  OLLAMA_MODEL="${CODEX_MODEL:-llama3.2}"
+  OLLAMA_MODEL="${CODEX_MODEL:-gpt-oss:20b}"
   export CODEX_MODEL="${OLLAMA_MODEL}"
 
   if ! command -v ollama >/dev/null 2>&1; then

guides/03-api-guide.md

@@ -88,6 +88,10 @@ opts.model_payload.backend_metadata["oss_provider"]
 # => "ollama"
 ```
 
+`gpt-oss:20b` remains the default validated OSS example when no explicit model
+is provided, but other installed Ollama models can be passed through this same
+route.
+
 ---
 
 ## Codex.CLI and Codex.CLI.Session
@@ -204,6 +208,27 @@ 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`.
 
+---
+
+## Shared Model Normalization
+
+`Codex.Options.new/1` does not own a second model-resolution pipeline. It now
+delegates mixed raw/payload input normalization to
+`CliSubprocessCore.ModelInput.normalize/3`, then projects `model`,
+`reasoning_effort`, and transport settings from the resulting
+`model_payload`.
+
+That matters most on the local Ollama route:
+
+- raw attrs such as `model`, `provider_backend`, `oss_provider`, and
+  `ollama_base_url` normalize once in the shared core
+- an explicit `model_payload` is authoritative when supplied
+- conflicting raw attrs fail during normalization instead of being silently
+  reinterpreted in the SDK
+- a custom Codex/Ollama base URL is carried inside payload env overrides as
+  `CODEX_OSS_BASE_URL`, so exec and app-server transports can rely on the
+  payload alone after normalization
+
 `connect/2` also accepts `oauth:` for child-auth-aware startup:
 
 ```elixir

lib/codex/examples_support.ex

@@ -13,7 +13,7 @@ defmodule Codex.ExamplesSupport do
 
   @spec ollama_model() :: String.t()
   def ollama_model do
-    System.get_env("CODEX_MODEL") || "llama3.2"
+    System.get_env("CODEX_MODEL") || "gpt-oss:20b"
   end
 
   @spec example_model(String.t() | nil) :: String.t()

lib/codex/options.ex

@@ -6,7 +6,7 @@ defmodule Codex.Options do
   """
 
   require Bitwise
-  alias CliSubprocessCore.ModelRegistry
+  alias CliSubprocessCore.ModelInput
   alias Codex.Auth
   alias Codex.Config.BaseURL
   alias Codex.Config.OptionNormalizers
@@ -80,22 +80,26 @@ defmodule Codex.Options do
          {:ok, base_url} <- fetch_base_url(attrs),
          {:ok, override} <- fetch_codex_path_override(attrs),
          {:ok, telemetry_prefix} <- fetch_telemetry_prefix(attrs),
-         {:ok, model_payload} <- resolve_model_payload(attrs, auth_mode_for(api_key)),
+         {:ok, model_input} <- normalize_model_input(attrs),
+         model_payload = model_input.selection,
+         normalized_attrs = model_input.attrs,
          {:ok, model} <- fetch_model(model_payload),
          {:ok, reasoning_effort} <- fetch_reasoning_effort(model_payload),
-         {:ok, model_personality} <- fetch_model_personality(attrs),
-         {:ok, reasoning_summary} <- fetch_reasoning_summary(attrs),
-         {:ok, model_verbosity} <- fetch_model_verbosity(attrs),
-         {:ok, model_context_window} <- fetch_model_context_window(attrs),
-         {:ok, supports_reasoning_summaries} <- fetch_supports_reasoning_summaries(attrs),
-         {:ok, model_auto_compact_token_limit} <- fetch_model_auto_compact_token_limit(attrs),
-         {:ok, review_model} <- fetch_review_model(attrs),
-         {:ok, history_persistence} <- fetch_history_persistence(attrs),
-         {:ok, history_max_bytes} <- fetch_history_max_bytes(attrs),
-         {:ok, hide_agent_reasoning} <- fetch_hide_agent_reasoning(attrs),
-         {:ok, tool_output_token_limit} <- fetch_tool_output_token_limit(attrs),
-         {:ok, agent_max_threads} <- fetch_agent_max_threads(attrs),
-         {:ok, config_overrides} <- fetch_config_overrides(attrs) do
+         {:ok, model_personality} <- fetch_model_personality(normalized_attrs),
+         {:ok, reasoning_summary} <- fetch_reasoning_summary(normalized_attrs),
+         {:ok, model_verbosity} <- fetch_model_verbosity(normalized_attrs),
+         {:ok, model_context_window} <- fetch_model_context_window(normalized_attrs),
+         {:ok, supports_reasoning_summaries} <-
+           fetch_supports_reasoning_summaries(normalized_attrs),
+         {:ok, model_auto_compact_token_limit} <-
+           fetch_model_auto_compact_token_limit(normalized_attrs),
+         {:ok, review_model} <- fetch_review_model(normalized_attrs),
+         {:ok, history_persistence} <- fetch_history_persistence(normalized_attrs),
+         {:ok, history_max_bytes} <- fetch_history_max_bytes(normalized_attrs),
+         {:ok, hide_agent_reasoning} <- fetch_hide_agent_reasoning(normalized_attrs),
+         {:ok, tool_output_token_limit} <- fetch_tool_output_token_limit(normalized_attrs),
+         {:ok, agent_max_threads} <- fetch_agent_max_threads(normalized_attrs),
+         {:ok, config_overrides} <- fetch_config_overrides(normalized_attrs) do
       {:ok,
        %__MODULE__{
          api_key: api_key,
@@ -214,46 +218,34 @@ defmodule Codex.Options do
 
   defp pick(_attrs, [], default), do: default
 
-  defp resolve_model_payload(attrs, _auth_mode) do
-    requested_model = pick(attrs, [:model, "model"])
-
-    provider_backend =
-      pick(
-        attrs,
-        [:provider_backend, "provider_backend"],
-        System.get_env("CODEX_PROVIDER_BACKEND")
-      )
-
-    oss_provider =
-      pick(attrs, [:oss_provider, "oss_provider"], System.get_env("CODEX_OSS_PROVIDER"))
-
-    ollama_base_url =
-      pick(attrs, [:ollama_base_url, "ollama_base_url"], System.get_env("CODEX_OLLAMA_BASE_URL"))
-
-    requested_reasoning =
-      pick(attrs, [:reasoning_effort, "reasoning_effort", :reasoning, "reasoning"])
-
-    opts =
-      []
-      |> maybe_put_env_model(
-        System.get_env("CODEX_MODEL") ||
-          System.get_env("OPENAI_DEFAULT_MODEL") ||
-          System.get_env("CODEX_MODEL_DEFAULT")
-      )
-      |> maybe_put_reasoning(requested_reasoning)
-      |> maybe_put_registry_opt(:provider_backend, provider_backend)
-      |> maybe_put_registry_opt(:oss_provider, oss_provider)
-      |> maybe_put_registry_opt(:ollama_base_url, ollama_base_url)
-      |> maybe_put_registry_opt(
-        :ollama_http,
-        pick(attrs, [:ollama_http, "ollama_http"])
-      )
-      |> maybe_put_registry_opt(
-        :ollama_timeout_ms,
-        pick(attrs, [:ollama_timeout_ms, "ollama_timeout_ms"])
-      )
-
-    ModelRegistry.build_arg_payload(:codex, requested_model, opts)
+  defp normalize_model_input(attrs) do
+    attrs
+    |> apply_model_env_defaults()
+    |> then(&ModelInput.normalize(:codex, &1, []))
+  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"))
+  end
+
+  defp put_missing_attr(attrs, _key, nil), do: attrs
+  defp put_missing_attr(attrs, _key, ""), do: attrs
+
+  defp put_missing_attr(attrs, key, value) when is_map(attrs) and is_atom(key) do
+    cond do
+      Map.has_key?(attrs, key) -> attrs
+      Map.has_key?(attrs, Atom.to_string(key)) -> attrs
+      true -> Map.put(attrs, key, value)
+    end
   end
 
   defp fetch_model(model_payload) when is_map(model_payload) do
@@ -267,16 +259,6 @@ defmodule Codex.Options do
     {:ok, normalize_reasoning_atom(reasoning)}
   end
 
-  defp maybe_put_env_model(opts, nil), do: opts
-  defp maybe_put_env_model(opts, env_model), do: Keyword.put(opts, :env_model, env_model)
-
-  defp maybe_put_reasoning(opts, nil), do: opts
-  defp maybe_put_reasoning(opts, reasoning), do: Keyword.put(opts, :reasoning_effort, reasoning)
-
-  defp maybe_put_registry_opt(opts, _key, nil), do: opts
-  defp maybe_put_registry_opt(opts, _key, ""), do: opts
-  defp maybe_put_registry_opt(opts, key, value), do: Keyword.put(opts, key, value)
-
   defp normalize_reasoning_atom(nil), do: nil
   defp normalize_reasoning_atom(value) when is_atom(value), do: value
   defp normalize_reasoning_atom(value) when is_binary(value), do: String.to_atom(value)
@@ -423,9 +405,6 @@ defmodule Codex.Options do
     |> Overrides.normalize_config_overrides()
   end
 
-  defp auth_mode_for(api_key) when is_binary(api_key) and api_key != "", do: :api
-  defp auth_mode_for(_), do: Auth.infer_auth_mode()
-
   defp normalize_string(nil), do: nil
 
   defp normalize_string(value) when is_binary(value) do