bug(openai_codex): preserve SSE error details and retry server_is_overloaded failures #234

Summary

The OpenAI Codex Responses endpoint can return an HTTP 200 SSE stream containing error and response.failed events with a structured transient-capacity error. Raven currently discards the event details and raises only:

Codex response failed

Because the original server_is_overloaded code/message is lost, Raven's shared error classifier categorizes the result as unknown instead of a retryable server failure. The user receives a generic terminal error without the normal backoff retry behavior.

Redacted evidence

A minimal OAuth-backed request returned:

http_status=200
event_type=error
event_error={
  "type": "service_unavailable_error",
  "code": "server_is_overloaded",
  "message": "Our servers are currently overloaded. Please try again later."
}
event_type=response.failed
event_error={
  "code": "server_is_overloaded",
  "message": "Our servers are currently overloaded. Please try again later."
}

The user-visible result from Raven was:

Error calling Codex: Codex response failed

OAuth was still valid, and a standalone Codex CLI request using the same account succeeded during the same diagnostic window, so this was not a missing credential or expired-subscription condition.

Root cause

On current main, raven/providers/openai_codex_provider.py::_consume_sse() handles both event types with:

elif event_type in {"error", "response.failed"}:
    raise RuntimeError("Codex response failed")

This drops event.error and event.response.error. The provider then returns the generic text as an error response. LLMProvider.classify_error() cannot see overloaded, service unavailable, or the typed service-unavailable error, so it classifies the response as non-retryable unknown.

Steps to reproduce

1. Configure a valid openai_codex OAuth provider and model.
2. Call raven doctor --probe or send an ordinary agent turn while the Codex endpoint is returning a capacity error.
3. Observe the SSE error / response.failed event with code=server_is_overloaded.
4. Observe that Raven reports only Codex response failed and does not classify it as a retryable server failure.

Expected behavior

• Preserve a safe, useful error code and message from the SSE event.
• Classify server_is_overloaded / service_unavailable_error as a transient server failure.
• Use Raven's existing retry/backoff ladder.
• Show an actionable final message if retries are exhausted.

Suggested fix scope

1. Extract error details from event.error and event.response.error in _consume_sse().
2. Raise or return an error that preserves type, code, and message without exposing credentials or request content.
3. Ensure the existing classifier sees server_is_overloaded or service unavailable and marks the failure retryable.
4. Add regression tests for:
   • error with service_unavailable_error;
   • response.failed with server_is_overloaded;
   • backoff retry followed by success;
   • retry exhaustion returning the real, safe message;
   • unrelated non-retryable SSE failures.

Environment

• macOS arm64
• Raven CLI v0.1.3 locally
• Confirmed that the same generic SSE error handling remains on current main

Privacy

This report contains no OAuth tokens, account identifiers, usernames, private paths, images, chat content, or business files.