#8274: feat(cron): add payload.fallbacks support for isolated jobs
stale
Cluster:
Model Fallbacks and Rate Limiting
## Summary
- Adds `payload.fallbacks` field to `agentTurn` payloads for isolated cron jobs
- Validates each fallback against the model catalog before execution
- Payload fallbacks take priority over agent-level and global fallbacks
- Empty array `[]` explicitly disables fallbacks (doesn't fall back to agent/global config)
## Alignment with Project Goals 🎯
This PR directly supports the **Performance** priority from the roadmap:
> **Performance**: Optimizing token usage and compaction logic.
With `payload.fallbacks`, users can now:
- **Optimize token costs per job**: Use cheaper/faster models (like Haiku) as primary with expensive models as fallback only when needed
- **Reduce latency**: Configure lightweight models for time-sensitive jobs without sacrificing reliability
- **Fine-tune by use case**: Different jobs can have different fallback strategies without creating separate agents
- **Avoid over-provisioning**: No need to default to expensive models "just in case" - fallbacks handle failures gracefully
## Motivation
Currently, isolated jobs with `agentTurn` support `payload.model` for model override, but **do not support** `payload.fallbacks` for job-specific fallbacks. This forces users to create separate agents just to have different fallbacks, which is verbose and unnecessary.
## Changes
- **`src/cron/types.ts`**: Added `fallbacks?: string[]` to `CronPayload` and `CronPayloadPatch`
- **`src/cron/isolated-agent/run.ts`**: Extract, validate, and pass payload fallbacks to `runWithModelFallback()`
- **`src/cron/isolated-agent.payload-fallbacks.test.ts`**: 6 tests covering all scenarios
## Fallback Priority (now)
1. `payload.fallbacks` (if defined)
2. `agents.list[agentId].model.fallbacks`
3. `agents.defaults.model.fallbacks`
## Example Usage
```json
{
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "Generate portfolio report...",
"model": "anthropic/claude-haiku-4-5-20251001",
"fallbacks": ["opencode/kimi-k2.5-free", "anthropic/claude-sonnet-4-20250514"]
}
}
```
## Test plan
- [x] `payload.fallbacks` is correctly passed to `runWithModelFallback`
- [x] Invalid fallbacks (not array) return error
- [x] Invalid fallback entries (not strings) return error
- [x] Disallowed models return error
- [x] Empty `[]` disables fallbacks
- [x] Undefined payload.fallbacks falls back to agent config
- [x] All existing tests pass
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Most Similar PRs
#19252: fix(agents): continue model fallback on failover text payloads
by mahsumaktas · 2026-02-17
73.5%
#23738: feat(fallback): first-class transition visibility + low-noise autom...
by SmithLabsLLC · 2026-02-22
72.7%
#8390: feat: notify user when fallback model is used (#8182)
by Glucksberg · 2026-02-04
71.1%
#21279: Fix/sessions list cron model override
by altaywtf · 2026-02-19
69.1%
#16303: fix: apply cron payload.model override to session entry and pass au...
by superlowburn · 2026-02-14
68.6%
#23816: fix(agents): model fallback skipped during session overrides and pr...
by ramezgaberiel · 2026-02-22
68.0%
#23318: feat(agents): emit model:fallback hook event for fallback visibilit...
by anillBhoi · 2026-02-22
67.7%
#18028: fix(cron): support partial payload patches in job updates
by andrewdamelio · 2026-02-16
66.7%
#21454: fix(cron): skip isError payloads when picking summary/delivery content
by Diaspar4u · 2026-02-19
66.6%
#13191: pi-embedded: enable failover when per-agent fallbacks are configured
by zesty-clawd · 2026-02-10
66.1%