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

Open
  • Is something wrong?
#7,965 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
backend-api-design

Research direction

Read the existing combo failover and compaction controls referenced in the issue, along with the Responses JSON/SSE error handling paths. Map how eligible targets, retry admission, streaming commits, and cancellation are currently tracked before proposing the typed combo_exhausted contract. Done means reporting an accurate cause only after permitted targets are examined while preserving protocol behavior and preventing retries after visible output or ambiguous side effects.

Written by the indexing model from the issue text.

Description

enhancement
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.
Dominant language
TypeScript
Stars
16.9k
Forks
1.3k
Avg merge
16h 42m
Merged PRs (30d)
695

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lidge-jun/opencodex

All issues in lidge-jun/opencodex

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.