# `Codex.Realtime.Diagnostics`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.16.1/lib/codex/realtime/diagnostics.ex#L1)

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

# `probe_result`

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

# `extract_session_id`

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

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

# `format_probe_failure`

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

Returns a human-readable summary for a failed probe.

# `probe_text_turn`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*