fix(codex): retry capacity failures before stream output

[spdc-elm]

Summary

• buffer lifecycle-only OpenAI Responses events until the stream produces stateful output
• turn pre-output Codex capacity failures (server_is_overloaded and slow_down) into retryable HTTP 503 relay errors
• recognize both nested response.failed errors and top-level error / response.error SSE events
• reset first-response state before retrying and avoid auto-disabling a channel for transient capacity failures
• preserve the upstream failure as a Responses response.failed event when output was already committed or retries are exhausted

This ports and adapts the original fixes from f6a185a5 and 6c6be644 onto the current S2 main branch, including its OpenTelemetry relay tracing and stream-scanner changes.

Tests

• go test ./relay/channel/openai ./relay/common ./relay/helper ./service ./controller ./types
• go test -v ./relay/channel/openai ./relay/common ./relay/helper ./service -run 'ServerOverload|ResponsesStream|ResetFirstResponse'
• go test ./... ran successfully for all Go subpackages; the root package cannot be set up in this checkout because the generated web/classic/dist/index.html embed artifact is absent

Notes

The race-enabled suite also surfaces pre-existing races around the global logger and existing parallel polling tests; the capacity-specific and ordinary package tests pass.

[Copilot]

Pull request overview

This PR improves OpenAI Responses (Codex) streaming robustness in the gateway by buffering lifecycle-only SSE events until “stateful” output is produced, and by treating pre-output capacity failures (server_is_overloaded, slow_down) as retryable 503 relay errors. It also prevents transient capacity failures from triggering automatic channel disabling, and adds targeted regression tests for retry/stream behavior and trace “first response” timing resets.

Changes:

• Add overload-code detection helpers and use them to avoid auto-disabling channels on transient capacity failures.
• Buffer Responses SSE “prelude” events and surface pre-output capacity failures as retryable HTTP 503s (without committing downstream output).
• Add helpers + tests to ensure trace first-response state can be reset between retry attempts, and that committed streams can still receive a response.failed SSE event.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
types/error.go	Adds helpers to detect Codex capacity error codes (server_is_overloaded, slow_down).
service/channel.go	Skips auto-disable for overload errors to avoid disabling channels for transient capacity failures.
service/channel_first_response_timeout_test.go	Adds regression test ensuring overload errors do not trigger channel disabling.
relay/helper/stream_scanner.go	Fixes WaitGroup accounting via defer wg.Done() in stream goroutines.
relay/helper/common.go	Adds ResponsesStreamError helper to emit response.failed SSE after downstream stream commit.
relay/helper/common_test.go	Tests ResponsesStreamError output and headers when the stream is already committed.
relay/common/relay_info.go	Adds ResetFirstResponseTime to allow retries to record a new first-response event.
relay/common/relay_info_test.go	Tests ResetFirstResponseTime behavior across attempts.
relay/channel/openai/relay_responses.go	Buffers prelude events; converts pre-output overload failures into retryable 503s; resets first-response state before retry.
relay/channel/openai/relay_responses_test.go	Adds tests covering buffering, overload retry behavior, and overload-code recognition.
dto/openai_response.go	Adds top-level Error field to ResponsesStreamResponse to support error / response.error SSE events.
controller/relay.go	Emits response.failed SSE on overload when stream already committed; forces JSON content-type for retryable pre-output overload errors.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.