codex_sdk: harden the final quality floor

Fix format, compile warnings, docs warnings, tests, dialyzer, and credo debt
with durable code changes only.

Author: nshkrdotcom

examples/conversation_and_resume.exs

@@ -91,5 +91,16 @@ case System.argv() do
     """)
 
   _ ->
-    Examples.Conversation.multi_turn()
+    case ExamplesSupport.conversation_default_mode() do
+      :multi_turn ->
+        Examples.Conversation.multi_turn()
+
+      :save_resume ->
+        IO.puts("""
+        Ollama mode detected. Running the bounded save/resume path instead of the
+        three-turn multi-turn demo for local OSS reliability.
+        """)
+
+        Examples.Conversation.save_and_resume_demo()
+    end
 end

examples/tool_bridging_auto_run.exs

@@ -18,7 +18,7 @@ defmodule Examples.ToolBridging do
     {:ok, _handle} = Codex.Tools.register(MathTool)
 
     {:ok, thread} =
-      Codex.start_thread(approval_policy: StaticPolicy.allow())
+      Codex.start_thread(%{}, %{approval_policy: StaticPolicy.allow()})
 
     {:ok, result} =
       Codex.Thread.run_auto(thread, "Ask the math tool to add 4 and 5", max_attempts: 2)

integration/fixtures/python/thread_error_retry_then_completed.jsonl

@@ -0,0 +1,5 @@
+{"type":"thread.started","thread_id":"thread_retry_then_completed"}
+{"type":"turn.started","thread_id":"thread_retry_then_completed","turn_id":"turn_retry_then_completed"}
+{"type":"error","thread_id":"thread_retry_then_completed","turn_id":"turn_retry_then_completed","message":"Reconnecting... 1/5 (stream disconnected before completion: stream closed before response.completed)","will_retry":true}
+{"type":"item.completed","thread_id":"thread_retry_then_completed","turn_id":"turn_retry_then_completed","item":{"id":"item_retry_then_completed","type":"agent_message","text":"Recovered after reconnect."}}
+{"type":"turn.completed","thread_id":"thread_retry_then_completed","turn_id":"turn_retry_then_completed","status":"completed","final_response":{"type":"text","text":"Recovered after reconnect."},"usage":{"input_tokens":8,"cached_input_tokens":0,"output_tokens":5,"total_tokens":13}}

integration/fixtures/python/thread_error_retry_without_completion.jsonl

@@ -0,0 +1,3 @@
+{"type":"thread.started","thread_id":"thread_retry_without_completion"}
+{"type":"turn.started","thread_id":"thread_retry_without_completion","turn_id":"turn_retry_without_completion"}
+{"type":"error","thread_id":"thread_retry_without_completion","turn_id":"turn_retry_without_completion","message":"Reconnecting... 5/5 (stream disconnected before completion: stream closed before response.completed)","will_retry":true}

lib/codex/examples_support.ex

@@ -26,6 +26,11 @@ defmodule Codex.ExamplesSupport do
     if ollama_mode?(), do: nil, else: default
   end
 
+  @spec conversation_default_mode() :: :multi_turn | :save_resume
+  def conversation_default_mode do
+    if ollama_mode?(), do: :save_resume, else: :multi_turn
+  end
+
   @spec decode_json_result(Result.t()) :: {:ok, term()} | {:error, term()}
   def decode_json_result(%Result{} = result) do
     case Result.json(result) do

test/support/app_server_subprocess.ex …ex/test_support/app_server_subprocess.extest/support/app_server_subprocess.ex renamed to lib/codex/test_support/app_server_subprocess.ex test/support/app_server_subprocess.ex renamed to lib/codex/test_support/app_server_subprocess.ex

@@ -974,6 +974,7 @@ defmodule Codex.Thread do
   defp extract_turn_failure(events) do
     find_turn_failed_failure(events) ||
       find_turn_completed_failure(events) ||
+      find_completed_turn_success(events) ||
       find_error_failure(events) ||
       :ok
   end
@@ -1005,6 +1006,10 @@ defmodule Codex.Thread do
     end
   end
 
+  defp find_completed_turn_success(events) do
+    if Enum.any?(events, &completed_turn_success?/1), do: :ok, else: nil
+  end
+
   defp error_event_payload(%Events.Error{} = event) do
     %{
       "message" => event.message,
@@ -1022,6 +1027,12 @@ defmodule Codex.Thread do
 
   defp failed_turn_completed?(_event), do: false
 
+  defp completed_turn_success?(%Events.TurnCompleted{status: status})
+       when status in [nil, "completed", :completed],
+       do: true
+
+  defp completed_turn_success?(_event), do: false
+
   defp telemetry_result(:ok, true), do: :early_exit
   defp telemetry_result(:ok, false), do: :ok
   defp telemetry_result({:error, _}, _), do: :error

lib/codex/thread.ex

@@ -0,0 +1,47 @@
+defmodule Codex.ExamplesSupportTest do
+  use ExUnit.Case, async: false
+
+  alias Codex.ExamplesSupport
+
+  describe "conversation_default_mode/0" do
+    test "uses multi-turn mode outside Ollama" do
+      restore = capture_env()
+
+      on_exit(fn ->
+        restore_env(restore)
+      end)
+
+      System.delete_env("CODEX_PROVIDER_BACKEND")
+      System.delete_env("CODEX_OSS_PROVIDER")
+
+      assert ExamplesSupport.conversation_default_mode() == :multi_turn
+    end
+
+    test "uses save-resume mode in Ollama" do
+      restore = capture_env()
+
+      on_exit(fn ->
+        restore_env(restore)
+      end)
+
+      System.put_env("CODEX_PROVIDER_BACKEND", "oss")
+      System.put_env("CODEX_OSS_PROVIDER", "ollama")
+
+      assert ExamplesSupport.conversation_default_mode() == :save_resume
+    end
+  end
+
+  defp capture_env do
+    %{
+      "CODEX_PROVIDER_BACKEND" => System.get_env("CODEX_PROVIDER_BACKEND"),
+      "CODEX_OSS_PROVIDER" => System.get_env("CODEX_OSS_PROVIDER")
+    }
+  end
+
+  defp restore_env(saved) do
+    Enum.each(saved, fn
+      {key, nil} -> System.delete_env(key)
+      {key, value} -> System.put_env(key, value)
+    end)
+  end
+end

test/codex/examples_support_test.exs

@@ -60,6 +60,10 @@ defmodule Codex.Plugins.ScaffoldTest do
   end
 
   defp temp_root(prefix) do
-    Path.join(System.tmp_dir!(), "#{prefix}_#{System.unique_integer([:positive])}")
+    Path.join(System.tmp_dir!(), "#{prefix}_#{unique_suffix()}")
+  end
+
+  defp unique_suffix do
+    Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)
   end
 end

test/codex/plugins/scaffold_test.exs

@@ -159,6 +159,10 @@ defmodule Codex.Plugins.WriterTest do
   end
 
   defp temp_root(prefix) do
-    Path.join(System.tmp_dir!(), "#{prefix}_#{System.unique_integer([:positive])}")
+    Path.join(System.tmp_dir!(), "#{prefix}_#{unique_suffix()}")
+  end
+
+  defp unique_suffix do
+    Base.encode16(:crypto.strong_rand_bytes(8), case: :lower)
   end
 end