#9486: feat(heartbeat): support primary/fallbacks model config
size: S
Cluster:
Model Fallbacks and Rate Limiting
## Summary
This PR adds support for defining primary and fallback models in the `heartbeat` configuration, bringing it to parity with the agent model configuration.
## Changes
- Updated `AgentDefaultsConfig` and `HeartbeatSchema` to allow `model` to be either a string (legacy) or an object with `{ primary, fallbacks }`.
- Updated `heartbeat-runner.ts` to synthesize a runtime configuration when a complex heartbeat model is used. This ensures that the heartbeat model becomes the effective default model for the run, enabling standard fallback mechanisms (`runWithModelFallback`) to work correctly without changes to the core agent runner.
- **Fix:** Tightened `HeartbeatSchema.target` validation to explicitly allow "last" and "none" literals in addition to channel ID strings, addressing review feedback.
## Motivation
Currently, the heartbeat model can only be a single string. If that model provider is down (e.g., `zai` or `openai`), the heartbeat fails entirely. This change allows users to define a cheaper/faster primary model (e.g., `gemini-2.5-flash-lite`) and reliable fallbacks (e.g., `gemini-2.5-flash`, `gpt-4o-mini`).
## AI Contribution
- **AI-Assisted**: Yes
- **Generated by**: OpenCode (Gemini 3 Pro)
- **Testing**:
- [x] Type check (`pnpm tsgo`) passed for modified files.
- [x] Automated testing (verified configuration synthesis logic via unit test).
## Local Validation
```bash
pnpm build && pnpm check && pnpm test
```
All tests pass. TypeScript compilation clean. Lint passes.
Most Similar PRs
#16289: feat: heartbeat model fallback chain support
by Unwatched2345 · 2026-02-14
81.1%
#21615: fix(tui): preserve main session model during heartbeat model override
by lailoo · 2026-02-20
74.3%
#19772: Honor configured heartbeat model overrides in all heartbeat runners
by harshang03 · 2026-02-18
72.3%
#22660: feat(agents): prioritize fallback-chain recovery and configurable r...
by sauerdaniel · 2026-02-21
70.6%
#9721: fix: heartbeat model override not working for per-agent config (#9556)
by divol89 · 2026-02-05
70.2%
#9429: fix: skip session model override for heartbeat runs
by dbottme · 2026-02-05
69.8%
#20275: fix(cli): include primary model in allowlist when adding fallbacks
by MFS-code · 2026-02-18
69.2%
#22277: fix: prevent heartbeat model override from bleeding into main session
by zhangjunmengyang · 2026-02-21
69.1%
#23738: feat(fallback): first-class transition visibility + low-noise autom...
by SmithLabsLLC · 2026-02-22
68.9%
#7981: fix(runner): use configured primary model as fallback default
by PiyushDuggal-source · 2026-02-03
68.1%