Add reason_code to TransportError and normalize payload errors

Updated Codex.TransportError to include a reason_code field for structured
error reporting. The Exec module now extracts the error code from incoming
payloads, normalizing binary strings to atoms to maintain consistent
internal representation. Codex.Error.normalize was updated to ensure this
metadata is preserved and surfaced during error handling.

Author: nshkrdotcom

lib/codex/error.ex

@@ -60,7 +60,8 @@ defmodule Codex.Error do
         exit_status: error.exit_status,
         stderr: error.stderr,
         stderr_truncated?: error.stderr_truncated?,
-        retryable?: error.retryable?
+        retryable?: error.retryable?,
+        reason_code: error.reason_code
       }
       |> Enum.reject(fn {_key, value} -> is_nil(value) end)
       |> Map.new()

lib/codex/runtime/exec.ex

@@ -89,16 +89,21 @@ defmodule Codex.Runtime.Exec do
 
   @spec session_error(CoreEvent.t(), binary(), boolean()) :: {:error, term()} | nil
   def session_error(
-        %CoreEvent{kind: :error, raw: %{exit: %CoreProcessExit{} = exit}},
+        %CoreEvent{
+          kind: :error,
+          raw: %{exit: %CoreProcessExit{} = exit},
+          payload: %Payload.Error{} = payload
+        },
         stderr,
         stderr_truncated?
       ) do
     {:error,
      Codex.TransportError.new(exit_code(exit),
-       message: exit_message(exit),
+       message: payload.message || exit_message(exit),
        stderr: stderr,
        stderr_truncated?: stderr_truncated?,
-       retryable?: retryable_exit?(exit)
+       retryable?: retryable_exit?(exit),
+       reason_code: normalize_reason_code(payload.code)
      )}
   end
 
@@ -545,6 +550,16 @@ defmodule Codex.Runtime.Exec do
     "codex executable exited: #{inspect(reason)}"
   end
 
+  defp normalize_reason_code(nil), do: nil
+  defp normalize_reason_code(code) when is_atom(code), do: code
+
+  defp normalize_reason_code(code) when is_binary(code) do
+    code
+    |> String.downcase()
+    |> String.replace("-", "_")
+    |> String.to_atom()
+  end
+
   defp retryable_exit?(%CoreProcessExit{} = exit),
     do: Codex.TransportError.retryable_status?(exit_code(exit))
 end

lib/codex/transport_error.ex

@@ -7,14 +7,15 @@ defmodule Codex.TransportError do
   whether to attempt automatic retries.
   """
 
-  defexception [:message, :exit_status, :stderr, :stderr_truncated?, :retryable?]
+  defexception [:message, :exit_status, :stderr, :stderr_truncated?, :retryable?, :reason_code]
 
   @type t :: %__MODULE__{
           message: String.t(),
           exit_status: integer(),
           stderr: String.t() | nil,
           stderr_truncated?: boolean(),
-          retryable?: boolean()
+          retryable?: boolean(),
+          reason_code: atom() | nil
         }
 
   @doc """
@@ -39,7 +40,8 @@ defmodule Codex.TransportError do
       stderr: stderr,
       stderr_truncated?: stderr_truncated?,
       message: message,
-      retryable?: retryable?
+      retryable?: retryable?,
+      reason_code: Keyword.get(opts, :reason_code)
     }
   end
 

test/codex/error_test.exs

@@ -1,7 +1,7 @@
 defmodule Codex.ErrorTest do
   use ExUnit.Case, async: true
 
-  alias Codex.{Error, Options, Thread}
+  alias Codex.{Error, Options, Thread, TransportError}
   alias Codex.Thread.Options, as: ThreadOptions
 
   test "non-zero codex exit normalizes into Codex.Error" do
@@ -37,6 +37,20 @@ defmodule Codex.ErrorTest do
     assert error.details.codex_error_info == %{"code" => "rate_limit"}
   end
 
+  test "normalize/1 preserves transport reason codes" do
+    error =
+      TransportError.new(127,
+        message: "Codex CLI not found on remote target ssh-target.example",
+        stderr: "env: 'codex': No such file or directory",
+        reason_code: :cli_not_found
+      )
+      |> Error.normalize()
+
+    assert error.message =~ "Codex CLI not found"
+    assert error.details.reason_code == :cli_not_found
+    assert error.details.exit_status == 127
+  end
+
   defp temp_script(contents) do
     path = Path.join(System.tmp_dir!(), "codex_error_#{System.unique_integer([:positive])}")
     File.write!(path, contents)