[Feature] Structured exhausted-combo diagnostics for unattended agent sessions #7965

What are you trying to accomplish?

Make long-running agentic sessions reliably report why a configured failover combo cannot continue, without mistaking a single target error for a globally exhausted combo. Users away from the client need a clear, machine-readable terminal condition that a compatible client can render professionally and use for alerts.

What prevents this today?

In OpenCodex v2.93.0, provider errors are surfaced as raw error text or a last-target refusal after failover. A multi-provider combo can contain different failures at once (provider access denied, quota cooldown, upstream transient, unsupported mandatory-tool wire choice). An HTTP 400/403/429 from one target is not proof all targets lack tokens. Conversely, a final exhausted combo lacks a stable, distinct, cross-provider diagnostic contract suitable for clients to display as an actionable summary.

Real operator observation: long agentic work in a Codex client stopped with Provider error 400: Antigravity invalid request. Separate live testing confirmed a Meta Responses tool_choice=required compatibility 400 when a combo selects Meta; filed as #7964. These are two distinct failure classes and this request must not bypass existing replay/side-effect protections.

Expected behavior

1. Keep existing safe retry and failover admission: never retry after committed visible output or ambiguous side effects; do not retry 403 policy restrictions or malformed client requests.
2. Only after all eligible and permitted configured targets have been examined, emit a stable typed failure such as combo_exhausted with combo ID, high-level cause classification (quota, permission, capacity, transient, incompatible request, mixed/unknown), number of eligible/attempted targets, and optional bounded retry time derived from trusted provider evidence. Do not expose account IDs, secrets, prompts, or internal config.
3. Distinguish all targets quota-exhausted from mixed provider causes and no target supports required tooling; do not invent a reason or claim credits are exhausted based solely on an HTTP 400.
4. Preserve the original client protocol (Responses JSON/SSE terminal semantics) and make the typed error available to the UI, telemetry, and alerting without hardcoding visual elements in the proxy.
5. Handle partial streaming, cancellations, cooldown races, account revisions, and late successes; a network retry cannot repeat tool side effects or a committed response.

Suggested operator-facing wording

• Quota-only: “El combo RHODIZ no tiene destinos disponibles por límites de uso. Espera al restablecimiento de cuota o revisa los planes de tus proveedores.”
• Mixed: “El combo RHODIZ no pudo completar la solicitud. Algunos proveedores rechazaron el acceso y otros están limitados. Revisa los destinos o selecciona otro combo compatible.”
• Capability-only: “Ningún destino del combo admite las herramientas obligatorias de esta solicitud.”
  The client should choose layout, severity and notification behavior.

Alternatives or workarounds

Operators can parse logs manually or switch combos, but that does not provide reliable unattended diagnostics. Rewriting every upstream error to “out of tokens” would be misleading and dangerous. A documented typed response is backward-compatible if clients without specialized rendering still receive useful concise text.

Version / environment

OpenCodex v2.93.0 Linux, multi-provider Responses failover combos; no secrets or original prompts included. Related issues #7443 (context-specific 400 hops), #7850 (compaction routing), #7964 (Meta required-tool capability).

Checks

• Searched related issues and reviewed the existing combo failover/compaction controls.
• Operator request is a new error-reporting contract, not a claim that all retries are missing.
• No credentials, private account data or conversation contents included.