OpenCode Free: runtime model failover and health signals for per-request availability
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 716
Description
Follow-up to #3409 / #3429, splitting out the layer that no static list can own.
#3429 resolves which free models are **eligible** (models.dev snapshot) and **anonymously served** (candidates ∩ `/zen/v1/models` at the discovery seam). The remaining layer is **per-request availability**, and the evidence from that thread shows why it must be reactive, at the Runtime Host execution seam:
- 429 `FreeUsageLimitError` is per-IP and point-in-time: the same id probed 429 and completed fine within hours, and the "healthiest" default was itself failing with a transient upstream 502 at one probe. No snapshot, listing, or pre-probe can encode this — pre-probing free models even burns the very quota it tries to measure.
- Today a quota-exhausted model fails the turn hard (`Recoverable: false`) and the user must switch models by hand (see the diagnostic in #3429's discussion).
Proposed direction (matching the reviewer's "Runtime Host owns connection-local health and reversible fallback"):
1. On a rate-limit/availability failure from a connection with other enabled models, fall back to the next enabled model within the turn, with a visible notice and without persisting a silent default change (reversible once the original recovers).
2. Treat an empty-content 200 completion as a model failure too — the muse-spark case shows status codes alone cannot gate health.
3. Optionally: a scheduled CI probe of the derived candidates to keep the evidence-dated deny-list in #3429 honest (flag recoveries and new persistent breakage), and the versioned built-in seed policy from #3354 to replace the deliberately lossy exact-match seed migration.
Per CONTRIBUTING, (1) changes user-visible execution behavior and should go through maintainer decision before implementation — this issue is that request.
Analysis and drafting AI-assisted (Claude Code); probes and diagnostics are from the linked PR discussion.
Contributor guide
Assessment
This issue has not been assessed yet.