apache / apache/maka

OpenCode Free: runtime model failover and health signals for per-request availability

Open
#3,449 6 comments 0 reactions 1 assignee Claimed by @SummerC0zyR0ck View on GitHub
enhancement help wanted
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.