Codex.Realtime.Diagnostics (Codex SDK v0.16.1)

Copy Markdown View Source

Diagnostics helpers for OpenAI Realtime sessions.

The direct Realtime API occasionally returns generic server_error payloads that are hard to distinguish from SDK bugs when all you see is an example failure. This module provides:

  • a minimal raw WebSocket text-turn probe that exercises the upstream service before higher-level example logic runs
  • error classification helpers for known skip conditions
  • session-id extraction so callers can report concrete upstream evidence

Summary

Types

probe_result()

Functions

extract_session_id(error)

Extracts a Realtime session id (sess_...) from a message, map, or inspected term.

format_probe_failure(proof)

Returns a human-readable summary for a failed probe.

probe_text_turn(opts \\ [])

Runs a minimal raw-WebSocket text probe against the Realtime API.

skip_reason_for_error(error)

Maps known direct-API Realtime failures to example skip reasons.

Types

probe_result()

@type probe_result() :: %{
  model: String.t(),
  prompt: String.t(),
  session_id: String.t() | nil,
  session_created: map() | nil,
  events: [String.t()],
  error: map() | nil
}

Functions

extract_session_id(error)

@spec extract_session_id(term()) :: String.t() | nil

Extracts a Realtime session id (sess_...) from a message, map, or inspected term.

format_probe_failure(proof)

@spec format_probe_failure(probe_result()) :: String.t()

Returns a human-readable summary for a failed probe.

probe_text_turn(opts \\ [])

@spec probe_text_turn(keyword()) :: {:ok, probe_result()} | {:error, term()}

Runs a minimal raw-WebSocket text probe against the Realtime API.

The probe intentionally bypasses Codex.Realtime.Session so callers can tell whether a failure is in the upstream Realtime service or in higher-level SDK logic such as examples, tools, or handoffs.

skip_reason_for_error(error)

@spec skip_reason_for_error(term()) :: String.t() | nil

Maps known direct-API Realtime failures to example skip reasons.