v0.3.0 — First public @razroo release

First public release of @razroo/opencode-model-fallback. OpenCode plugin that rotates through a configured fallback_models chain when a model returns rate-limit / 5xx / known provider errors, then replays the in-flight request on the next model.

Features

• Per-agent fallback chains. Each agent in opencode.json can declare its own fallback_models: [...] ordered list.
• Global fallback chain. A single chain in .opencode/opencode-model-fallback.json(c) applies to agents that don't declare their own.
• Comprehensive error detection. HTTP status codes (429, 500, 502, 503, 504) + pattern-matching on error messages (rate limit, overloaded, quota exceeded, insufficient credits, etc.) — works around opencode's error-prettifier sometimes stripping status codes.
• TTFT timeout. Aborts models that produce no tokens within a configurable window (default 30s). Actively-streaming models are never interrupted.
• Cooldown + auto-recovery. Failed models enter a cooldown period (default 60s); the plugin automatically switches back to the primary once it recovers.
• Custom retryable patterns. Extend built-in error matching with your own regex patterns via retryable_error_patterns: [...]. Invalid regexes warn once and skip.
• Init-time validation. Malformed fallback_models entries (not matching provider/model format) are flagged in the first log line instead of silently skipping at dispatch.
• Structured logging to ~/.config/opencode/opencode-model-fallback.log with trigger error, original model, fallback model, timestamp, and source event. 10MB rotation with single backup (.log.1).
• Toast notifications on fallback events (opt-out via notify_on_fallback: false).
• Subagent result sync. Parent sessions correctly receive the fallback model's response when a child session rotates mid-execution.

Install

```bash
npm install @razroo/opencode-model-fallback
```

Configure

```json
{
"plugin": ["@razroo/opencode-model-fallback"],
"agent": {
"coder": {
"model": "anthropic/claude-opus-4-6",
"fallback_models": ["openai/gpt-5.4", "kimi-for-coding/k2p5"]
}
}
}
```

Optional tuning at .opencode/opencode-model-fallback.json or ~/.config/opencode/opencode-model-fallback.json:

```json
{
"enabled": true,
"cooldown_seconds": 60,
"timeout_seconds": 30,
"max_fallback_attempts": 10,
"notify_on_fallback": true,
"retryable_error_patterns": ["custom-pattern-here"]
}
```

Requirements

• @opencode-ai/plugin >= 1.1.19 (peer)
• @opencode-ai/sdk (optional peer, required only if you use compaction-model fallback)
• Node >= 18

Notes

• Built with Bun; ships pre-compiled dist/ — no build step at install time.
• 387 tests across 13 test files. See src/*.test.ts.