v1.2.2

[1.2.2] - 2026-05-22

Added

• Consolidated Agent Guidelines — Merged CLAUDE.md and AGENTS.md into a single canonical AGENTS.md file. CLAUDE.md is now a symlink to AGENTS.md so both Claude Code and other agents read from the same source.
• Release Process Documentation — Added complete release process steps to AGENTS.md (version bump, changelog, tag, GitHub release, npm publish, verification).

Fixed

• Model Metadata Overrides for Provider Models — Fixed model metadata overrides not being applied to provider models returned by the provider hook. (src/plugin.ts) (@Alph4d0g)

v1.2.1

Release v1.2.1

Highlights

• Model Variant Support Fix — Variant-suffixed models (e.g., codex/gpt-5.5-xhigh, codex/gpt-5.5-high) are now grouped under their base model ID instead of appearing as duplicate top-level entries. Includes synthetic base model creation, xhigh variant support, and getModelFamily() fix for provider-prefixed versioned models.
• models.dev enrichment no longer fails on transient network slowness. The fetch pipeline now retries up to 3 times with exponential backoff and falls back to stale cached data if live refresh fails.
• Default context limit corrected from 4096 to 128000 tokens to match OmniRoute API behavior.
• Structured observability for enrichment failures with per-attempt diagnostics and fallback decisions.

What Changed

Reliability

• fetchModelsDevData() now uses a bounded retry loop:
  • Maximum 3 attempts with 250ms / 500ms backoff.
  • Retries on: timeouts (AbortError), network errors, HTTP 429, and HTTP 5xx.
  • Fail-fast on: HTTP 4xx (non-429) and structurally invalid responses.
• Stale in-memory cache fallback:
  • If cached data exists but TTL expired, live refresh is attempted first.
  • If all refresh attempts fail, the stale cached data is returned instead of null.
  • If no cache exists and all attempts fail, returns null (safe fail-open).
• Timeout budget increased from 1000ms to 5000ms per attempt.
• Failure classification: timeout, network, http_retryable, http_non_retryable, parse, invalid_structure.

Model Variant Support Fix

Problem: When OmniRoute lists variant-suffixed models separately (e.g., codex/gpt-5.5-xhigh, codex/gpt-5.5-high), each variant appeared as an independent top-level entry with incorrect generated variants ({low, medium, high}), causing duplicate/confusing model entries in OpenCode's model picker.

Solution:

• Added groupVariantModels() in src/models.ts — a pure two-pass algorithm that:
  1. Categorizes models into real bases and variants using stripVariantSuffix()
  2. Builds result: real bases pass through unchanged; for each base with variants, merges all variants under the base model with a variants Record
  3. Synthetic bases: when only variants are returned (no explicit base), creates a synthetic base from the first variant, copying all fields and setting id/name to the stripped base ID
  4. Metadata merging: base inherits max contextWindow, max maxTokens, and the union of supported capability flags across all variants
• Integrated into fetchModels() pipeline: normalizeModel → deduplicateModels → groupVariantModels → enrichModelMetadata → toProviderModels
• Fixed toProviderModel() in src/plugin.ts to prioritize pre-populated model.variants over generated {low, medium, high} defaults
• Added 'xhigh' to OmniRouteModelVariant.reasoningEffort type and generated variants

Edge Cases Handled:

Scenario	Behavior
Only variants returned, no base model	Creates synthetic base from first variant
Base model + variants both returned	Uses real base; merges variant metadata (max limits)
Non-reasoning suffix (e.g., -preview)	stripVariantSuffix() ignores it; no grouping
Mixed provider prefixes post-dedup	Grouping operates on canonical IDs
Variant without supportsReasoning=true	Still grouped; base becomes true if any variant has it

Fixes

• DEFAULT_CONTEXT_LIMIT corrected from 4096 to 128000.
• getModelFamily() for Provider-Prefixed Models — Fixed incorrect family extraction for versioned models with provider prefixes. getModelFamily('codex/gpt-5.5-xhigh') now correctly returns 'gpt' (was 'codex/gpt').

Code Review Fixes

• Cache Isolation — modelsDevCache is now keyed by URL (Map<string, ModelsDevCache>) to prevent cross-config data leakage when different configs specify different modelsDev.url values.
• JSDoc Accuracy — OmniRouteModelsDevConfig.timeoutMs JSDoc updated to reflect the new 5000ms default.
• Lockfile Sync — package-lock.json version aligned with package.json (1.2.1).
• Test Suite Speed — Eliminated real setTimeout sleeps from test/models-dev.test.mjs by using cacheTtl: 0 for stale-cache tests. Reduces test runtime and improves scalability.
• Latency Documentation — Explicit JSDoc added on fetchModelsDevData() documenting worst-case cold-start latency (~15.75s) as an accepted reliability trade-off.
• models.dev Structural Validation — Fetched models.dev payloads now validate provider entries and nested models records before accepting data, preventing malformed upstream objects from entering cache/index paths.
• Variant Capability Union — Grouped variants now merge supportsVision, supportsTools, supportsStreaming, supportsTemperature, and supportsAttachment into the base model when any variant advertises those capabilities.

Testing

• Added 9 focused tests in test/models-dev.test.mjs covering all retry, cache, fallback, and malformed-provider validation paths.
• Added 1 unit test in test/models.test.mjs covering capability union across grouped variants.
• Added 2 regression tests in test/plugin.test.mjs for variant grouping and synthetic base model creation.
• Added cache isolation (clearModelCache(), clearModelsDevCache()) to test/plugin.test.mjs afterEach to prevent cross-test contamination.
• Full regression suite: 54/54 tests pass (0 failures).

Documentation

• Internal docs/superpowers/ planning/spec artifacts are kept local only and are excluded from the GitHub repository.

Verification

• npm run prepublishOnly passes (clean, build, check:exports).
• npm test passes: 54 tests, 0 failures.
• TypeScript strict mode compiles cleanly.

Upgrade Notes

• No breaking changes. Plugin behavior remains safe when models.dev is fully unavailable.
• Existing modelsDev.timeoutMs and modelsDev.cacheTtl config options continue to work as before.

v1.2.0 - Model metadata enrichment

Highlights

Thank you to everyone using and improving opencode-omniroute-auth. This release focuses on making OmniRoute model metadata richer, safer, and more accurate inside OpenCode.

Added

• Comprehensive model metadata normalization across camelCase fields, snake_case fields, and OmniRoute capabilities objects.
• Provider alias deduplication for known aliases such as cx -> codex and ollamacloud -> ollama-cloud.
• Extended OmniRoute model capability enrichment with context limits, output token limits, vision, tool calling, reasoning, thinking, attachment, and temperature metadata.
• Validation for array-based user modelMetadata blocks, including warning logs for invalid entries.
• New test coverage for normalization precedence, snake_case field handling, and deduplication behavior.

Changed

• User-provided array-based modelMetadata now takes precedence over generated metadata in first-match-wins systems.
• Metadata keys using known alias prefixes are canonicalized to match deduplicated model IDs.
• Unknown provider prefixes now merge metadata instead of overwriting existing entries.

Fixed

• Preserved alias metadata by merging it into canonical model entries instead of dropping it.
• Removed unreachable deduplication logic.
• Addressed review feedback around metadata precedence, validation, unknown-prefix merging, and alias simplification.

Thanks

Special thanks to the users and contributors who tested OmniRoute model enrichment, reported edge cases, and helped refine OpenCode compatibility. Your feedback directly shaped the metadata precedence, validation, and alias-handling improvements in this release.

Full Changelog: v1.1.4...v1.2.0

v1.1.4 — Provider hook for OpenCode >=1.14.49

What's New

Added

• Added hook for OpenCode >=1.14.49 model listing API (), enabling dynamic model fetching when authentication is available. (@kkMihai)
• Added , , , and type definitions matching the v1.14.50 API. (@kkMihai)
• Added 3 regression tests covering provider hook behavior: live model fetch with auth, fallback without auth, and error recovery. (@kkMihai)

Fixed

• Fixed model picker only showing 4 hardcoded fallback models on OpenCode >=1.14.49 by supplying models through the new hook callback. (@kkMihai)
• Fixed stale fallback in no-auth branch to always return plugin-native defaults with correct and metadata.
• Fixed misleading comment in fetch-failure recovery test.

Changed

• Improved test coverage for unauthenticated state to explicitly verify rejection of stale host-provided models.
• Improved formatting consistency in type definitions.

Verification

• TypeScript compilation: 0 errors
• Test suite: 25/25 pass

Full Changelog: v1.1.3...v1.1.4

v1.1.3

What's New in v1.1.3

Added

• Proper logging: New src/logger.ts module that writes to OpenCode's log file instead of polluting the console
  • warn() always writes to the log
  • debug() only writes when OMNIROUTE_DEBUG=1 is set
  • Automatically finds the most recent .log file in ~/.local/share/opencode/log/
  • Handles log rotation by re-scanning when the cached file is deleted
  • Silently fails on all I/O errors — never crashes the plugin
• Logger tests: 13 comprehensive unit tests in test/logger.test.mjs

Changed

• Replaced all 46 console.log/console.warn/console.error calls across 4 source files with the new logger
• Log format now matches OpenCode's native format: WARN 2026-05-15T12:34:56.789Z +0ms service=omniroute <message>

Fixed

• Fixed 2 pre-existing failing model cache tests that were incorrectly counting all fetch calls instead of only /v1/models calls

Full Changelog: https://github.com/Alph4d0g/opencode-omniroute-auth/blob/main/CHANGELOG.md

v1.1.2

[1.1.2] - 2026-05-13

Fixed

• Fixed model picker only showing fallback models on OpenCode >=1.14.47 by eagerly fetching live models in the config hook before OpenCode reads provider.models. (@jms830)
• Refactored createRuntimeConfig to accept options directly for reuse across both config and loader hooks.

Added

• Added readAuthFromStore() helper to read the stored OmniRoute API key from ~/.local/share/opencode/auth.json during the config hook.
• Added regression test for eager model fetching in the config hook.

v1.1.0 - Model Capability Enrichment & Combo Model Support

🚀 What's New

Model Capability Enrichment from models.dev

This release introduces automatic model metadata enrichment by integrating with models.dev API. Your OmniRoute models now automatically receive accurate context windows, token limits, and capability flags without manual configuration.

Key Features:

• Automatic metadata lookup: Fetches model specs from models.dev's comprehensive database (102+ providers, ~2000 models)
• Provider alias mapping: Seamlessly maps OmniRoute provider keys (, , ) to models.dev providers (, )
• Smart caching: 24-hour TTL cache for models.dev data minimizes API calls
• Graceful degradation: Works even when models.dev is unavailable or models aren't found

Combo Model Support

OmniRoute's combo models (virtual models that route to multiple underlying models) now automatically calculate their capabilities using a lowest common denominator approach:

• Context Window: Minimum of all underlying models (prevents token overflow)
• Max Tokens: Minimum of all underlying models (ensures safe output limits)
• Vision Support: Only enabled if ALL underlying models support vision
• Tool Support: Only enabled if ALL underlying models support tools

Example calculated capabilities:

Combo Model	Context	Max Tokens	Vision	Tools
Designer	204,800	32,768	❌	✅
Explorer	204,800	65,536	❌	✅
Oracle	128,000	32,000	❌	❌
Orchestrator	262,144	64,000	✅	✅

New Configuration Options

Enable/disable models.dev enrichment:

{
  provider: {
    omniroute: {
      options: {
        modelsDev: {
          enabled: true,  // default
          url: 'https://models.dev/api.json',
          timeoutMs: 1000,
          cacheTtl: 86400000,  // 24 hours
          providerAliases: {
            cx: 'openai',
            mycustom: 'anthropic'
          }
        }
      }
    }
  }
}

Custom model metadata overrides:

{
  provider: {
    omniroute: {
      options: {
        modelMetadata: [
          { match: /gpt-5\.3-codex$/i, contextWindow: 200000, maxTokens: 8192 },
          { match: 'virtual/my-custom-model', addIfMissing: true, contextWindow: 50000 }
        ]
      }
    }
  }
}

🐛 Bug Fixes

• Fixed: modelsDev.enabled: false option now properly disables enrichment
• Fixed: Optional chaining bug in `isComboModel()\ that threw TypeError when cache was null

📦 New API Exports

import {
  // Existing
  fetchModels,
  clearModelCache,
  refreshModels,
  // NEW: Combo model utilities
  clearComboCache,
  fetchComboData,
  resolveUnderlyingModels,
  calculateModelCapabilities
} from 'opencode-omniroute-auth/runtime';

📚 Documentation

• Comprehensive README updates with combo model explanation
• Configuration examples for JavaScript and JSON configs
• New API documentation for runtime exports

🔧 Technical Details

• New files: src/models-dev.ts (375 lines), src/omniroute-combos.ts (363 lines)
• Modified: src/models.ts, src/plugin.ts, src/types.ts, src/constants.ts
• Total changes: +1,210 lines across 9 files
• Tested: End-to-end against local OmniRoute instance (all tests passing)

🔄 Migration Guide

No breaking changes - this release is fully backward compatible:

• Existing configurations continue to work unchanged
• models.dev enrichment is enabled by default but can be disabled
• All new features are opt-in via configuration

📥 Installation

npm install opencode-omniroute-auth@1.1.0

🙏 Credits

Thanks to kilo-code-bot for the thorough code review that caught critical bugs before release!

v1.0.3

Release v1.0.3

Highlights

• Fixes npm plugin loading in OpenCode by limiting root runtime exports to plugin functions only.
• Adds optional API mode selection (chat and responses) with safe normalization and compatibility defaults.
• Introduces opencode-omniroute-auth/runtime for programmatic helper and constant imports.

What Changed

Plugin Compatibility

• Root package export now exposes plugin functions only:
  • default
  • OmniRouteAuthPlugin
• Added prepublish guard to fail builds if non-function runtime exports are added to package root.

API Mode Support

• Added provider.omniroute.options.apiMode with supported values:
  • chat (default)
  • responses
• Invalid values are normalized to chat with warning output.

Runtime Subpath

• Added opencode-omniroute-auth/runtime export for:
  • model helpers (fetchModels, refreshModels, clearModelCache, getCachedModels, isCacheValid)
  • constants (OMNIROUTE_DEFAULT_MODELS, MODEL_CACHE_TTL, OMNIROUTE_ENDPOINTS, etc.)

Documentation

• Updated README examples for apiMode and runtime helper imports.
• Added troubleshooting guidance for npm plugin loading.
• Added CHANGELOG.md with full history for 1.0.0 through 1.0.3.

Verification

• npm run prepublishOnly passes (clean, build, check:exports).
• Local packed tarball installs with expected export shape.
• Runtime helper API remains available through opencode-omniroute-auth/runtime.

Upgrade Notes

• If importing helper APIs from package root, update imports to opencode-omniroute-auth/runtime.
• Existing plugin configuration remains backward compatible; apiMode defaults to chat.