AGENTS.md

1# model-core - Model Resolution (Core)
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
7Harness-neutral model resolution core (`@oh-my-opencode/model-core`). Resolves which model an agent or category should use via a prioritized pipeline: override, category default, user fallback, hardcoded fallback chain, system default. Consumed by `omo-opencode` (Ultimate adapter shims), `delegate-core` (task delegation), `claude-code-compat-core` (Claude Code model normalization), `skills-loader-core` (model sanitization), and `prompts-core` (variant resolution). The `ProviderCache` interface is the dependency-injection seam for connected-provider and model-metadata lookups.
8 
9## KEY FILES
10 
11| File | Role |
12|------|------|
13| `model-resolver.ts` | Entry: `resolveModel()`, `resolveModelWithFallback()`, `normalizeFallbackModels()` |
14| `model-resolution-pipeline.ts` | `resolveModelPipeline()` - 6-step resolution with logging hooks for testing |
15| `provider-cache.ts` | `ProviderCache` DI interface: `readConnectedProvidersCache()`, `findProviderModelMetadata()` |
16| `model-availability.ts` | `fuzzyMatchModel()` - exact, then shortest prefix match against `availableModels` |
17| `agent-model-requirements.ts` | Hardcoded `AGENT_MODEL_REQUIREMENTS` fallback chains (11 agents) |
18| `category-model-requirements.ts` | Hardcoded `CATEGORY_MODEL_REQUIREMENTS` fallback chains (8 categories) |
19| `provider-model-id-transform.ts` | Provider-specific ID transforms (Vercel sub-provider inference, Claude version dots, Gemini preview suffixes) |
20| `model-capabilities/index.ts` | Capability queries against bundled snapshot + runtime readers |
21| `model-capability-aliases.ts` | `resolveModelIDAlias(modelID, providerID?)` canonicalizes exact + pattern aliases; OpenAI GPT-5.6 fast service-tier alias scoped to `openai` and the `vercel` subprovider |
22| `model-family-detectors.ts` | Family predicates (`isGptModel`, `isClaudeOpus47OrLaterModel`, `isClaudeFableOrMythosModel`, `isKimiK3Model`, `isGeminiModel`, ...) |
23| `runtime-fallback-*.ts` | Error classification, auto-retry signals, and runtime fallback model selection |
24 
25## FLOW
26 
27```
28resolveModelPipeline(request, providerCache)
29  1. UI-selected model → "override"
30  2. User config model → "override"
31  3. Category default → fuzzy match availableModels, or connected provider via ProviderCache → "category-default"
32  4. User fallback_models → match availableModels or connected providers → "provider-fallback"
33  5. Hardcoded fallback chain (agent/category requirements) → cross-provider fuzzy match → "provider-fallback"
34  6. systemDefaultModel → "system-default"
35```
36 
37## NOTES
38 
39- **ProviderCache is injected**, not imported. `omo-opencode` implements it with runtime cache state; `model-core` stays pure.
40- **Two resolution APIs:** `resolveModel()` for simple 3-tier fallback; `resolveModelWithFallback()` for full pipeline with `ExtendedModelResolutionInput`.
41- **`connected-providers-cache.ts`** exports no-op defaults. Adapters override via the `ProviderCache` parameter.
42- **39 source files.** Barrel `index.ts` re-exports ~27 public modules. Tests co-located as `*.test.ts`.
43- Parent: [`packages/AGENTS.md`](../AGENTS.md)
44