Model Resolution and Fallback

Relevant source files

This document describes the model resolution and fallback system, which ensures that agents and categories are assigned appropriate models based on available providers. The system operates at two distinct times: install-time (via CLI) and runtime (via the configuration pipeline and session hooks).

Overview

The model resolution system manages the complexity of supporting built-in agents and categories across a fragmented landscape of AI providers. The system provides:

Install-time static configuration: The CLI installer writes agent/category models to configuration files based on detected providers during setup.
5-Tier Priority Resolution: Resolves models through a priority system on every session initialization, utilizing AGENT_MODEL_REQUIREMENTS packages/model-core/src/agent-model-requirements.ts3-183
Fallback chains: Each agent/category defines an ordered list of acceptable models across providers packages/model-core/src/agent-model-requirements.ts5-29
Fuzzy matching: Model names are normalized and matched flexibly to handle provider-specific naming conventions (e.g., "claude-opus-4-7" matches "claude-opus-4.7") packages/model-core/src/model-family-detectors.ts15-18
Runtime Error Recovery: The RuntimeFallbackHook monitors for retryable errors (429, 500, 503, 529) and triggers an automatic switch to the next available model in the fallback chain packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts126-142

Sources: packages/model-core/src/agent-model-requirements.ts3-183 packages/model-core/src/model-family-detectors.ts1-85 packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts1-142

Dual-Time Architecture

The system transitions from high-level requirements (e.g., "Sisyphus needs a reasoning model") to specific code entities that manage the resolution and recovery lifecycle.

System Interaction Diagram

Sources: packages/model-core/src/agent-model-requirements.ts3-183 packages/model-core/src/model-resolution-pipeline.ts40-41 packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts16-34

Model Capability Resolution

At runtime, the system determines the specific capabilities of a resolved model (e.g., does it support "thinking" or specific modalities like PDF?).

Capability Hierarchy

The function getModelCapabilities resolves capabilities by checking multiple sources in order of priority:

Runtime Metadata: Live data from the provider's SDK or API packages/model-core/src/model-capabilities/get-model-capabilities.ts72-85
Pattern-based Aliases: Normalizing legacy IDs like claude-opus-4-7-thinking to canonical IDs packages/model-core/src/model-capabilities/get-model-capabilities.ts179-188
Bundled Snapshot: A generated JSON file containing baseline capabilities for known models packages/model-core/src/model-capabilities/get-model-capabilities.ts16-70

Model Family Detection

Fuzzy matching and family detection are handled by specialized detectors that normalize string separators and casing packages/model-core/src/model-family-detectors.ts1-85

Detector Function	Normalization Rule	Example Matches
`isGptModel`	`.toLowerCase().includes("gpt")`	`openai/gpt-5.5`, `github-copilot/gpt-4o`
`isClaudeOpus47OrLaterModel`	major > 4 or (major == 4 and minor >= 7)	`claude-opus-4.7`, `claude-fable-5`
`isKimiK27Model`	Regex `/kimi-k2[.\-]?7/`	`opencode-go/kimi-k2.7`, `k2p7`
`isGeminiModel`	Prefix check for `google/` or `google-vertex/`	`google/gemini-3.1-pro`

Sources: packages/model-core/src/model-capabilities/get-model-capabilities.ts1-225 packages/model-core/src/model-family-detectors.ts1-85

Runtime Error Recovery (The Fallback Hook)

The RuntimeFallbackHook intercepts errors and performs a "headless resume" with a different model.

Auto-Retry Dispatcher

The createAutoRetryDispatcher manages the transition between a failed model and its fallback packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts16-34 It handles complex session states such as:

Session Reservations: If a session is reserved (e.g., from a cancelled stream), it performs linear backoff before retrying the fallback dispatch packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts143-162
Active Assistant Detection: If the assistant is still active/generating during a failure, the fallback is queued until the assistant unblocks packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.test.ts138-188

Code Entity Mapping

This diagram bridges conceptual resolution to specific code entities.

Sources: packages/omo-opencode/src/hooks/runtime-fallback/auto-retry-dispatch.ts116-125 packages/model-core/src/agent-model-requirements.ts3-183 packages/model-core/src/model-family-detectors.ts1-85

Fallback Chain Structure

Data Types

The system relies on ModelRequirement definitions which specify a primary fallbackChain packages/model-core/src/agent-model-requirements.ts3-5

Agent-Specific Chains

Different agents have tailored fallback chains based on their reasoning requirements packages/model-core/src/agent-model-requirements.ts3-183:

Sisyphus (Orchestrator): Prioritizes claude-opus-4-7 (max) -> kimi-k2.6 -> gpt-5.5 (medium) packages/model-core/src/agent-model-requirements.ts4-31
Hephaestus (Worker): Strictly requires GPT-5.5 or compatible variants from OpenAI/Copilot/Venice packages/model-core/src/agent-model-requirements.ts32-42
Librarian/Explore: Optimized for speed and cost using gpt-5.4-mini-fast or qwen3.5-plus packages/model-core/src/agent-model-requirements.ts63-86

Sources: packages/model-core/src/agent-model-requirements.ts3-183 packages/model-core/src/model-requirement-types.ts1