mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
b729a8f273
* chore(release): open v3.8.43 development cycle * docs(relay): clarify backend routing contract (#5621) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * fix(security): avoid rendering error stacks (#5624) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * fix(chatgpt-web): restore dot-form Pro model ids (#5549) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * feat(commandCode): add multimodal image support for CC vision models (#5557) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * fix(providers): validate M365 Copilot web credentials (#5432) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * fix(sse): bound chat hot-path heap — pressure-aware admission + response cap + clone reductions (#5152) (#5425) Integrated into release/v3.8.43 (drift-shed: cherry-picked the real change onto the release tip; stale-base drift dropped). * fix: model lockout not recording for 429 rate_limit_exceeded from Antigravity ## Problem When Antigravity returns HTTP 429 with `rate_limit_exceeded` error code, the model lockout system never records the failure, so the model is not cooled down despite being rate-limited. ### Root Cause Antigravity's 429 error text is: `"Resource has been exhausted (e.g. check quota)."` The QUOTA_PATTERNS in `classify429.ts` contained overly broad regexes: - `/resource.*exhaust/i` — matches "Resource has been exhausted" - `/check.*quota/i` — matches "check quota" This caused `classifyErrorText()` to return `QUOTA_EXHAUSTED` (wrong), which set `providerExhausted = true` in the combo target exhaustion logic. With `providerExhausted`, the retry path was skipped entirely, and while the "done retrying" path should still record lockout, the misclassification cascaded into incorrect provider-level exhaustion state. Additionally, `targetExhaustion.ts` used the raw error text string instead of the structured error code (`rate_limit_exceeded`) that was already parsed from the response body. ## Fix 1. **classify429.ts** — Removed overly broad `/resource.*exhaust/i` and `/check.*quota/i` from QUOTA_PATTERNS. Antigravity's rate-limit wording is not a true quota exhaustion signal. 2. **targetExhaustion.ts** — Added optional `structuredError` to `ApplyComboTargetExhaustionOptions`. When available, the structured error code (e.g. `rate_limit_exceeded`) takes precedence over raw error text for exhaustion classification. 3. **combo.ts** — Passes `structuredError` to both `applyComboTargetExhaustion` call sites (dispatch path + retry-or-rotate path). ## Effect `structuredError.code = "rate_limit_exceeded"` → classified as rate-limit (not quota) → `providerExhausted = false` → retry proceeds → `recordModelLockoutFailure` called → model enters lockout with proper cooldown (120s base, exponential backoff). ## Tests Added 2 new tests for `structuredError.code` precedence in exhaustion classification. All 28 related tests pass. * fix(checks): normalize route paths on windows (#5613) Integrated into release/v3.8.43. Windows path-normalization fix for the route-guard membership gate + regression test (Rule #18). Co-authored test added by maintainer. * fix: truncate tool list when provider limit exceeds MAX_TOOLS_LIMIT (grok-cli 200) - Add proactive PROVIDER_TOOL_LIMITS map with grok-cli: 200 - Fix regex to capture 'maximum is 200' (not '427 tools provided') - Remove broken truncation gate that skipped limits >= MAX_TOOLS_LIMIT (128) - Add tests for Grok regex, proactive limits, and limits above threshold Refs #5563 * test(chatcore): cover grok-cli tool-list truncation via prepareUpstreamBody (#5563) Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(security): v3.8.15 hardening follow-ups (Seg2/Seg3/Seg4/Bug3) (#5512) Security v3.8.15 hardening follow-ups: Seg2 (CHANGEME boot warn), Seg3 (auth_token cookie maxAge 30d), Seg4 (VS Code path-token once-per-process warning), Bug3 (real global install path resolution), Bug1 (segment-match node_modules in auto-update detection). All 5 carry TDD regression guards. * Fix HuggingChat web session routing (#5592) (#5592) Integrated into release/v3.8.43. HuggingChat web session-routing fix (root parent-message fetch + cookie propagation + encrypted-credential guard) + 24-model catalog refresh. Maintainer adjustments (co-authored): reverted the freeModelCatalog.data.ts whole-file reformat down to the surgical 24-record huggingchat change (preserving the auto-generated compact format), and added a 502 regression test for the null parent-message-id path (Rule #18). * fix: preserve system role for GLM 5.1/5.2 (#5610) (#5663) * fix: restore Codex Responses WS TLS profile + apply proxy (#5591, #5611) (#5668) * fix: allow saving providers without a live validator (#5565, #5567) (#5669) * fix: static model catalog for jules/linkup/ollama/searchapi search providers (#5569, #5571, #5573, #5575) (#5672) * fix: live AI/ML API catalog + deprecate dead CablyAI (#5570, #5568) (#5673) * fix: correct 404 provider setup links for ollama/searchapi/you.com (#5572, #5574, #5576) (#5674) * fix: page call_logs cleanup queries to avoid startup OOM on large DBs (#5618) (#5675) * fix: use PowerShell Expand-Archive on Windows for embedded-service install (#5590) (#5678) * fix: treat array content blocks as valid output in detectMalformedNonStream (#5559) (#5680) * fix: render memory engine status detail strings in English (#5596) (#5685) * fix: free proxy pool silent sync failure — iplocate txt + per-source isolation + surface errors (#5595) (#5686) * chore(quality): close QG v2 tail — drop orphan semcheck.yaml + Fase 9 maturity re-eval (#5681) - Remove semcheck.yaml: orphan config (zero workflow/script wiring) with stale rule counts; deterministic doc-accuracy coverage already exists (check:fabricated-docs --strict + docs-counts-sync + docs-symbols). Drop the REPOSITORY_MAP row referencing it. - Add docs/ops/MATURITY_REEVAL.md (Fase 9): re-measures maturity post-Ondas 0-3. The two biggest structural weaknesses from QUALITY_GATE_PLAYBOOK (2026-06-16) are now closed: fast-gates hole (quality.yml runs typecheck:core + impacted TIA unit tests + vitest + shards) and mutation-score-as-ratchet (check-mutation-ratchet.mjs + seeded baseline + nightly blocking job). Residual gap is owner/infra-gated (branch-protection main, SLSA L3, CodeQL advanced). - Record agent-lsp as deferred/opt-in (doc-only scaffold, no wiring). * fix(ci): stabilize nightly-mutation — guard tap.testFiles drift + anti-flake eps (#5682) Root cause (NOT a timeout): the nightly-mutation run fails on cold-cache nights because the blocking mutation-ratchet job measures modules below baseline, while warm-cache nights pass — the verdict tracked GitHub Actions cache state, not code quality. Proven via a local Stryker probe on headers.ts: covering unit tests (no-memory-header, strip-reasoning) had drifted OUT of stryker.conf.json tap.testFiles, so their mutants went covered-but-unkilled = Survived on a cold full run (COVERED score 61.73 vs 94.29 baseline); adding them restores the kills. - Add scripts/check/check-mutation-test-coverage.mjs: guards that every UNIT test importing a Stryker-mutated module is listed in tap.testFiles. Advisory by default, --strict in CI (wired in quality.yml fast-gates). Prevents recurrence. - Add the 38 drifted covering unit tests to stryker.conf.json tap.testFiles (138 -> 176). Monotonically safe: more covering tests only raise/hold the score. - Add MUTATION_RATCHET_EPS (1.0pt) anti-flake tolerance to check-mutation-ratchet so sub-point tap-runner jitter no longer false-fails the gate. Lowers no baseline. - Tests: check-mutation-test-coverage (3) + eps cases in check-mutation-ratchet. Residual: a clean post-merge nightly confirms scores return to/above baseline; any marginal residual gets a baseline re-seed (operator). * refactor(dashboard): split sidebarVisibility god-file into types + sections leaves (#5683) Behavior-preserving decomposition: src/shared/constants/sidebarVisibility.ts 1197 -> 291 LOC by extracting two leaves under sidebarVisibility/: - types.ts (160): HIDEABLE_SIDEBAR_ITEM_IDS + all sidebar types (self-contained). - sections.ts (762): section building-block consts + SIDEBAR_SECTIONS (imports types only — cycle-safe). COMPRESSION_CONTEXT_GROUP + SIDEBAR_SECTIONS stay exported; host re-exports both + 'export *' of types, so every consumer import path is unchanged. Byte-identical data verified via JSON.stringify of HIDEABLE_SIDEBAR_ITEM_IDS / SIDEBAR_ICON_ACCENTS / COMPRESSION_CONTEXT_GROUP / SIDEBAR_SECTIONS / SIDEBAR_PRESETS + getSectionItems output (identical before/after). typecheck:core, check:cycles (no cycles), check:file-size (3 files <800), and the 3 sidebar suites (20/20) pass. No logic changed. Note: file-size frozen baseline for sidebarVisibility.ts (1198) can ratchet to 291 to lock the shrink (left for the release ratchet / operator). * fix: surface fusion-specific config on the Global Routing tab (#5598) (#5688) * fix(executor): route OpenAI-compatible MCP Responses requests to /responses (#5483) Closes #5483. OpenAI-compatible providers receiving a Responses-shaped request carrying MCP / tool_search tools now route to the upstream /responses endpoint instead of downgrading to /chat/completions, preserving Codex deferred tool discovery. Detection helpers extracted to open-sse/executors/forceResponsesUpstream.ts. Thanks to @KooshaPari. * fix(ci): make release-green pre-flight gates visible + bounded so unit reds are not missed (#5644) Integrated into release/v3.8.43. * fix(body-size): raise LLM API payload limit for responses routes (#5652) Integrated into release/v3.8.43. Thanks @JxnLexn! * fix(test): use lightweight health probe for batch e2e (#5651) Integrated into release/v3.8.43. Thanks @KooshaPari! * feat(compression): T05/C5 — preserveSystemPrompt mode enum + legacy back-compat (#5653) Integrated into release/v3.8.43. Includes the legacy-boolean back-compat derivation so existing preserveSystemPrompt=false installs keep whenNoCache behavior. * routing: optimize latency strategy with perf metrics (#5629) Integrated into release/v3.8.43. Thanks @KooshaPari! * feat(db): models/5004 — self-correcting model context-window overrides (#5667) Integrated into release/v3.8.43. * feat(providers): complete SenseNova free Token Plan — chat + Text-to-Image (port from 9router#2233) (#5679) Integrated into release/v3.8.43. * feat(api): routing/4985 — configurable response-body validation + failover (#5684) Integrated into release/v3.8.43. * fix(chatcore): default Claude tool type to "custom" when missing (#5662) Integrated into release/v3.8.43. Port from 9router#2196. Co-authored-by: warelik <warelik@users.noreply.github.com> * fix(translator): merge consecutive same-role contents for Gemini (port from 9router#2191) (#5661) Integrated into release/v3.8.43. Port from 9router#2191. * chore(bun): add locked bun runtime dependency (#5615) Integrated into release/v3.8.43. Bun 1.3.10 pinned via npm lockfile (adopt-partial decision). Thanks @KooshaPari! * chore(bun): run validated ts scripts with bun (#5612) Integrated into release/v3.8.43. Thanks @KooshaPari! * chore(bun): run CI script checks with bun (#5617) Integrated into release/v3.8.43. Validated bun==node output for all 3 gates (provider-consistency, compression-budget, known-symbols). Thanks @KooshaPari! * fix(build): make pack validator bun safe (#5643) Integrated into release/v3.8.43. Forward-compat guard; node/npm path unchanged. Thanks @KooshaPari! * docs: document Bun as the allow-listed build/dev script runner (Node stays the published runtime) (#5703) Integrated into release/v3.8.43. * feat(analytics): show $0 cost for flat-rate subscription/cookie providers (#5552) (#5704) * refactor(api): extract unified-catalog helpers into cohesive leaf modules (#5699) BLOCO E2 of the god-files campaign. The module-level pure/standalone helpers in src/app/api/v1/models/catalog.ts (1611 LOC) were lifted out verbatim into five cohesive leaf modules so the catalog host shrinks toward the 800-LOC file-size cap without any behavior change (host now 1345 LOC; the heavy getUnifiedModelsResponse orchestrator is untouched — its in-function closures stay put): - catalogHelpers.ts — pure numeric/array/shape helpers + shared catalog types - catalogOpenrouter.ts — OpenRouter id/modality/free-model/display-name helpers - catalogVision.ts — vision-capability field derivation (+ isVisionModelId re-export) - catalogProviderMaps.ts — alias<->providerId resolution maps (buildAliasMaps) - catalogRequest.ts — /v1/models API-key auth gating + Codex CLI client detection The host re-exports getCustomVisionCapabilityFields and isVisionModelId so the public API consumed by other tests (llm-selector-custom-vision-models, vision-detection- consistency) is unchanged; all 9 catalog/vision suites stay green. Adds tests/unit/catalog-helpers-extraction.test.ts: characterization tests for every extracted helper + a guard asserting the host preserves its public exports. Validated: typecheck:core, 50 catalog characterization tests, 12 new leaf tests, integration-wiring, check:cycles, check:file-size (no new violations), ESLint, Prettier. * feat(mcp): T07 — expose RTK learn/discover as MCP tools (#5691) Adds two read-only MCP tools wrapping the existing RTK discovery primitives: omniroute_rtk_discover (discoverRepeatedNoise/suggestFilter over recently captured raw tool output → candidate noise patterns + suggested filter) and omniroute_rtk_learn (listRtkCommandSamples + commandToId). Scope read:compression, MCP audit-logged, no new engine logic. Regression guard: tests/unit/compression/rtk-mcp-tools.test.ts. gaps v3.8.42 — T07. * feat(compression): T05/C3 — opt-in LLM-tier compression engine (#5702) Adds an opt-in, default-off LLM-tier compression engine ('llm') that condenses non-system message prose via a pluggable chat-completion backend, mirroring the llmlingua contract. Safe by construction: no-op default backend (pass-through out of the box), not in the default stacked pipeline, enabled defaults false, fenced code blocks + system messages never sent to the model, fail-open everywhere, minTokens floor. Real production backend is a VPS-validated follow-up (Hard Rule #18). Regression guard: tests/unit/compression/llm-compressor-engine.test.ts (8). gaps v3.8.42 — T05/C3. * refactor(db): extract compat/aliases/mitm helpers from db/models.ts into leaf modules (#5705) BLOCO E3 of the god-files campaign. db/models.ts (1250 LOC) mixed six concerns; the three cleanly-separable ones plus the shared key_value helpers were lifted out verbatim into a new src/lib/db/models/ subdirectory, leaving the tightly-coupled custom/synced/ flags trio in the host (host now 936 LOC). The host re-exports every moved public symbol so the module's public API (consumed by ~29 test files + localDb) is unchanged. - models/shared.ts — asRecord / toNonEmptyString / getKeyValue + JsonRecord (19 LOC) - models/compat.ts — model-compat overrides + sanitizeUpstreamHeadersMap (249 LOC) - models/aliases.ts — model-alias CRUD + cascade delete (61 LOC) - models/mitmAlias.ts — MITM alias get/set (32 LOC) The custom/synced/flags trio stays in the host because it is genuinely coupled (flags->getCustomModelRow, flags->readCompatList, custom->removeModelCompatOverride, synced->getModelIsDeleted, setModelIsHidden->updateCustomModel) — splitting it cleanly is a follow-up. Dependency DAG is acyclic (verified by check:cycles). Adds tests/unit/db-models-split.test.ts: characterization of the pure extracted helpers + a guard asserting the host preserves its full public export surface. Validated: typecheck:core, check:cycles (no cycles), 77 existing db/models consumer tests (db-models-crud/extended/aliases-cascade + 7 more) green, 7 new tests, ESLint, Prettier, check:file-size (host 936 < frozen 1259; no new violations). * refactor(db): extract pricing/lkgp/cache-metrics from db/settings.ts into leaf modules (#5709) BLOCO E3 of the god-files campaign. db/settings.ts (1154 LOC) mixed five concerns; the three cleanly-separable ones plus the shared toRecord/JsonRecord helper were lifted out verbatim into a new src/lib/db/settings/ subdirectory, leaving the Settings-core + Proxy config concerns in the host (host now 646 LOC). The host re-exports every moved public symbol so the module's public API (consumed by ~93 test files + localDb) is unchanged. - settings/shared.ts — toRecord + JsonRecord (9 LOC) - settings/pricing.ts — pricing layers/sources/per-model + update/reset (254 LOC) - settings/lkgp.ts — Last-Known-Good-Provider get/set/clear (49 LOC) - settings/cacheMetrics.ts — cache metrics + trend (235 LOC) Settings-core + the Proxy-config concern stay in the host: proxy is the most tangled (245-line resolveProxyForConnection, resolution cache, imports from ./proxies) and getSettings is the most central function — leaving them is the correct coupled-core stop. Pricing/LKGP/Cache have NO dependency on Settings/Proxy helpers (verified); the dependency DAG is acyclic (check:cycles). Adds tests/unit/db-settings-split.test.ts: characterization of the shared toRecord helper + a guard asserting the host preserves its full public export surface. Validated: typecheck:core, check:cycles (no cycles), 149 existing+new db/settings consumer tests green (db-settings-crud/extended, 8 pricing suites, cache-metrics, 2 proxy-resolution suites + 29 new), ESLint, Prettier, check:file-size (host 646 < frozen 1155). * fix(translator): re-apply lost defensive hardening for Gemini merge + Claude tool defaults (#5706) Re-applies two dropped gemini-code-assist hardening fixes (defaultClaudeToolType non-object passthrough; mergeConsecutiveSameRoleContents shallow-copy) with regression tests. Follow-up to #5661/#5662. Integrated into release/v3.8.43. * feat(codex): generate fallback profiles for compatible models (#5701) setup-codex now generates Codex profiles for compatible text models from the live /v1/models catalog when the model id doesn't match a hand-tuned pattern, skipping media/embedding models. Integrated into release/v3.8.43. * docs(changelog): credit @Chewji9875 for #5563 + #5579 Add CHANGELOG credit bullets for grok-cli tool-limit (#5563) and Antigravity 429 lockout (#5579). Documentation-only. * test(dashboard): repoint sidebar quota-share placement scan to sections.ts (#5711) The D1 god-file split (#5683) moved the nav-item id definitions out of src/shared/constants/sidebarVisibility.ts into the extracted leaf src/shared/constants/sidebarVisibility/sections.ts. This source-scan test still read the old monolith path, so it found 0 occurrences of id: "costs-quota-share" and failed (base-red on release/v3.8.43). Repoint SIDEBAR_PATH to sections.ts where the ids now live. All four placement assertions (quota-share after quota, same array, far from costs-budget, exactly one occurrence) hold against the new source. * refactor(db): extract columns/nodes/rate-limit leaves from db/providers.ts (#5714) db/providers.ts was a 1106-line god-file mixing four concerns. Extract the three acyclic, cohesive slices into sibling leaf modules under src/lib/db/providers/, leaving the tightly-coupled connection-CRUD core in the host: - providers/columns.ts (116) 10 pure column-normalizer helpers (DB-free) - providers/nodes.ts (163) 6 provider-node CRUD functions - providers/rateLimit.ts (177) 6 rate-limit/quota runtime helpers + formatResetCountdown Host providers.ts: 1106 -> 719 lines. The connection-CRUD core does not call any node or rate-limit function (verified), so the host re-exports the 12 moved public symbols via `export { ... } from './providers/<leaf>'` — the module's public API stays IDENTICAL (23 symbols). Bodies moved verbatim (byte-identical); the only edit to a moved line is the added `export` on the 10 previously-private normalizers. Behavior-preserving: 122 existing provider/quota/rate-limit consumer tests stay green; new tests/unit/db-providers-split.test.ts guards the re-export barrel + characterizes the pure column helpers (38 assertions). Refs #3501 (god-file structural shrink). * refactor(db): extract types + pure mappers from db/proxies.ts (#5717) db/proxies.ts was a 1059-line god-file. Extract the two acyclic, DB-free slices into sibling leaf modules under src/lib/db/proxies/, leaving the tightly-coupled CRUD + assignment + resolution core in the host: - proxies/types.ts (65) 10 proxy type/interface declarations - proxies/mappers.ts (180) pure row mappers / scope normalizers / payload coercers (toRecord, mapProxyRow, mapAssignmentRow, isRelayProxyType, extractRelayAuth, toRegistryProxyResolution, normalizeScope, normalizeAssignmentScopeId, toLegacyProxyLevel, coerceProxyPayload, redactProxySecrets) Host proxies.ts: 1059 -> 847 lines. The resolution functions call createProxy/assignProxyToScope, so the CRUD+resolution core CANNOT be extracted without an import cycle and stays in the host. The host re-exports the 2 moved public functions (extractRelayAuth, redactProxySecrets) via `export { ... } from './proxies/mappers'` — the public API stays IDENTICAL (20 functions; no types were ever publicly exported). Bodies moved verbatim; the only host edits are the new leaf imports, the re-export, dropping the now unused `import { decrypt }`, and two prettier line-wrap reflows of retained ternary/union lines (token-identical). Behavior-preserving: 69 existing proxy/registry/relay/family consumer tests stay green; new tests/unit/db-proxies-split.test.ts guards the re-export barrel + characterizes the pure mappers (35 assertions). Refs #3501. * refactor(db): extract static migration data tables from migrationRunner.ts (#5721) migrationRunner.ts (1124 lines, frozen-baselined) is the startup migration orchestrator. As a conservative, zero-behaviour-risk first slice, extract the six static migration-compatibility DATA tables (verbatim) into a pure-data leaf, leaving the entire orchestrator + all SQL-running helpers in the host: - migrationRunner/constants.ts (118) RENAMED_MIGRATION_COMPATIBILITY, LEGACY_VERSION_SLOT_MIGRATIONS, SUPERSEDED_DUPLICATE_MIGRATIONS, PHYSICAL_SCHEMA_SENTINELS, INITIAL_SCHEMA_SENTINELS, OPTIONAL_FTS5_MIGRATION_VERSIONS Host migrationRunner.ts: 1124 -> 1023. The runtime fts5SupportCache (a WeakMap, mutable state) stays in the host. No public API change (these consts were module-internal). Data moved byte-identical (sed-extracted, verbatim verified); the only host edits are the leaf import + one prettier collapse of a pre-existing 2-line union type annotation to 1 line (token-identical, typecheck-confirmed). Characterize-first (operator-chosen): the existing db-migration-runner.test.ts (26 tests) + no-migration-collisions/weak-rng-fixes/check-db-rules (11) prove the reconciliation/dedup/already-applied BEHAVIOUR is unchanged; the new tests/unit/db-migrationrunner-constants-split.test.ts (7 tests) PINS THE DATA (counts + shape + spot-checks of every table) so a dropped/transposed row is caught immediately. Refs #3501. * refactor(db): extract pure SQL-source builders from usageAnalytics.ts (#5722) usageAnalytics.ts (924 lines, frozen-baselined) mixes two pure SQL-source builders with ~20 getXxxRows() query functions. Extract the contiguous, DB-free builder block verbatim into a leaf, leaving every query function in the host: - usageAnalytics/sources.ts (208) AnalyticsParams, BuildUnifiedSourceOptions, UnifiedSourceResult + buildUnifiedSource + buildPresetUnifiedSource (pure string builders; no DB, no imports) Host usageAnalytics.ts: 924 -> 723. The query functions do not call the builders (callers build the unified source then pass the string in), so the host re-exports the 5 moved public symbols (2 fns + 3 types) and imports AnalyticsParams as a type for its query signatures — the public API stays IDENTICAL (39 symbols). Builder bodies moved byte-identical; the two orphaned section-header banners that described the moved block were removed with it; the retained query-function suffix is byte-identical to the original. Behavior-preserving: 37 existing analytics consumer tests stay green (usage-analytics 12, usage-endpoint-dimension 3, db-usage-analytics-3500 22); new tests/unit/db-usageanalytics-split.test.ts (25 assertions) characterizes buildUnifiedSource's needsAggregated branching (raw-only vs raw+daily_usage_summary) + guards the 39-symbol re-export barrel. Refs #3501. * docs(readme): refresh metrics, list 17 strategies, add Quota-Share + real provider logos - Unify provider count to 236; MCP tools 87->94; cloud agents 3->4 (+Cursor); compression 9->10 engines (+relevance) - Tests -> 21,000+ across 2,586 files; footer -> v3.8.43 - Raise lower bounds to real values: 90+ free, 80+ commands, 24+ CLIs - Language flag grid 33->43 (15/14/14, all locales) - List all 17 routing strategies; new Quota-Share section before Resilience - Real provider logos (lobe-icons + local agentrouter) in providers grid and Free Forever - Top Contributors: refreshed stats + add herjarsa; 280+ title; half-size avatars; contrib.rocks 100->200 - Acknowledgments: refreshed star counts; fix headroom repo rename * docs(readme): update provider counts and add new badges * feat(memory): T10/TV6 — opt-in typed memory decay (#5723) Opt-in typed memory decay so the conversational memory store self-prunes stale episodic noise. access_count + last_accessed_at telemetry (migration 111) is always-on/non-destructive; the sweep is opt-in (MEMORY_TYPED_DECAY_ENABLED, default false). Only episodic decays by default (30d); factual/procedural/semantic immune; access_count>=3 earns immunity; deletions reuse deleteMemory (SQLite+vec+Qdrant in sync), fail-open. Regression guard: tests/unit/memory/typed-decay.test.ts (15). gaps v3.8.42 — T10/TV6. * feat(dashboard): T06/T03 — drag-reorder compression pipeline editor + studio e2e (#5727) T06: named-combos editor gains a @dnd-kit/sortable drag-to-reorder stacked pipeline backed by a pure model (compressionPipelineModel.ts: add/remove/move/update, engine->intensity invariant, never-empty). CompressionPipelineEditor.tsx replaces the inline fixed list in CompressionCombosPageClient; order persists via the existing combos endpoint (no API change). T03: adds tests/e2e/compression-studio.spec.ts (Tela A render + Play/Compare tab switch), the dedicated compression-studio e2e combo-live-studio.spec.ts did not cover. TDD: compression-pipeline-model.test.ts (11) + compression-pipeline-editor.test.tsx (4). gaps v3.8.42 — T06 + T03. * fix(thinking): wire Thinking-Budget boot hydration into live instrumentation path (#5312) (#5729) hydrateThinkingBudgetConfig was only called from the unused src/server-init.ts, which never runs in production, so the dashboard Thinking-Budget mode silently reverted to passthrough on every restart. Wire it into the real boot path (src/instrumentation-node.ts), next to the Global System Prompt restore. Surfaced by live Anthropic-OAuth validation on the VPS (fix A of #5312 was non-functional even though its direct unit test passed). New guard tests/unit/thinking-budget-boot-wiring-5312.test.ts asserts the production boot module calls the hydration, closing the test gap that let this ship. * refactor(usage): extract pure formatting helpers from callLogs.ts (#5725) callLogs.ts (996 lines, frozen-baselined) mixes pure log-formatting / sanitization helpers with DB CRUD, disk-artifact, and rotation logic. Extract the ten pure, DB-free helpers verbatim into a leaf, leaving all stateful code in the host: - callLogs/format.ts (129) asRecord, toNumber, toStringOrNull, truncateText, parseInlineError, normalizeDetailState, sanitizeErrorForLog, toStoredErrorSummary, protectPipelinePayloads, buildRequestSummary Host callLogs.ts: 996 -> 885. The stateful generateLogId (mutates logIdCounter) stays in the host. These helpers were all module-internal, so the public API is unchanged (10 exported functions). Bodies moved byte-identical; the host's now unused 'sanitizePII' import (only referenced inside the moved bodies) moved to the leaf; prettier wrapped buildRequestSummary's signature across lines once the 'export' prefix pushed it past 100 cols (token-identical). Behavior-preserving: 46 existing call-log consumer tests stay green (call-log-cap 14, pagination 4, file-rotation 5, log-retention 5, startup 1, oom 2, trim-sql 2, db-settings-maintenance 13); new tests/unit/calllogs-format-split.test.ts (26 assertions) characterizes the pure helpers + guards the 10-function public API. Refs #3501. * refactor(usage): extract pure stat/coercer helpers from usageHistory.ts (#5728) usageHistory.ts (987 lines, frozen-baselined) mixes pure DB-free helpers with an in-memory pending-request state machine and DB CRUD. Extract the contiguous pure block verbatim into a leaf, leaving all stateful code in the host: - usageHistory/helpers.ts (85) asRecord, toStringOrNull, normalizeServiceTier, toNumber, percentile, stdDev, truncatePendingPreview (+ its MAX_PREVIEW_* bounds, co-located) Host usageHistory.ts: 987 -> 916. The pending-request state machine (module Maps + track/update/finalize/sweep) and DB CRUD stay in the host. These helpers were all module-internal, so the public API is unchanged (21 direct exports + the pre-existing getCompletedDetails re-export = 22). Bodies moved byte-identical (leaf 0 non-verbatim lines); the host's local 'type JsonRecord' moved with the bodies that used it (host no longer references it — typecheck-confirmed). Behavior-preserving: 38 existing usage-history consumer tests stay green (usage-history-db 5, api-key-usage-limits 6, log-retention 5, usage-endpoint-dimension 3, provider-request-failure-pipeline 6, database-settings-maintenance 13); new tests/unit/usagehistory-helpers-split.test.ts (30 assertions) pins the percentile/stdDev formulas + normalizeServiceTier + guards the public API. Refs #3501. * refactor(usage): extract pure quota-normalize helpers from providerLimits.ts (#5730) providerLimits.ts (954 lines, frozen-baselined) is the heavily DB/network-coupled provider quota sync module. Extract a small, fully SELF-CONTAINED leaf of pure quota-key/quota-value normalization helpers (+ the isRecord type guard they share), leaving all sync/DB/network code in the host: - providerLimits/quotaNormalize.ts (72) isRecord, isUsageQuotaKeyAllowed, normalizeUsageQuotaKey, normalizeUsageQuotasForProvider, sanitizeUsageQuotasForProvider Host providerLimits.ts: 954 -> 890. The leaf imports only the external antigravity/agy model-alias helpers the moved bodies reference (moved from the host's import block) — it does NOT import the host, so check:cycles stays clean (no cycle). isRecord (used ~9x in the host) is co-extracted and imported back. These five were all module-internal, so the public API is unchanged (13 exported functions). Bodies moved byte-identical. Behavior-preserving: 18 existing provider-limits consumer tests stay green (sanitize-scope 3, db-provider-limits 3, proxy-fail-closed 3, rotating-expired-guard 7, codex-quota-sync 2); new tests/unit/providerlimits-quotanormalize-split.test.ts (19 assertions) pins isRecord + isUsageQuotaKeyAllowed + guards the 13-function public API. Refs #3501. * refactor(memory): extract pure scoring/conversion helpers from retrieval.ts (#5733) retrieval.ts (1192 lines — ABOVE its 1171 frozen baseline) is the memory retrieval engine (DB + vector + rerank network). Extract the pure, DB-free scoring/conversion helpers (+ the MemoryRow row shape they share) verbatim into a self-contained leaf, leaving all DB/vector/network code in the host: - retrieval/scoring.ts (104) interface MemoryRow + estimateTokens, parseMetadata, rowToMemory, getRelevanceScore Host retrieval.ts: 1192 -> 1072 — back UNDER the 1171 frozen baseline (the split also repairs the pre-existing file-size drift). The leaf imports only ../types, never the host, so check:cycles stays clean (no cycle). MemoryRow moved to the leaf and imported back as a type by the host's DB row functions. The public estimateTokens is re-exported from the leaf; the host also imports it for its internal token-budget loops. The other three helpers were module-internal, so the public API is unchanged (7 exports). Bodies moved byte-identical. Behavior-preserving: 38 existing memory-retrieval consumer tests stay green (rerank 5, hybrid 6, semantic 6, engine-status 9, stats-api 12); new tests/unit/retrieval-scoring-split.test.ts (11 assertions) pins estimateTokens (ceil(len/4)) + parseMetadata + rowToMemory mapping + getRelevanceScore (+20 phrase / +3 token) and guards the public API. Refs #3501. * refactor(sse): extract reasoning-tag detection/extraction from responseSanitizer.ts (#5734) responseSanitizer.ts (1133 lines, frozen-baselined) mixes reasoning-tag detection/extraction with response/usage/streaming sanitization. Extract the cohesive, ZERO-IMPORT reasoning block verbatim into a self-contained leaf: - responseSanitizer/reasoning.ts (143) the reasoning regex consts + collapseExcessiveNewlines, cleanReasoningFragment, splitClosingOnlyReasoningPrefix, movePrefixBeforeContentTagToThinking, extractThinkingFromContent, normalizeReasoningRouteId, isAntigravityReasoningRoute, isTextualReasoningTagNativeRoute, shouldParseTextualReasoningTags Host responseSanitizer.ts: 1133 -> 1003. The block's helpers only call each other, so the leaf has ZERO imports — it cannot import the host (check:cycles clean). The host imports back collapseExcessiveNewlines (6 call sites) + extractThinkingFromContent, and re-exports the two public symbols (extractThinkingFromContent, shouldParseTextualReasoningTags) — the public API stays IDENTICAL (7 exports). Bodies moved byte-identical; two long declarations (REASONING_TAG_FRAGMENT_REGEX, movePrefixBeforeContentTagToThinking signature) were line-wrapped by prettier once the 'export' prefix pushed them past 100 cols (token-identical). Behavior-preserving: 47 existing consumer tests stay green (response-sanitizer 36, strip-reasoning-header 8, textual-toolcall-false-positive 3); new tests/unit/responsesanitizer-reasoning-split.test.ts (11 assertions) characterizes extractThinkingFromContent + shouldParseTextualReasoningTags and guards the public API. Refs #3501. * refactor(sse): extract rate-limit header parsing from rateLimitManager.ts (#5736) rateLimitManager.ts (1034 lines, frozen-baselined) is the stateful rate-limiter (Bottleneck limiters, watchdog timers, learned-limits Map). Extract the pure, ZERO-IMPORT header-parsing block verbatim into a self-contained leaf, leaving all stateful machinery in the host: - rateLimitManager/headers.ts (94) STANDARD_HEADERS, ANTHROPIC_HEADERS, parseResetTime, toPlainHeaders Host rateLimitManager.ts: 1034 -> 945. The four items are pure (no limiter state, no external deps), so the leaf has ZERO imports — it cannot import the host (check:cycles clean). The host imports all four back (used by updateFromHeaders). They were module-internal, so the public API is unchanged (17 exports). Bodies moved byte-identical. Behavior-preserving: 21 existing rate-limit consumer tests stay green (rate-limit-manager 7, limiter-lifecycle 4, queue-timeout-msg 2, idle-eviction 6, body-lock 2); new tests/unit/ratelimitmanager-headers-split.test.ts (7 assertions) pins parseResetTime (durations / bare-number / nullish) + toPlainHeaders + guards the 17-function public API (with a watchdog-timer teardown hook so the runner exits cleanly). Refs #3501. * fix(config): back boot-hydrated proxy config singletons with globalThis (#5312) (#5742) Next.js compiles instrumentation.ts as a separate webpack module graph from the app-route/open-sse executors, so a module-local `let _config` is duplicated: the boot-time hydration (applyRuntimeSettings / restore hooks) lands on the instrumentation graph's copy, but the request path (base.ts) reads a different, un-hydrated copy. Live VPS validation proved the Thinking-Budget hydrate ran to completion at boot yet base.ts still read the passthrough default — why #5312 fix A stayed broken after the boot-wiring fix. Back the singletons with globalThis (the pattern systemPrompt.ts already uses for #2470) so all graph copies share one instance: - thinkingBudget.ts — dashboard Thinking-Budget mode reaches the executor - backgroundTaskDetector.ts — opt-in background degradation actually fires - systemTransforms.ts — operator pipeline overrides reach the request path payloadRules.ts was already safe (lazy per-request DB self-load, #2986). Guards: thinking-budget-globalthis-5312 + runtime-config-globalthis-5312 (assert globalThis sharing; a module-local let fails them, RED->GREEN). * refactor(evals): extract built-in golden-set suites from evalRunner.ts (#5740) Move the 7 static built-in eval suites (golden-set, coding-proficiency, reasoning-logic, multilingual, safety-guardrails, instruction-following, codex-comparison) plus the builtInSuites aggregate into the pure-data leaf src/lib/evals/evalRunner/builtinSuites.ts (zero imports, no side effects). evalRunner.ts keeps all logic (register/get/list/evaluate/run/scorecard/reset) and registers the leaf suites at module load, mirroring the original inline calls. Public API is unchanged (7 exported functions; the suite consts were already module-private). Host 960->301 LOC; leaf 676 LOC (< 800 cap); host was frozen-satisfied (961), so this is debt reduction. Suite data moved verbatim (652 data lines byte-identical). New split-guard test characterizes the suite ids/case counts/key cases and proves the host registers every leaf suite at load. * refactor(models): extract pure transform layer from modelsDevSync.ts (#5743) Move the models.dev data-model types, the provider-id mapping table (MODELS_DEV_PROVIDER_MAP + mapProviderId), and the raw->OmniRoute transforms (transformModelsDevToPricing, transformModelsDevToCapabilities) into the pure leaf src/lib/modelsDevSync/transform.ts (zero imports, no DB, no module state). modelsDevSync.ts keeps all sync orchestration, DB access, caches and the periodic-sync timer; it imports the transforms for internal use and re-exports mapProviderId/transformModelsDevToPricing/transformModelsDevToCapabilities plus the ModelCapabilityEntry/CapabilitiesByProvider types, so the public API is unchanged. Host 924->677 LOC; leaf 279 LOC (< 800 cap); host was frozen-satisfied (934), so this is debt reduction. 238 moved lines are byte-identical. New split-guard test characterizes the provider map + both transforms and proves the host re-exports them. * refactor(resilience): split settings.ts into types + normalize leaves (#5745) Decompose the (fully pure) resilience settings module into two sibling leaves: - src/lib/resilience/settings/types.ts: the settings shape (11 public interfaces + JsonRecord/AuthCategory), zero imports. - src/lib/resilience/settings/normalize.ts: the coercers (asRecord/toInteger/ toBoolean/feature-flag resolvers) + the 11 per-section normalize* functions. settings.ts keeps DEFAULT_RESILIENCE_SETTINGS, DEFAULT_REQUEST_QUEUE_MAX_WAIT_MS, buildLegacyFallback, and the public orchestrators (resolveResilienceSettings, mergeResilienceSettings, buildLegacyResilienceCompat); it imports the coercers/normalizers for internal use and re-exports the 11 settings interfaces, so the public API is unchanged. Host 840->363 LOC; leaves 182 + 359 LOC (< 800 cap); host was frozen-satisfied (841), so this is debt reduction. 472 moved lines are byte-identical; no cycles (leaves never import the host). New split-guard test characterizes the coercers/normalizers and the host resolve/merge/compat orchestration. * docs(readme): document faster/leaner install — skip native build, sql.js fallback (#5713) Documents the optional better-sqlite3 + pure-JS fallback chain and OMNIROUTE_SKIP_POSTINSTALL/CI skip flags. Docs-only, claims verified. (#5550) * feat(compression): T02 opt-in per-engine pipeline circuit-breaker (#5735) Opt-in, default-off per-engine circuit-breaker for the stacked compression pipeline. Byte-identical to legacy when off. 9 regression tests. * docs: sync MCP tool count to 95 + routing-strategy count (#5732) Sync CLAUDE.md/README.md to canonical MCP tool count (95, 35 base) and routing strategies (17). Numbers fact-checked against getAllToolDefinitions()/ROUTING_STRATEGY_VALUES. * feat(api): add first-class Ollama local provider card (#5712) First-class ollama-local provider card (localhost:11434/v1, keyless, passthrough models) in LOCAL_PROVIDERS + SELF_HOSTED + default.ts executor case. Docs count 236→237, Local 11→12 (full README sweep). 4 tests. (#5578) * feat(api): add opt-in API-key provider quota-policy bypass scope (#5731) Adds an opt-in per-API-key scope (policy:bypass-provider-quota) that lets a key skip provider/account-side quota cutoffs during routing. Operator USD budgets/usage limits still enforced unconditionally (fail-closed, before the bypass). Default-off; UI toggle + badge in API Manager. Integrated into release/v3.8.43. * feat(codex): opt-in auto-sync of Codex profiles after model discovery (#5737) Auto-sync ~/.codex/*.config.toml profiles after a provider model sync, reusing the setup-codex generator. Opt-in, default OFF (OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true; also honors CLI_ALLOW_CONFIG_WRITES). Never touches the active Codex config. Gating test added. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(providers): opt-in CLI profile auto-sync toggles + Claude Code auto-sync (#5755) Providers-dashboard 'CLI profile auto-sync' card (Codex + Claude Code toggles), feature-flag backed (default off), + Claude Code auto-sync mirroring the Codex path. Follow-up to #5737. * feat(compression): T08/H8 (2.3) — graduated CCR retrieval-feedback ramp (#5739) Turns CCR retrieval feedback from a binary cliff into a graduated ramp: each prior retrieval raises a block's effective minChars linearly (effectiveMinChars); >= 3 retrievals still excluded (Infinity). retrievalRampFactor default 2 (config/env COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR); 1 = legacy binary. Regression guard: tests/unit/compression/ccr-retrieval-ramp.test.ts (12); 51 existing CCR tests green. gaps v3.8.42 — T08/H8 (2.3). * feat(compression): T08/H5 (2.4) — usage-observed prefix freeze (opt-in) (#5744) Evolves the cache-aware guard to also learn which system prompts recur: observed >= threshold → treated as a stable cacheable prefix and preserved even for providers the static check misses. Content-addressed by a hash of the system prompt (OpenAI/Claude/Gemini), in-memory, freeze=preserve (never mutates). Opt-in/default-off (COMPRESSION_PREFIX_FREEZE_ENABLED); respects the never preserve-mode. New prefixFreeze.ts wired into resolveCacheAwareConfig. Regression guard: prefix-freeze.test.ts (10); 44 cache-aware tests green. gaps v3.8.42 — T08/H5 (2.4). * feat(compression): T08/H7 (2.5) — read-lifecycle engine (collapse superseded reads) (#5754) New opt-in, default-off read-lifecycle engine: collapses stale/superseded file-Read tool results (same path re-read OR modified later) to a stub, keeping the current Read intact. Anthropic + OpenAI tool shapes; conservative (known tool names, exact path, strictly-later); fail-open. Lossy → opt-in. Regression guard: read-lifecycle.test.ts (10); 41 registry/pipeline suites green. gaps v3.8.42 — T08/H7 (2.5). Completes Onda 2. * fix(sse): anti-thundering-herd guard tolerates numeric-epoch cooldowns (#5747) markAccountUnavailable's dedupe guard used a raw `new Date()` on rateLimitedUntil, which can hold a numeric-epoch string (e.g. the Antigravity full-quota path via setConnectionRateLimitUntil). That produced Invalid Date/NaN, so the guard never detected an already cooling connection — a second concurrent failure on the same connection overwrote a long quota-exhaustion cooldown with a much shorter fresh backoff cooldown, making the account selectable again far sooner than intended. Reuses the existing cooldownUntilMs normalizer (#3954) instead of a raw Date parse. * fix(chat): harden non-streaming SSE aggregation (#5746) * fix: repoint DashScope/Alibaba setup links to consoles (#5665) (#5762) * fix: point Quick Start step 1 to API Keys page, not Endpoint (#5695) (#5763) * fix: onboarding wizard saves providers with unsupported validation (#5692) (#5764) * docs(security): document full LOCAL_ONLY route set + GHSA-fhh6-4qxv-rpqj + audit path (#5599) (#5748) Expand ROUTE_GUARD_TIERS.md Tier 1 (LOCAL_ONLY): - link the GHSA advisory and explain the attack class (RCE via a subprocess spawn reachable from non-loopback traffic) - replace the 3-example prefix table with the full LOCAL_ONLY set, mirroring LOCAL_ONLY_API_PREFIXES / LOCAL_ONLY_API_PATTERNS in routeGuard.ts (the authoritative source; check-route-guard-membership enforces the code side) - add an "Operator guidance & auditing" section for users behind nginx/Cloudflare/Tailscale: don't forge X-Forwarded-For loopback, keep the manage-scope bypass minimal, and how to audit non-loopback access Docs-only; SECURITY.md already links here. Closes #5599 * docs(security): document banned-keyword / account-ban detection (#5600) (#5756) * docs(security): add BAN_DETECTION.md — banned-keyword / account-ban detection (#5600) New docs/security/BAN_DETECTION.md documenting the previously-undocumented system: - the 8 built-in ACCOUNT_DEACTIVATED_SIGNALS + custom keywords are additive - detection flow (body substring match -> terminal `banned` state, skipped in account selection; `deactivated` on 401/403; autoDisableBannedAccounts) - scope: global (all providers); the signal strings target OAuth/subscription scrapers - custom keywords: add path, 200-char cap, hot-reload, and the false-positive warning (raw substring match -> prefer full ban sentences, not "quota"/"limit") - recovery: terminal states never auto-recover -> re-test / re-auth / re-enable Registered in security meta.json; cross-linked from RESILIENCE_GUIDE (terminal states). Docs-only. Closes #5600 * docs(security): clarify deactivated vs expired terminal-status split (#5600) The same ACCOUNT_DEACTIVATED signal surfaces as two different terminal statuses depending on the code path: chatCore.ts inline writes 'deactivated' (401/403 via classifyProviderError), while markAccountUnavailable() -> resolveTerminalConnectionStatus() writes 'expired'. Document both. * fix: surface relay proxy-test errors instead of silent failure (#5716) (#5765) * refactor(api): extract pure discovery leaves from provider-models route (#5758) Split src/app/api/providers/[id]/models/route.ts (2511 -> 1818 LOC) by moving the cohesive, DB-free discovery building blocks into four leaves under discovery/: - helpers.ts record/string coercion, Azure + base-url helpers, bearer/named-openai header builders - normalizers.ts Antigravity / DataRobot / OpenAI-like / SAP models response normalizers - providerModelsConfig.ts PROVIDER_MODELS_CONFIG + ProviderModelsConfigEntry - providerSets.ts NAMED_OPENAI_STYLE_PROVIDERS + isNamedOpenAIStyleProvider The host keeps all request orchestration and imports the leaves back. The moved symbols were module-private, so the route's public export set (GET) is unchanged and no external importer needs updating. Bodies are byte-identical: the code-line multiset of host + leaves equals the original route verbatim. Tests: - repoint the qwen-web source-guard in catalog-updates-v3829-kimi-qwen to the new config leaf (assertions unchanged) - add provider-models-discovery-split as the split regression guard (leaf public surface + host wiring + the #5570 cablyai->aimlapi entry swap) * fix(memory): enabling Qdrant activates it as the engine + inline guidance (#5597) (#5741) * fix(memory): enabling Qdrant now activates it as the engine + inline guidance (#5597) Enabling Qdrant in the Engine tab was inert: retrieval only routes to Qdrant when memoryVectorStore === "qdrant" (the default "auto" never selects it), and the card only wrote qdrantEnabled — nothing set the engine selector, and there is no UI for it. So users configured Qdrant, saw "enabled", but it was never actually used. - PUT /api/settings/qdrant now sets memoryVectorStore alongside the toggle: enable -> "qdrant", disable -> "auto". Editing other fields leaves it untouched. - Add inline guidance to QdrantConfigCard: a Tier-1-vs-Tier-2 banner + per-field help (host, collection, embedding model). Note there is no "vector dimension" or "distance metric" field: dimension is auto-detected from the embedder, distance is always Cosine. - Document the real behavior in MEMORY.md: engine gate, no back-fill of existing memories, dimension auto-detect, Cosine-only, API-key-only auth. Tests: tests/integration/qdrant-routes.test.ts — enable->qdrant, disable->auto, and field-edit-without-enabled leaves the engine untouched (TDD: red -> green). Closes #5597 * fix(memory): invalidate memory-settings cache on Qdrant toggle (#5597) The PUT handler wrote memoryVectorStore to the DB but retrieval reads through getMemorySettings(), a module-level cache. Without busting it, the engine switch did not take effect until a process restart (the DB said qdrant, retrieval kept routing to sqlite-vec). Now calls invalidateMemorySettingsCache() after the write, mirroring src/app/api/settings/memory/route.ts. Regression test warms the cache, toggles via the route, and asserts getMemorySettings().vectorStore flips to qdrant (fails without the invalidate call). * fix(compression): record Context Editing telemetry on the streaming path (#5761) Streaming SSE responses now preserve context_management from the final message_delta snapshot and fire the telemetry hook in onStreamComplete, so context-clear savings surface in compression analytics for streaming (not just non-streaming). Additive telemetry, Claude-only, opt-in-neutral. gaps v3.8.42 — T01 (5.1). Test: context-editing-streaming-telemetry.test.ts (3, failing->passing). * Persist batch item checkpoints during recovery (#5753) * fix(sse): checkpoint batch item recovery * fix(db): renumber batch checkpoints migration 110→112 (collision with #5667) 110 was taken by 110_model_context_overrides.sql (#5667), which landed on the release branch after this PR branched. migrationRunner throws a hard version- collision error on startup when two files share a numeric prefix. 112 is the next free slot (110/111 taken on the release tip). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix: resolve CCR MCP retrieve principal from api-key auth context (#5649) (#5768) * feat(cli): show version in startup banner (integrates #5752) (#5769) * feat(cli): show version in startup banner Print dim 'v<version>' line below ASCII art logo in omniroute serve. Uses readFileSync (same pattern as program.mjs) to read package.json. Closes #5749. * test(cli): guard startup-banner version line (#5752) Source-inspection test (same pattern as cli-serve-port.test.ts) asserting serve.mjs parses the version from package.json and prints v${_pkg.version} in the startup banner — satisfies Hard Rule #8 for the bin/ change. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * docs(changelog): credit #5752 startup-banner version line (thanks @chirag127) --------- Co-authored-by: Chirag Singhal <76880977+chirag127@users.noreply.github.com> * fix(proxyfetch): skip fallback for non-replayable bodies (#5770) * chore(release): open v3.8.42 cycle Bump version to 3.8.42, add CHANGELOG placeholder, sync openapi/electron/open-sse + 42 i18n CHANGELOG mirrors. * chore: remove unused qdrant schema aliases (#5404) Integrated into release/v3.8.42 * chore: remove unused memory schema aliases (#5403) Integrated into release/v3.8.42 * chore: remove unused quota schema types (#5402) Integrated into release/v3.8.42 * chore: remove unused playground row type (#5401) Integrated into release/v3.8.42 * chore: remove unused codegraph exports (#5400) Integrated into release/v3.8.42 * chore: remove unused notion client type (#5399) Integrated into release/v3.8.42 * chore: remove unused settings types (#5398) Integrated into release/v3.8.42 * chore: remove unused combo types (#5396) Integrated into release/v3.8.42 * chore: remove unused provider types (#5393) Integrated into release/v3.8.42 * chore: remove unused skillssh skill type (#5392) Integrated into release/v3.8.42 * chore: remove unused status hex key type (#5391) Integrated into release/v3.8.42 * chore: remove unused batch provider type (#5390) Integrated into release/v3.8.42 * chore: remove unused skills schema types (#5389) Integrated into release/v3.8.42 * chore: remove unused codex auth input type (#5388) Integrated into release/v3.8.42 * chore: remove unused memory schema types (#5387) Integrated into release/v3.8.42 * chore: remove unused playground row type (#5386) Integrated into release/v3.8.42 * chore: remove unused qdrant schema types (#5385) Integrated into release/v3.8.42 * chore: remove unused kiro social schema (#5384) Integrated into release/v3.8.42 * chore: remove unused memory schema types (#5383) Integrated into release/v3.8.42 * chore: remove unused audit action type (#5382) Integrated into release/v3.8.42 * chore: remove unused agent skills schema types (#5381) Integrated into release/v3.8.42 * chore: remove unused shared logger default export (#5380) Integrated into release/v3.8.42 * chore: remove unused sse logger helpers (#5378) Integrated into release/v3.8.42 * chore: remove unused sse model legacy helpers (#5377) Integrated into release/v3.8.42 * chore: remove unused v1 search response schema (#5376) Integrated into release/v3.8.42 * chore: remove unused cloud agent result schemas (#5375) Integrated into release/v3.8.42 * chore: remove unused a2a routing logger readers (#5374) Integrated into release/v3.8.42 * chore: remove unused webhook delivery detail export (#5372) Integrated into release/v3.8.42 * chore: remove unused api key type (#5395) Integrated into release/v3.8.42 * chore: remove unused usage types (#5397) Integrated into release/v3.8.42 * chore: remove unused cloud agent input types (#5373) Integrated into release/v3.8.42 * deps: bump electron from 42.4.1 to 42.5.1 in /electron (#5413) Integrated into release/v3.8.42 * deps: bump the production group with 11 updates (#5414) Integrated into release/v3.8.42 * fix: frame non-streaming JSON responses (#5416) Integrated into release/v3.8.42 * fix(services): runNpm shell on win32 + prefix via env for Node 24 EINVAL (#5379) (#5474) Node 24 refuses execFile of npm.cmd without a shell (nodejs/node#52554), so embedded-service install (9Router/CLIProxy) failed with spawn EINVAL on Windows. runNpm now enables shell on win32 only; to stay Hard-Rule-#13 safe under a shell, the install --prefix is passed via npm_config_prefix (env) instead of an argv path (survives spaces), and the user-supplied version is constrained by SERVICE_VERSION_PATTERN at the route boundary. * fix(cli): restore dist/tls-options.mjs to npm tarball (#5452) (#5503) Closes #5452 * fix(dashboard): render onboarding wizard on /providers/new (#5427) (#5505) Closes #5427 * fix(db): EBUSY-safe database import on Windows (#5406) (#5507) Closes #5406 * chore: remove unused gamification streak exports (#5463) * chore: remove unused headroom log tail export (#5464) * chore(dead-code): remove unused prompt cache control helper (#5466) * chore(duplication): share vscode metadata helpers (#5471) * chore(duplication): share auth zip extractors (#5475) * chore(duplication): share vscode tokenized request helper (#5479) * chore(duplication): share quota strategy ranking helpers (#5482) * chore(duplication): share recharts donut card (#5484) * chore(duplication): share provider specific validation (#5485) * chore(duplication): share batch response formatter (#5488) * chore(duplication): share redis runtime helpers (#5490) * chore(duplication): share version manager request parsing (#5492) * chore(duplication): share media generation route helpers (#5493) * chore(duplication): share settings transform schemas (#5496) * chore(duplication): share relay stream finalizer (#5497) * chore(duplication): share machine id fallback (#5498) * chore(duplication): share node sqlite adapter (#5500) * fix: treat terminal stream cancels as complete (#5491) * fix post-merge ci regressions (#5467) * fix: gate claude adaptive thinking defaults (#5480) Co-authored-by: KooshaPari <koosha@example.com> * fix(fallback): normalize provider error rule headers (#5473) Co-authored-by: KooshaPari <koosha@example.com> * fix(rate-limit): normalize queue refresh settings (#5499) Co-authored-by: KooshaPari <koosha@example.com> * chore(ci): add npm fetch-retry + release-freeze protocol (Hard Rule #21) (#5506) - .npmrc: bump fetch-retries 2->5 with backoff so transient registry ECONNRESET during npm ci (electron-release, v3.8.41) retries instead of failing the job; applies repo-wide. - CLAUDE.md Hard Rule #21: release-freeze coordination marker (label release-freeze) that campaign workflows honor before merging into the active release branch, preventing the mid-release commit races that forced CHANGELOG re-reconciliation in v3.8.40/v3.8.41. * chore(duplication): share service install helpers (#5495) Share service install helpers; re-add SERVICE_VERSION_PATTERN regex to the shared schema (dropped in extraction, #5474) + tests rejecting malformed versions. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * chore(duplication): share proxy route handlers (#5472) Share proxy route handlers; add resolveProxyLookupResponse regression test (3 branches + custom whereUsed param name). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * chore(duplication): share combo builder model options (#5477) Share combo builder model options; add regression test locking custom-model source classification (manual->custom, api-sync->imported). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * chore(dead-code): ratchet dead code baseline (#5468) Ratchet dead-code baseline to the true measured value (310 -> 225) after the v3.8.42 dead-code + duplication wave. Measured by check-dead-code.mjs on the tip. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(dashboard): provider-add UX — i18n labels, surface import warning, default key name (#5511) * fix(dashboard): provider-add UX — real i18n labels, surface import warning, default key name (#5421 #5428 #5429 #5431 #5435) Three rough edges in the Add-API-Key / model-import flow, all from the provider-catalog audit: 1. Validation Model + Account ID form fields shipped untranslated i18n stub copy ('Validation Model Id Label', etc.) that rendered verbatim. Replaced with real copy in en.json. 2. Model import silently fell back to the cached/local catalog — the route returns a 'warning' field the import hook never read. New pure helper extractImportWarning surfaces it as a log line. 3. Required connection-name field defaulted to '' (let browser autofill inject garbage like 'wiw'); now defaults to 'main'. Regression guard: tests/unit/provider-add-ux-i18n-import-warning.test.ts. * fix(dashboard): compress AddApiKeyModal comment to keep file under frozen size cap * fix(providers): align Muse Spark (Meta AI) cookie copy to ecto_1_sess (#5449) (#5513) * fix(providers): align Muse Spark (Meta AI) cookie copy to ecto_1_sess (#5449) The default Meta AI session cookie migrated from the retired abra_sess to ecto_1_sess (META_AI_DEFAULT_COOKIE), but the provider form hint and one 401 auth-failure message still named abra_sess, telling users to paste a cookie that no longer exists. Both strings now name ecto_1_sess. Regression guard: tests/unit/muse-spark-cookie-copy-5449.test.ts. * chore: reconcile CHANGELOG with release (keep #5449 + #5511 bullets) * fix(providers): correct FriendliAI (serverless) + Novita (/openai/v1) endpoints (#5430 #5455) (#5515) * fix(providers): correct FriendliAI (serverless) and Novita (/openai/v1) endpoints (#5430 #5455) Both rejected valid keys, verified live with real provider keys: - FriendliAI baseUrl was /dedicated/v1/... which 403s a serverless flp_* token; switched to /serverless/v1/... + serverless modelsUrl. - Novita baseUrl was the legacy /v3/... with a typo'd model id ai-ai/... (both 404); switched to OpenAI-compat /openai/v1/... + meta-llama/llama-3.1-8b-instruct. Regression guard: tests/unit/provider-endpoints-friendliai-novita.test.ts. * chore: reconcile CHANGELOG with release (keep #5430/#5455 + prior bullets) * fix(providers): gate import for tool-only providers + sanitize Coze validation error (#5420 #5426) (#5522) #5420: the 'Import Models' button now hides for tool-only providers (web search / web fetch) via a capability check over resolved serviceKinds, not just the -search suffix — firecrawl/jina-reader (webFetch) no longer show an Import button that 400s. No LLM/media provider is affected. #5426: Coze key validation no longer leaks the raw upstream envelope ({code,msg,logId,from}) into the UI; the Coze error becomes a friendly message, scoped to provider === 'coze' so no other provider is affected. Regression guards: tests/unit/model-listing-capability-5420.test.ts, tests/unit/coze-validation-error-5426.test.ts. * fix(providers): correct LongCat free tier — GA LongCat-2.0, one-time 10M (KYC) (#5508) LongCat's preview ended and the Flash-* line was retired (2026-05-29); the API now exposes only the GA LongCat-2.0 (1M context, 128K output). The free tier is a ONE-TIME 10M-token grant unlocked after account signup + KYC verification — NOT a recurring daily/monthly allowance. The catalog still described the retired preview/Flash models and a recurring 150M / 5M-per-day budget; this corrects every reference. Config / code: - registry/longcat: model LongCat-2.0-Preview -> LongCat-2.0, name + comment reflect one-time 10M (KYC) and pay-as-you-go beyond it. - freeModelCatalog: longcat-2.0-preview (150M, recurring-daily) -> LongCat-2.0 (10M, freeType one-time-initial via creditTokens). - freeTierCatalog: drop longcat from the recurring-monthly budget map (one-time credits are excluded by that catalog's own rule). - regional.ts freeNote: one-time 10M after signup + KYC, not recurring. - providerCostData: longcat-flash-lite -> longcat-2.0 (pay-as-you-go 0.75/2.95 per 1M, 10M free quota). - validation probe model longcat -> LongCat-2.0. Tests: - free-tier-catalog: longcat now absent from FREE_TIER_BUDGETS; providerCount 22->21 (clean 21->20); documented total ~1.39B. - tierResolver: sample model flash-lite -> LongCat-2.0. Docs: - README, PROVIDERS-GUIDE, FREE-TIERS-GUIDE, FREE_TIERS: 50M/day Flash-Lite -> one-time 10M LongCat-2.0 (KYC); 'No auth' -> API key + KYC. - Regenerated PROVIDER_REFERENCE.md (picks up the new freeNote). typecheck:core clean; changed-file lint 0 errors; docs-sync PASS. * fix(providers): Bytez OpenAI-compat base URL + auth-only key validation (#5422) (#5528) Bytez IS OpenAI-compatible at .../models/v2/openai/v1, but the registry stored the bare .../models/v2 base, so validation's chat-probe hit .../models/v2/chat/completions -> 404 -> 'endpoint not supported'. Part A: registry baseUrl -> full OpenAI-compat chat path. Part B: a Bytez account only serves catalog-provisioned models, so chat-probe validation 404s even for valid keys. validateBytezProvider instead probes the auth-only GET .../models/v2/list/tasks (200=valid, 401/403=invalid). Verified live with a real key: list/tasks -> 200 (valid) / 401 (invalid). Regression guard: tests/unit/bytez-validation-5422.test.ts. * fix(providers): remove dead Phind provider + dedupe HuggingChat catalog listing (#5530) Integrated into release/v3.8.42 (round 3). Dead Phind removal + HuggingChat dedupe, verified complete. * fix: protect dynamic dashboard tests with CSRF (#5405) Integrated into release/v3.8.42 (round 3). Reworked CSRF (HMAC-signed synchronized token). * docs: clarify bifrost relay backend envs (#5520) Integrated into release/v3.8.42 (round 3). Doc-only: bifrost relay envs. * test(quota): guard Claude-Code identity version lockstep (Phase 2) (#5514) Integrated into release/v3.8.42 (round 3). Claude-Code identity version lockstep guard. * feat(compression): T02 — honest default-on pipeline inflation guard (H1) (#5527) Integrated into release/v3.8.42 (round 3). T02 pipeline inflation guard * feat(compression): T05/C2 — caveman dedup + ultra packs for de, fr, ja (#5529) Integrated into release/v3.8.42 (round 3). T05/C2 caveman packs de/fr/ja * feat(compression): T05/C6 — Chinese (zh / wenyan) caveman pack + detection (#5532) Integrated into release/v3.8.42 (round 3). T05/C6 zh/wenyan pack + detection * feat(compression): T07/R9 — gradle + dotnet RTK catalog filters (#5537) Integrated into release/v3.8.42 (round 3). T07/R9 RTK gradle+dotnet filters * refactor(dashboard): T11 — drop duplicate caveman on/off toggle from the compression settings tab (#5524) Integrated into release/v3.8.42 (round 3). T11 consolidate duplicate caveman controls; i18n'd the panel hint string (source key). * test relay routing fallback headers (#5526) Integrated into release/v3.8.42 (round 3). Relay fallback header extraction + tests (drift-shed: dependabot #5415 commit dropped). * fix(opencode-plugin): bump to 0.2.0 + auto-publish on release (#5363) - Bump @omniroute/opencode-plugin from 0.1.0 to 0.2.0 so CI publishes the accumulated fixes (auto combos, schema fields, debug logging) that were merged after the initial 0.1.0 publish on May 24. - Add auto-bump step in npm-publish.yml: detects if the plugin dir changed since the last release tag and auto-increments patch version, so the plugin never falls behind again on future releases. Co-authored-by: herjarsa <herjarsa@users.noreply.github.com> * [codex] add bifrost auto fallback cooldown (#5519) Integrated into release/v3.8.42 (round 3). Bifrost auto fallback cooldown; header reconciled with #5526 helper + env-doc. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix onboarding schema client import (#5525) Integrated into release/v3.8.42 (round 3). Browser-safe onboarding schema import (drift-shed: dependabot #5415 dropped). * docs: add relay backend strategy guide (#5547) Port #5533 relay strategy guide to release/v3.8.42 (doc-only). * fix(chatgpt-web): support GPT-5.5 Pro handoff (#5536) Integrated into release/v3.8.42 (round 3). GPT-5.5 Pro async stream_handoff support (drift-shed: dependabot #5415 dropped). * fix(providers): persist Configured filter across page reloads (#5510) Integrated into release/v3.8.42 (round 3). Persist Configured filter across reloads; extracted shouldSyncProviderDisplayMode race guard + TDD test (Closes #4059). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(mimocode): route per-account traffic through SOCKS5 proxy dispatchers (#5521) Integrated into release/v3.8.42 (round 3). Per-account SOCKS5 dispatcher routing — completes #3837's stored proxy config with the actual undici dispatcher layer. Rebased onto .42 (dropped the CI-workflow-deletion commits; merged proxyUrlMap dispatch with #3837's acct.proxy storage). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(chatgpt-web): portable SHA3-512 for sentinel PoW under Electron/BoringSSL (#5531) (#5540) * fix(build): keep ioredis out of the client/CLI bundle via SPAWN_CAPABLE_PREFIXES leaf (#5546) Fix the dast-smoke ioredis client-bundle regression (proven: dast-smoke green). Remaining reds are pre-existing base-reds/flakes (base.ts file-size, GOLDEN provider drift, shard-1 compression flakes) inherited by all PRs — not from this change. * chore(release): finalize v3.8.42 CHANGELOG + cycle-close reconciliation - Reconcile CHANGELOG.md for v3.8.42: 40 bullets covering all 89 commits since v3.8.41 (4 features, 26 fixes, 10 maintenance incl. 2 rollups for the 35-PR dead-code sweep + 17-PR DRY consolidation), dedup the merge- artifact duplicate New Features headers, set release date 2026-06-30. - Sync 42 docs/i18n/*/CHANGELOG.md mirrors. - Document 3 new chatgpt-web/TLS env vars in .env.example + ENVIRONMENT.md (OMNIROUTE_CGPT_WEB_PRO_TIMEOUT_MS, _PRO_POLL_INTERVAL_MS, OMNIROUTE_CHATGPT_STREAM_FIRST_BYTE_TIMEOUT_MS). - Cycle-close ratchet rebaselines: eslintWarnings 4116->4121, file-size base.ts/chatgpt-web.ts/strategySelector.ts/chatgpt-web.test.ts (all inherited drift, justified inline). - Regenerate provider translate-path golden snapshot for the merged bytez/friendliai/novita endpoint fixes. * chore(changelog): cover #5415 dev-deps bump merged from main The release/v3.8.42 ↔ main merge (c4c1b56ba) brought #5415 (development dependency group, 9 updates) and #5533 (relay backend guide) from main. #5533's content is already covered by the #5547 port bullet; add a Maintenance bullet for #5415 and re-sync the 42 i18n CHANGELOG mirrors. * test: relocate 2 orphaned test files to collected runner paths check:test-discovery flagged two cycle-merged tests that no runner collects (they never ran → false coverage confidence): - compression-settings-tab-consolidation.test.tsx (#5524) → tests/unit/ui/ (vitest UI runner collects tests/unit/ui/**/*.test.tsx); 3/3 pass. - providers/providerPageStorage.test.ts (#5510) → tests/unit/dashboard/ ('providers' is not a collected subdir; 'dashboard' is, same ../../../ import depth); 30/30 pass under the node runner. Both confirmed green when actually executed; no assertions weakened. * fix(release): repair inherited base-red tests from #5480/#5527/#5427/#5521 The fast-path (PR->release/**) does not run the full unit+integration suites, so four merged feature PRs shipped with stale/incorrect tests that only surface on the release PR (PR->main). Repairs (features are correct; align tests to the new behavior — no assertions weakened): - #5480 (gate claude adaptive thinking): adaptive thinking is now injected only for a real Claude Code client (x-app:cli / claude-code UA), not for any bare Claude OAuth token. claude-thinking-tool-choice-guard + base-thinking-budget-5312 now identify as a Claude Code client to exercise the adaptive path (3 tests). - #5527 (T02 inflation guard): the guard reverts a stacked body that did not shrink in tokens. The bail-out/advancement fixtures used growth-appending mock engines; they now carry a droppable padding message the engines empty, so the body realistically shrinks and the marker assertions survive. bailout (5), stacked-async (3), engine-enabled-toggle (2). - #5427 (render onboarding wizard at /providers/new): integration-wiring asserted the old redirect stub; now asserts the route renders ProviderOnboardingWizard. - #5521 (mimocode SOCKS5 per-account proxy): the constructor's default account omitted the proxy field (undefined), breaking the 'all proxies null' backward compat guard. Default it to null, mirroring syncAccountsFromCredentials(). * fix(proxyfetch): skip fallback for non-replayable bodies --------- Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> Co-authored-by: Jan Leon <Jan.gaschler@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Randi <55005611+rdself@users.noreply.github.com> Co-authored-by: Diego Rodrigues de Sa e Souza <8016841+diegosouzapw@users.noreply.github.com> Co-authored-by: KooshaPari <42529354+KooshaPari@users.noreply.github.com> Co-authored-by: KooshaPari <koosha@example.com> Co-authored-by: backryun <bakryun0718@proton.me> Co-authored-by: Hernan Javier Ardila Sanchez <hjasgr@gmail.com> Co-authored-by: herjarsa <herjarsa@users.noreply.github.com> Co-authored-by: Arthur Bodera <abodera@gmail.com> Co-authored-by: PizzaV <103120356+pizzav-xyz@users.noreply.github.com> Co-authored-by: OpenClaw Auto <openclaw-auto@example.invalid> * Move CLI profile sync toggles to CLI Code (#5778) * move CLI profile sync toggles to CLI Code * test CLI profile auto-sync toggles * Document CLI profile auto-sync flags * docs(changelog): note CLI profile auto-sync card moved to CLI Code (#5778) --------- Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> * fix(grok-cli): parse expires_at from auth.json and exp from JWT to fix auto-refresh (#5775) * fix(grok-cli): parse expires_at from auth.json and exp from JWT to fix auto-refresh * docs(changelog): note grok-cli token auto-refresh fix (#5775) --------- Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> * fix(providers): import intentional local-catalog-only providers instead of 502 (#5460, #5465) (#5787) The model-sync route returned a hard 502 ('Remote model discovery failed; local catalog fallback not synced') for every provider whose local catalog is its ONLY discovery source (Reka #5460, t3.chat #5465, embedding/rerank like voyage-ai/jina-ai, Qwen-OAuth, and web-cookie providers). The /models route now flags catalogs that are the provider's intended source (no remote /models endpoint) with intentional:true; model-sync imports those instead of 502-ing, while a genuinely degraded remote fallback still surfaces. New dependency-free leaf degradedLocalCatalog.ts. Also fixes t3.chat's confusing add-credential hint: it no longer renders the circular 'Required cookie: convex-session-id + Cookie header...' copy and wires the step-by-step DevTools hint (t3ChatWebCookieHint) already translated in every locale. Regression guards: tests/unit/sync-models-degraded-local-catalog-5460-5465.test.ts, tests/unit/t3chat-web-cookie-hint-5465.test.ts, + intentional-flag assertions in tests/unit/provider-models-route.test.ts. * fix(api): self-hydrate model aliases from DB on GET after restart (#5777) * Fix grammatical errors in readme (#5738) * fix(api): self-hydrate model aliases from DB on GET when in-memory state is empty In the standalone production build, webpack creates two separate copies of modelDeprecation.ts — one hydrated by the startup path (used for request routing) and one used by the /api/settings/model-aliases API route. The API route's copy starts with an empty _customAliases after each server restart, causing the Settings → Routing UI to show 'No exact-match aliases configured' even though the aliases are persisted in the DB. The GET handler now detects an empty _customAliases state and reads the modelAliases key from the settings blob in the DB, calling setCustomAliases() to hydrate this module instance. This is a best-effort fallback — when _customAliases is already populated (e.g. by the startup path in dev mode), no DB read occurs. Regression test: tests/unit/model-aliases-settings-route-selfheal.test.ts - Verifies hydration from DB when in-memory state is empty - Verifies no hydration when in-memory state is already populated - Verifies graceful handling when no modelAliases exist in DB --------- Co-authored-by: Chirag Singhal <76880977+chirag127@users.noreply.github.com> Co-authored-by: marcelpeterson <marcelpeterson@users.noreply.github.com> Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> * refactor(usage): extract 5 provider usage families into leaves (#5782) Split open-sse/services/usage.ts (1723 -> 901 LOC) by moving the Cursor, Kimi, Codex, Claude and Kiro usage-fetcher families into cohesive leaves under open-sse/services/usage/ (mirroring the existing glm/minimax/antigravity/quota/ scalars leaves): - usage/cursor.ts getCursorUsage (+ CURSOR_USAGE_CONFIG, decodeCursorJwtSub) - usage/kimi.ts getKimiUsage (+ KIMI_CONFIG, getKimiPlanName) - usage/codex.ts getCodexUsage (+ CODEX_CONFIG) - usage/claude.ts getClaudeUsage / getClaudePlanLabel (+ CLAUDE_CONFIG, legacy) - usage/kiro.ts getKiroUsage / buildKiroUsageResult / discoverKiroProfileArn (+ helpers) The host keeps the getUsageForProvider dispatcher and imports the fetchers back; the public export set is unchanged — buildKiroUsageResult + discoverKiroProfileArn are re-exported from the kiro leaf (the kiro-* tests import them from services/usage) and __testing stays wired to the moved claude/kiro internals. Bodies are verbatim: the code-line multiset of host + leaves equals the original. Adds tests/unit/usage-families-split.test.ts pinning the leaf surface, the kiro re-export identity, the __testing wiring, and getClaudePlanLabel's pure logic. * chore(docs): sync i18n CHANGELOG mirrors with root [3.8.43] section (#5789) Regenerate the docs/i18n/<locale>/CHANGELOG.md [3.8.43] blocks from the root CHANGELOG so the mirror body size returns within the 25% docs-sync tolerance. Clears a pre-existing release-time drift (mirrors were ~26% smaller than root) that was failing check-docs-sync and blocking every local commit on the release branch. * fix(providers): correct stale/broken provider metadata (#5487, #5461, #5534, #5470) (#5790) - #5487 Qoder: replace the untranslated i18n stubs (personalAccessTokenLabel, qoderPatHint, qoderPatPlaceholder) with real copy; extend the STUB_KEYS guard. - #5461 Scaleway: website pointed at scaleway.com/en/ai/generative-apis (HTTP 404); repoint at the live docs URL /en/docs/ai-data/generative-apis/. - #5534 Microsoft 365 Copilot: rewrite the vague authHint with concrete DevTools WebSocket steps (the token lives on the Chathub WS URL, not an Authorization header). - #5470 Together AI: retired the $25 signup credit and is now fully prepaid (min $5); hasFree false + a prepaid notice instead of the stale free-tier freeNote (verified live). Regression guards: tests/unit/provider-metadata-5461-5470-5534.test.ts + Qoder keys added to tests/unit/provider-add-ux-i18n-import-warning.test.ts. * fix(dashboard): neutral badge for unsupported validation + clickable OAuth error links (#5442, #5486) (#5795) - #5442 LMArena (and any provider with no live validator) returns { unsupported: true } from /api/providers/validate and Save succeeds, but the Add-API-Key modal only had success/failed states so it rendered a red 'Invalid' badge. Add an 'unsupported' result → neutral info 'N/A' badge via the pure leaf validationBadgeProps(); both validate handlers now map data.unsupported to it. - #5486 GitLab Duo's OAuth setup error embeds a registration URL (gitlab.com/-/profile/applications) but the OAuth error step rendered it as dead red text. New LinkifiedText component (+ pure ReDoS-safe linkify util) makes any http(s) URL in an OAuth error clickable; the GitLab Duo backend message already carries the full setup steps. Regression guards: tests/unit/validation-badge-unsupported-5442.test.ts, tests/unit/oauth-error-linkify-5486.test.ts. Frozen god-files kept within cap (AddApiKeyModal 868/868, OAuthModal 968/969). * fix(system): route in-app auto-update npm calls through the win32 shell helper (#5542) (#5797) The in-app auto-update flow called execFileAsync("npm", ...) directly for the version lookup (versionCheck.getLatestVersionFromNpmCli), dependency install, global install, and native rebuild. On Windows npm is npm.cmd and Node >=24 refuses to execFile a .cmd without a shell (nodejs/node#52554), so those calls threw 'spawn npm ENOENT'. Route them through buildNpmExecOptions (the same win32-shell helper the embedded-services installer uses, fix #5379). The global install spec is validated with SERVICE_VERSION_PATTERN before it is shell-joined (Hard Rule #13). Not the pnpm/npx swap the issue proposed — that is the wrong direction for an 'npm install -g' flow already solved elsewhere in-repo. Regression guard: tests/unit/autoupdate-npm-win32-5542.test.ts. * refactor(sse): extract cursor protobuf wire primitives into a leaf (#5794) Split open-sse/utils/cursorAgentProtobuf.ts (1520 -> 1400 LOC) by moving the low-level protobuf wire-format primitives — varint/tag/length-delimited encode+ decode + the generic field walker (encodeVarint, encodeTag, encodeBytes, encodeString, encodeMessage, encode{UInt32,Bool,Double}Field, decodeVarint, checkedLen, decodeFields, findField, decode{String,Varint}Field, the Field type and the WT_VARINT/WT_LEN wire-type constants) — into cursorAgentProtobuf/wire.ts. These primitives were module-private, so the host's public API is unchanged; the host imports them back internally. Bodies are verbatim: the code-line multiset of host + wire.ts equals the original. First layer of the codec decomposition — the value/framing codec and the message encoders/decoders build on this and stay in the host (they share host-retained helpers; splitting them is a separate step). Adds tests/unit/cursor-protobuf-wire-split.test.ts pinning the leaf surface, the encode/decode round-trip invariants, the buffer-overrun guard, and the host wiring. * test(runtime): guard tsx/esm→esbuild transform path on boot (#5757) (#5773) #5757 reported that a fresh `npm install omniroute` pulls `esbuild@0.28.1` transitively via `tsx` (a runtime dependency the CLI registers at boot in `bin/omniroute.mjs`), and proposed forcing `esbuild@0.27.4`. That override is unsafe: `tsx@4.22.4` requires `esbuild@~0.28.0` and `fumadocs-mdx@15` (also a runtime dep) requires `esbuild@^0.28.0`; forcing 0.27.x pushes esbuild below both, and 0.28.1 is currently the latest release. The reported transform failure also does not reproduce — OmniRoute targets ES2022, its minimum supported Node is 22.2 (destructuring is native), and tsx targets the running Node, so esbuild never lowers to an unsupported target. Instead of an unsafe version pin, add two regression guards: - functional: spawn the real `node --import tsx/esm` loader on a fixture packed with modern syntax (destructuring/spread, class+private fields, optional chaining, nullish, logical assignment, async + top-level await) and assert it transforms + runs correctly. Fails if a future esbuild regresses the boot path. - dependency-shape: assert the resolved esbuild stays within tsx's declared range, so nobody reintroduces the out-of-range override this issue proposed. No production code changed; no esbuild version pinned. * fix(deps): add missing runtime deps @toon-format/toon and safe-regex (#5771) Both packages are imported at runtime but were only declared for their type shims (safe-regex was via @types/safe-regex; @toon-format/toon had no declaration at all). Missing runtime deps mean: - open-sse/services/compression/engines/headroom/toon.ts imports @toon-format/toon → MODULE_NOT_FOUND on cold pnpm/npm install - open-sse/services/compression/engines/ccr/ccrQuery.ts imports safe-regex → MODULE_NOT_FOUND Both engines are wired into the stacked compression pipeline (default enabled), so a fresh clone that does not have a stale node_modules from a previous version crashes as soon as the pipeline runs. Verified with pnpm ls / grep before/after. * fix(oauth): clamp grok-cli expired-token expiresIn to a positive value (#5775 follow-up) (#5820) An already-expired grok-cli token (real expires_at/exp in the past) produced a negative expiresIn, which is truthy in the import-token route and maps to a PAST expiresAt — AutoCombo then reads that as 'already expired' and excludes the connection instead of refreshing it. Clamp with Math.max(1, expiresIn) so an expired token is treated as due-for-refresh. Extends #5775 (thanks @Chewji9875). Regression: 2 new cases in tests/unit/grok-cli-oauth.test.ts (expired JWT exp + expired JSON expires_at), both failing-then-passing. * fix(model-aliases): back custom-alias store with globalThis (#5777 follow-up) (#5821) #5777 self-healed the GET /api/settings/model-aliases symptom at the route layer, but the root cause remained: modelDeprecation.ts held _customAliases in a plain module-level let, which webpack duplicates across the startup and app-route module graphs (same class as #5312). Startup hydration landed on one copy; the API route read the other (empty) one. Back the store with globalThis (__omniroute_customAliases__) so both instances share one store — the exact pattern already used by thinkingBudget.ts/backgroundTaskDetector.ts (#5312). The route-layer DB self-heal from #5777 stays as a harmless fallback. Extends #5777 (thanks @jleonar2). Regression: tests/unit/model-aliases-globalthis-5777.test.ts (fails on the plain-let store: never populates globalThis, never reads a sibling instance's write). * chore(release): rebaseline file-size + test-masking ratchets for v3.8.43 (#5609) DRIFT acumulado dos 109 commits do ciclo v3.8.43 (fast-gate PR->release nao roda check:file-size/test-masking; base-reds so afloram na release-PR): - file-size: 8 god-files existentes cresceram + 2 arquivos novos acima do cap + 4 test files cresceram -> frozen ajustado ao estado atual. - test-masking: chatgpt-web.test.ts 281->280 asserts allowlisted (#5549 consolidou 2 assert.equal num unico map-driven; refactor legitimo, nao masking). Modularizacao dos god-files deferida (#3501). * refactor(sse): extract openai-to-gemini pure helpers into a leaf (#5824) Split open-sse/translator/request/openai-to-gemini.ts (873 -> 756 LOC, back under the 800-line cap) by moving the module-private pure helpers — the historical-tool- context string builders (stringifyHistoricalToolArguments, buildInertHistorical*, escapeHistoricalContext*, buildHistoricalToolResultContext), deepCleanUndefined, extractClientThoughtSignature, buildChangedToolNameMap, isVertexGeminiProvider, and applyAntigravityGenerationDefaults (with its GeminiGenerationConfig shape) — into openai-to-gemini/helpers.ts. These were module-private, so the translator's public API is unchanged; the host imports them back internally. Bodies are verbatim: the code-line multiset of host + leaf equals the original. Adds tests/unit/openai-to-gemini-helpers-split.test.ts pinning the leaf's pure behaviour (escaping, undefined-pruning, signature extraction, antigravity generation-config defaults) and the host wiring. * fix(db): re-export modelContextOverrides from localDb (check:db-rules #5609) * test(discovery): wire tests/unit/memory into node runner glob (#5609) typed-decay.test.ts (TV6 typed memory decay, 15 asserts) sat in tests/unit/memory/ which no runner glob collected -> orphan (never ran). Adds 'memory' to the subdir brace-glob in all runner sources (package.json scripts + ci.yml shards) and the COLLECTORS mirror in check-test-discovery.mjs (drift-check keeps them in sync). Passes standalone (15/15); DATA_DIR isolation handled per-file by tests/_setup/isolateDataDir.ts. * test: align 3 stale release tests to landed behavior (#5609) Base-reds surfaced on the release PR (fast-gate PR->release skips these shards): - api-manager-page-static: Self-service Visibility now has 5 switches (added the API-key provider quota-policy bypass toggle, #5731); bump inventory 4->5 while keeping the invariant that every switch declares type=button (verified 5/5 typed). - security-hardening (callLogs PII): #5725 extracted sanitizeErrorForLog into callLogs/format.ts; assert the new wiring (callLogs imports it + format.ts imports piiSanitizer) instead of the removed direct import — PII sanitization still intact. - memory-glm-injection: #5610 made GLM 5.1+ ACCEPT the system role (z.ai docs), so glm-5.1 must PRESERVE system, not fold it. Flip the stale #1701-era assertion. * test(shared): align t3-web web-session expected metadata with hintKey (#5835) The t3-web provider metadata intentionally carries `hintKey: "t3ChatWebCookieHint"` (#5465 — the generic cookie hint reads circular for t3.chat), but the metadata assertion in web-session-credentials was never updated, so it deep-equals against an object missing the field. This is a stale-test base-red on release/v3.8.43 that turns the whole PR queue's "Unit Tests fast-path (1/2)" red. Align the expected object to the shipped source of truth. * test(compression): de-flake rtk_discover sample seeding seedSamples() persisted two byte-identical raw outputs. The raw-output filename is keyed on Date.now() (ms) + a content hash (rawOutput.ts), so two identical captures landing in the same millisecond collapse to one file (the 2nd write overwrites the 1st) -> sampleCount 1 instead of 2. Reproduced at ~25% (501/2000 trials), matching the intermittent Coverage Shard (5/8) failure on fast CI runners. Seed two DISTINCT captures so the store deterministically holds 2 samples regardless of timing (0/2000 collisions after the change). * test(e2e): anchor compression-studio smoke on play-input, not async play-lane The T03 smoke asserted `play-lane` visible on mount, but those per-lane buttons only render after a preview-compression run populates `batch.lanes` (usePreviewCompression keeps batch null until run(); there is no mount auto-run). The smoke intentionally does not drive a compression cascade, so `play-lane` can never appear -> the E2E added in #5727 failed all 3 retries (E2E Tests 4/9). Anchor on the always-present `play-input` panel, which proves the studio body mounted without needing async lane data. * fix(security): explicit http(s) scheme allowlist in linkifyText href CodeQL flagged the <a href> in LinkifiedText (#5486) with js/xss (high) and js/client-side-unvalidated-url-redirection (medium) because href traces back to user-provided text. URL_RE already requires an http(s):// prefix, so a javascript:/data: scheme can never reach href — but that guarantee was only implied by the regex. Validate the scheme explicitly via new URL().protocol before exposing href (non-http(s) degrades to plain text): defense-in-depth that also makes the sink provably safe to static analysis. Regression test added. * fix(ci): register mark-account-unavailable test in stryker tap.testFiles check:mutation-test-coverage --strict (Fast Quality Gates) flagged tests/unit/mark-account-unavailable-numeric-epoch-guard.test.ts as a covering unit test missing from stryker.conf.json tap.testFiles, so its mutant kills would not count (--strict). Add it. Pre-existing tap.testFiles drift on the release tip that fails Fast Quality Gates on every PR into release/v3.8.43, not just this branch. * chore(release): rebaseline eslintWarnings ratchet 4121->4158 (v3.8.43 cycle drift) * chore(release): rebaseline complexity 1981->1982 + cognitive-complexity 842->845 (v3.8.43 cycle drift) * chore(release): rebaseline deadExports 225->227 (v3.8.43 cycle drift) * fix(dashboard): add error boundaries for Combos and MITM Proxy pages (#5788) Integrated into release/v3.8.43 * fix(cli): rename process title to omniroute (#5791) Integrated into release/v3.8.43 * fix(providers): add claude-sonnet-5 to Kiro model catalog (#5796) Integrated into release/v3.8.43 * fix(kiro): bound Claude id dash->dot minor group to protect date-suffixed ids (#5825) Integrated into release/v3.8.43 * fix(db): allowlist modelContextOverrides as intentionally-internal to green release DB-rules gate (#5798) (#5827) Integrated into release/v3.8.43 * fix(sse): stop reasoning-summary drop + duplicated deltas on claude→codex streaming (#5786) (#5832) Integrated into release/v3.8.43 * fix(dashboard): guard null modelAliases values in model picker (#5792) Integrated into release/v3.8.43 * fix(github): drop trailing assistant prefill for Copilot chat (#5802) Integrated into release/v3.8.43 * fix(oauth): disambiguate OAuth connections on username to prevent cross-IdP overwrites (#5803) Integrated into release/v3.8.43 * fix(translator): strip orphaned tool results across request formats (#5805) Integrated into release/v3.8.43 * fix(kiro): stop injecting placeholder user turn on tool-result turns (#5807) Integrated into release/v3.8.43 * fix(mitm): clean up privileged hosts entries on exit when possible (#5808) Integrated into release/v3.8.43 * fix(translator): prevent doubled tool args in OpenAI-to-Claude (#5828) Integrated into release/v3.8.43 * fix(usage): keep tool definitions visible when request log is truncated (#5829) Integrated into release/v3.8.43 * fix(db): preserve healthCheckInterval=0 across create/update (#5822) Integrated into release/v3.8.43 * fix: unify dashboard csrf origin fallback (#5856) Integrated into release/v3.8.43 * fix(kimi-web): migrate to www.kimi.com Connect-RPC API (kimi.moonshot.cn retired) (#5858) Integrated into release/v3.8.43 * fix(qwen-web): unblock validator + chat completion (retired endpoint + missing SPA version header) (#5855) Integrated into release/v3.8.43 * fix(antigravity): 429 hang on credit exhaustion and precise reset time lockout (Cleaned) (#5846) Integrated into release/v3.8.43 * fix(cli): correct rootDir resolution in doctor.mjs on Windows (#5844) (#5845) Integrated into release/v3.8.43 * Show startup time in ready banner (#5799) Integrated into release/v3.8.43 * extracted CorrelationId observability changes from #5275 (#5834) Integrated into release/v3.8.43 * refactor(executors): deduplicate shared utilities and add comprehensive tests (#5720) Integrated into release/v3.8.43 * Harden provider node URL validation (#5760) Integrated into release/v3.8.43 * [codex] Tune adaptive stream readiness timeouts (#5767) Integrated into release/v3.8.43 * fix: restore om-usage HTTP endpoint (#5859) Integrated into release/v3.8.43 * fix(sse): strip zero-width markers from streamed responses (parity with non-streaming) (#5857) Integrated into release/v3.8.43 * [codex] Protect long-running agent goal streams (#5772) Integrated into release/v3.8.43 * refactor(oauth): remove dead legacy OAuth service classes (#5838) The src/lib/oauth/services/ service-class hierarchy is superseded — the live OAuth flow runs through src/lib/oauth/providers.ts + providers/. The old per-provider 'class *Service extends OAuthService' implementations and their barrel had zero production or test references. Removed oauth/openai/github/claude/codex/antigravity/ qwen/qoder + the index barrel (-1559 LOC). Kept kiro.ts, cursor.ts, codexImport.ts (routes import them directly by path, never via the deleted barrel). Proven safe by typecheck:core staying green (a live reference would fail the build) + a filesystem guard test pinning the removal. Salvage of closed PR #5039. gaps v3.8.42 - T10 (5.7). * chore(docs): scope release-freeze to /generate-release only (Hard Rule #21) (#5839) A freeze is authorized ONLY inside /generate-release (raised Phase 0a, lifted Phase 12c). No campaign/session/agent may open a release-freeze mid-development; if one is ever unavoidable outside the release flow it must be requested from the operator in chat first with an explicit "estou criando um freeze" alert. Also codifies: never lift an active captain freeze to unblock campaign merges (it auto-lifts at 12c). * fix(chat): preserve JSON default when stream is omitted (#5866) * fix(chat): preserve JSON default when stream is omitted * chore(chat): type route record guard * fix(api): gate early SSE keepalive on explicit stream intent, keep body untouched Remove the stream:false body normalization so the legacy streaming default (resolveStreamFlag) and the per-key streamDefaultMode json opt-in keep deciding the response framing; the keepalive wrapper is only applied when stream:true is explicit or Accept forces SSE. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(usage): report usage command quotas as percentages + honor observed provider quota resets (#5874) * feat: report usage command quotas as percentages Convert @@om-usage and the HTTP usage endpoint to report personal API key quotas as remaining percentages while keeping USD amounts out of the command output. Scale provider quota remaining percentages by the configured quota cutoff so the protected reserve reads as 0% left. Restore provider USD cost drilldown in the quota dashboard.\n\nAlso sync the 3.8.43 i18n changelog mirrors so the docs-sync pre-commit gate remains green.\n\nTests: DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/internal-usage-command.test.ts; DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/api-key-usage-limits.test.ts; DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/provider-window-costs.test.ts; DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/api-manager-usage-command.test.ts tests/unit/apikeys-usage-command.test.ts; npx eslint <changed files>; npm run typecheck:core; npm run build; npm run check:migration-numbering; npm run check:docs-sync; docker build --target runner-base (cherry picked from commitf66abd2028) * fix: honor observed provider quota resets Detect same-resetAt quota resets when provider usage drops back to the reset floor, and prefer that observed snapshot over stale recorded weekly events for provider USD windows and API-key USD quotas.\n\nTests: npx eslint changed files\nTests: npm run typecheck:core\nTests: DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/lib/quota-reset-events.test.ts tests/unit/provider-window-costs.test.ts tests/unit/api-key-usage-limits.test.ts\nTests: npm run build\nTests: docker build --target runner-base --build-arg OMNIROUTE_BUILD_MEMORY_MB=4096 -t omniroute:quota-reset-window-20260702002300 . (cherry picked from commit39c12a6f17) * docs(changelog): credit usage quota percentages extraction from #5863 Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: Wital <wital@example.com> * fix(github): keep Copilot access-token sessions active (#5875) * fix(github): keep Copilot access-token sessions active GitHub Copilot device-flow accounts may have a GitHub access token and short-lived Copilot token without a refresh token. The proactive health check was treating that as terminal no_refresh_token and marking the connection expired minutes after login. Keep those sessions active, clear stale no_refresh_token state, and refresh the Copilot sub-token when needed.\n\nTests:\n- npx eslint src/lib/tokenHealthCheck.ts tests/unit/token-health-no-refresh-token-expired-5326.test.ts\n- DISABLE_SQLITE_AUTO_BACKUP=true node --import tsx/esm --test tests/unit/token-health-no-refresh-token-expired-5326.test.ts tests/unit/token-health-check.test.ts tests/unit/token-health-check-circuit-breaker.test.ts tests/unit/token-refresh-service.test.ts tests/unit/token-refresh-route-service.test.ts tests/unit/executor-github.test.ts\n- npm run typecheck:core\n- npm run build (cherry picked from commit68095d4796) * docs(changelog): credit Copilot token-health fix extraction from #5863 Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: Wital <wital@example.com> * feat: add NEXT_PUBLIC_LIVE_WS_PUBLIC_URL for custom domain WebSocket support (#5878) * docs: add ai_features scope to GitLab Duo OAuth env setup instructions * docs: add LIVE_WS_ALLOWED_HOSTS env var to example config for LAN/Tailscale setups * feat: add web socket public URL for reverse proxy/Cloudflare Tunnel WebSocket setups * fix(dashboard): resolve live WS public URL at runtime via handshake with scheme validation - Read NEXT_PUBLIC_LIVE_WS_PUBLIC_URL lazily in /api/v1/ws (function, not module-level const) so runtime env changes are honored in prebuilt images. - Only echo/consume publicUrl when it is a ws:// or wss:// URL (server and client guards); anything else is rejected to null. - useLiveDashboard now fetches /api/v1/ws?handshake=1 before connecting and prefers: explicit wsUrl > build-time env > handshake publicUrl > default. - Align GitLab Duo scopes line in .env.example with GITLAB_DUO_CONFIG.scope. - Extend tests: lazy env read + scheme validation cases. - CHANGELOG entry for 3.8.43. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: Septianata Rizky Pratama <ian.rizkypratama@gmail.com> * Add .editorconfig to improve repository standards (#5879) * chore(ci): pass sonar.projectVersion to SonarQube scan so the new-code baseline advances per release (#5880) * fix(dashboard): Modal — two-field auth (Token ID + Token Secret) (#5446) (#5881) * fix(dashboard): add Modal Token ID + Token Secret fields (#5446) Modal authenticates with a Token ID (ak-…) + Token Secret (as-…) pair sent as `Authorization: Bearer <TOKEN_ID>:<TOKEN_SECRET>`. The add-connection form only exposed a single API-key field, so users could not enter both credentials. Add a dedicated two-field form for the `modal` provider: the existing field is relabeled "Token ID" and a new "Token Secret" field is rendered below it. Both are combined into the single encrypted `apiKey` value via a new pure helper `combineModalCredential(id, secret)` → `id:secret`, so the generic bearer executor path emits `Bearer <id:secret>` with no registry/executor/DB changes. An empty secret returns the id verbatim, preserving the ability to paste a pre-combined `id:secret` into the single field. The field hint points to https://modal.com/settings → API Tokens. Registry (baseUrl/executor), DB schema, and the request-time header path are untouched — Modal remains bring-your-own-deploy. Tests: tests/unit/modal-credential-combine.test.ts (5, TDD). * docs(changelog): add v3.8.43 bullet for Modal two-field auth (#5446) * fix(mcp): forwarded caller auth wins over OMNIROUTE_API_KEY env fallback (#5819) (#5882) * fix(middleware): run operator hook code in hardened vm sandbox instead of new Function (#5872) (#5885) * fix(providers): include custom compatible providers in auto/ routing (#5873) (#5886) * fix(db): honor autoBackupEnabled setting for pre-write backups (#5871) (#5888) * fix(dashboard): gate Token Expired badge on terminal testStatus, not raw token expiry (#5836) (#5883) * docs: use pnpm --allow-build flag instead of unsupported approve-builds -g (#5554) (#5884) * fix(dashboard): pre-fill Modal Validation Model Id with the server probe model (#5446) (#5892) * fix(api): strip upstream x-middleware-* headers from proxied responses (#5849) (#5893) * fix(providers): restore codex inference for unprefixed gpt-5.5 on codex-only setups (#5887) (#5895) * test(autoCombo): stabilize model fitness source expectation (#5890) * test(autoCombo): make fitness source test stable against model caps * chore(ci): retrigger checks for PR 5890 * docs(changelog): add 3.8.43 bullet for the autoCombo fitness-source test stabilization (#5890) --------- Co-authored-by: kooshapari <kooshapari@users.noreply.github.com> Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> * docs(architecture): Router Backends & Embedded Services ADR (#5603) (#5891) * routing: add router backend registry * docs(architecture): add Router Backends & Embedded Services ADR (#5603) Document the two orthogonal axes that #5603 asked to clarify: an engine's lifecycle (in-process / supervised / external / disabled) vs the relay routing backend selection (ts / bifrost / auto). Anchors the ADR on the typed `src/domain/routing/routerBackends.ts` registry as the single source of truth, and captures the /api/services/* status-code contract (409/200/404/403/500 + the LOCAL_ONLY loopback guard) so dashboard errors are interpretable. Stacked on the router-backend-registry work so it documents a real contract. * docs(architecture): reduce ADR PR to docs-only — registry lands via #5868; describe adoption as tracked, not current * docs(changelog): add 3.8.43 bullet for the Router Backends ADR (#5891) --------- Co-authored-by: KooshaPari <kooshapari@gmail.com> * fix(ci): re-green release/v3.8.43 fast-gates — db-rules stale allowlist + 4 more base-reds (#5798) (#5896) * fix(db): remove stale modelContextOverrides allowlist entry from check:db-rules (#5798) * fix(ci): clear release/v3.8.43 fast-gates base-reds (env-docs, ADR refs, mutation-cov, ratchets) (#5798) * fix(sse): type-safe resolveBaseUrl/resolveEffectiveKey coercions in BaseExecutor (typecheck:core base-red, #5798) * chore(quality): freeze base.ts at post-typecheck-fix size (#5798) * fix(docs): add required MDX frontmatter to ROUTER_BACKENDS ADR (build base-red, #5798) * fix(image): keep bare gpt-5.5 codex mapping in image resolver (#5902) * fix: preserve codex bare image model over combo shadowing * docs(changelog): credit #5902 codex bare image alias fix * docs(changelog): restore #5902 bullet after merge auto-resolve --------- Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> * fix(providers): route OpenAI responses-only models to /v1/responses (#5842) (#5901) * fix(providers): route OpenAI responses-only models to /v1/responses (#5842) * docs(changelog): restore #5842 bullet after merge auto-resolve ate it * docs(changelog): keep #5842 bullet additive over release tip * chore(release): v3.8.43 — 2026-07-02 * chore(release): allowlist 3 verified-legitimate test-assert reductions (#5805/#5856/#5855) * chore(release): rebaseline file-size caps for base.ts + 2 aligned test files (v3.8.43 release-close) * docs(changelog): add v3.8.43 Contributors section + sync i18n mirrors --------- Co-authored-by: KooshaPari <42529354+KooshaPari@users.noreply.github.com> Co-authored-by: Arthur Bodera <abodera@gmail.com> Co-authored-by: Wahyu Hidayatulloh Pamungkas <87377496+Stazyu@users.noreply.github.com> Co-authored-by: skyzea1 <161649495+skyzea1@users.noreply.github.com> Co-authored-by: José Victor Ferreira <root@josevictor.me> Co-authored-by: Choti Wongbussakorn <126886556+Chewji9875@users.noreply.github.com> Co-authored-by: backryun <bakryun0718@proton.me> Co-authored-by: Jan Leon <Jan.gaschler@gmail.com> Co-authored-by: warelik <warelik@users.noreply.github.com> Co-authored-by: WITALO ROCHA <witalo_rocha@hotmail.com> Co-authored-by: Randi <55005611+rdself@users.noreply.github.com> Co-authored-by: Alex <alexgild@gmail.com> Co-authored-by: Chirag Singhal <76880977+chirag127@users.noreply.github.com> Co-authored-by: Ardem2025 <ardemb22@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: KooshaPari <koosha@example.com> Co-authored-by: Hernan Javier Ardila Sanchez <hjasgr@gmail.com> Co-authored-by: herjarsa <herjarsa@users.noreply.github.com> Co-authored-by: PizzaV <103120356+pizzav-xyz@users.noreply.github.com> Co-authored-by: OpenClaw Auto <openclaw-auto@example.invalid> Co-authored-by: jleonar2 <92810914+jleonar2@users.noreply.github.com> Co-authored-by: marcelpeterson <marcelpeterson@users.noreply.github.com> Co-authored-by: Yuan Li <atom.long@outlook.com> Co-authored-by: janeza2 <49841619+janeza2@users.noreply.github.com> Co-authored-by: Aris <arissunandar399@gmail.com> Co-authored-by: Isha Tiwari <156085572+ishatiwari21@users.noreply.github.com> Co-authored-by: Markus Hartung <mail@hartmark.se> Co-authored-by: Nguyen Minh <lop123thcs@gmail.com> Co-authored-by: Denis Kotsyuba <kocubads96@gmail.com> Co-authored-by: Wital <wital@example.com> Co-authored-by: Septianata Rizky Pratama <ian.rizkypratama@gmail.com> Co-authored-by: Shiva Vinodkumar <127319648+shiva24082@users.noreply.github.com> Co-authored-by: kooshapari <kooshapari@users.noreply.github.com> Co-authored-by: KooshaPari <kooshapari@gmail.com>
88 KiB
88 KiB
🚀 OmniRoute — The Free AI Gateway
Never stop coding. Connect every AI tool to 237 providers — 90+ free — through one endpoint.
Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.
RTK + Caveman compression saves 15–95% tokens. Never hit limits.
~1.6B documented free tokens/month — up to ~2.1B in your first month with signup credits — aggregated across the free tiers, plus a long tail of permanently-free, no-cap providers, and the compression above stretches every one further. (how we count →)
⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.
💬 Join the community
Questions, provider tips, roadmap & support → Discord · Telegram · WhatsApp 🌍 Global / 🇧🇷 Brasil
🧩 Available
🚀 Quick Start • 🎯 Combos • 🌐 Providers • 🔌 CLI & MCP • 🗜️ Compression • 🌍 Website
💥 The Promise • 🤔 Why • 🏆 What Sets Apart • 🤖 Compatible CLIs • 🖥️ Where It Runs • 🔒 Private • 🎬 In Action • 📚 Explore More • 📧 Support
🌐 In 42+ languages
| 🇺🇸 | 🇧🇷 | 🇵🇹 | 🇪🇸 | 🇫🇷 | 🇮🇹 | 🇩🇪 | 🇳🇱 | 🇷🇺 | 🇺🇦 | 🇵🇱 | 🇨🇿 | 🇸🇰 | 🇷🇴 | 🇭🇺 |
| 🇧🇬 | 🇩🇰 | 🇫🇮 | 🇳🇴 | 🇸🇪 | 🇨🇳 | 🇹🇼 | 🇯🇵 | 🇰🇷 | 🇹🇭 | 🇻🇳 | 🇮🇩 | 🇲🇾 | 🇵🇭 | |
| 🇮🇳 | 🇮🇳 | 🇮🇳 | 🇮🇳 | 🇮🇳 | 🇮🇳 | 🇧🇩 | 🇵🇰 | 🇮🇷 | 🇸🇦 | 🇮🇱 | 🇹🇷 | 🇦🇿 | 🇹🇿 |
💰 ~1.6B Free Tokens / Month
Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the documented free tiers of 40+ provider pools / 500+ models into one honest number and shows it live on the dashboard (
/dashboard/free-tiers).
- ~1.6B free tokens / month (steady) — and up to ~2.1B in your first month with signup credits.
- Pool-deduped, honest — we count each shared free pool once, so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (Counting every rate limit 24/7 would read ~10B; we don't publish that.)
- Plus the un-countable — permanently-free, no-token-cap providers (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen…) and a $10 OpenRouter top-up that unlocks +24M/mo, both surfaced separately so they never inflate the headline.
- Per-model breakdown, live used / remaining for the current month, and a transparent terms flag per provider.
Preview mockup — a real screenshot lands once the
/dashboard/free-tierspage is validated. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.
💥 The Promise
One endpoint. 237 providers. Never stop building — and let OmniRoute pick the cheapest one that works.
| 🚫 Never hit limits Auto-fallback across 237 providers in milliseconds. Quota out? Next provider takes over — zero downtime. |
💸 Save up to 95% tokens RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions). |
🆓 $0 to start 90+ providers with a free tier, 11 free forever (Kiro, Qoder, Pollinations, LongCat…). No card needed. |
| 🔌 Every tool works 24+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config. |
🧩 One endpoint OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at /v1 and it just works. |
🛡️ Production-grade Circuit breakers, TLS stealth, MCP (95 tools), A2A, memory, guardrails, evals. 21,000+ tests. |
🤔 Why OmniRoute?
Stop juggling 10 dashboards, dead API keys, and surprise bills.
| ❌ The daily pain | ✅ How OmniRoute fixes it |
|---|---|
| 📉 Subscription quota expires unused every month | Maximize subscriptions — track quota, use every token before reset |
| 🛑 Rate limits stop you mid-coding | 4-tier auto-fallback — Subscription → API → Cheap → Free, in milliseconds |
🔥 Tool outputs (git diff, grep, logs) burn tokens |
RTK + Caveman compression — save 15–95% eligible tokens per request |
| 💸 Expensive APIs ($20–50/mo per provider) | Cost-optimized routing — auto-route to the cheapest viable model |
| 🧰 Each AI tool wants its own setup | One endpoint, every tool, one dashboard |
| 🌍 AI blocked in your country | 3-level proxy + TLS fingerprint stealth — use AI from anywhere |
┌──────────────────────────────────────────────────────────┐
│ Your IDE / CLI (Claude Code, Cursor, Cline…) │
└─────────────────────────┬──────────────────────────────────┘
│ http://localhost:20128/v1
▼
┌──────────────────────────────────────────────────────────┐
│ OmniRoute — Smart Router │
│ RTK + Caveman compression · 17 routing strategies │
│ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │
└─────────────────────────┬──────────────────────────────────┘
┌─────────────┬────┴────────┬─────────────┐
▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4
SUBSCRIPTION API KEY CHEAP FREE
Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder,
Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations
quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on
🎯 Combos — The Flagship
A combo is a chain of models OmniRoute routes across automatically. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. This is what makes OmniRoute unbreakable. 🛡️
⚡ Zero-config — just use auto
No combo to create. Set your model to auto (or a variant) and OmniRoute builds a virtual combo from your connected providers, scored live:
| Model ID | What it optimizes for |
|---|---|
auto |
🎯 Balanced default (LKGP — sticks to your last good provider) |
auto/coding |
🧑💻 Quality-first weights for code generation |
auto/fast |
⚡ Lowest latency first |
auto/cheap |
💰 Cheapest per token first |
auto/offline |
🔋 Most quota / rate-limit headroom first |
auto/smart |
🔭 Quality-first + 10% exploration to discover better models |
🔀 Or build your own — 17 routing strategies
All 17 strategies — mix & match per combo step:
| # | Strategy | What it does |
|---|---|---|
| 1 | priority |
First-target ordered list — drain each before the next 🥇 |
| 2 | fill-first |
Fill each target's quota fully before moving on |
| 3 | weighted |
Weighted random by per-target weight |
| 4 | round-robin |
Cycle through targets in order |
| 5 | p2c |
Power-of-two-choices random load balancing |
| 6 | least-used |
Pick the target with the lowest current load |
| 7 | random |
Uniform random pick (deduplicated) |
| 8 | strict-random |
Random without de-duplicating repeats 🎲 |
| 9 | cost-optimized |
Minimize $ per request from live catalog pricing 💸 |
| 10 | headroom |
Pick the target with the most remaining quota |
| 11 | reset-window |
Prefer the target whose quota window resets soonest |
| 12 | reset-aware |
Rank by quota reset time — short windows first 📊 |
| 13 | context-relay |
Hand off context across targets for long conversations 🧠 |
| 14 | context-optimized |
Pick the best fit for the current context size |
| 15 | lkgp |
Last-Known-Good Path — sticky to the last successful target |
| 16 | auto |
9-factor live scoring across every connection 🤖 |
| 17 | fusion |
Fan out to a panel of models + a judge synthesizes one answer 🧬 |
The Auto-Combo engine scores every candidate on 9 factors (health, quota, cost, latency, success rate, freshness…) — see docs/routing/AUTO-COMBO.md.
⚖️ Quota-Share — split one subscription across a team ✨ NEW
Running several keys against the same upstream account (one Codex Pro plan, one Kimi key, one GLM Coding seat)? A burst on one key can burn the whole 5-hour / hourly quota and lock everyone else out. Quota-Share distributes a provider's time-based quota fairly across the keys in a pool — and it's work-conserving, so an idle member's slice is lent out instead of wasted.
| Knob | What it controls |
|---|---|
| ⚖️ Allocation weight | each key's slice of the pool — e.g. 50 / 30 / 20 |
| 📐 Dimensions | track % · requests · tokens · $, per 5h / 7d / per-model window |
| 🚦 Policy | hard (block over share) · soft (deprioritize) · burst (use idle headroom) |
| 🧱 Cap | absolute ceiling per key, independent of mode |
Pool "team-codex" · 1 Codex Pro account · 3 keys · 5-hour window
├─ alice weight 50 ██████████░░░░░░░░░░ ≤ 50% of the shared 5h quota
├─ bob weight 30 ██████░░░░░░░░░░░░░░ ≤ 30%
└─ ci-bot weight 20 ████░░░░░░░░░░░░░░░░ ≤ 20%
Generous mode (<50% pool used) → idle shares are lent out
Strict mode (≥50% pool used) → each key held to its fair share
Enforced in the hot path before the request leaves OmniRoute, with per-(key, model) caps + session stickiness for prompt-cache integrity. 📖 Quota Sharing Engine
🧱 Resilience is built in (3 independent layers)
| Layer | Scope | What it does |
|---|---|---|
| 🔌 Circuit breaker | whole provider | Stops hammering a provider that's failing upstream; auto-probes to recover |
| 💤 Connection cooldown | one account / key | Skips a rate-limited key while other keys keep serving |
| 🎯 Model lockout | provider + model | Quarantines just one quota-limited model, not the whole connection |
Combo: "always-on" Strategy: priority
1. cc/claude-opus-4-7 ← subscription (use it fully)
2. cx/gpt-5.5 ← second subscription
3. glm/glm-5.1 ← cheap backup ($0.5/1M)
4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails)
Result: 4 layers of fallback = zero downtime
📖 Auto-Combo Engine · Resilience Guide
🏆 What Sets OmniRoute Apart
| Feature | OmniRoute | Other routers |
|---|---|---|
| 🌐 Providers | 237 | 20–100 |
| 🆓 Free providers | 90+ (11 free forever) | 1–5 |
| 🔀 Routing strategies | 17 (priority, weighted, cost-optimized, context-relay, fusion…) | 1–3 |
| 🗜️ Token compression | RTK + Caveman stacked (15–95%) | None / 20–40% |
| 🧰 Built-in MCP server | 95 tools, 3 transports, 30 scopes | Rare |
| 🤝 A2A agent protocol | 6 skills, JSON-RPC 2.0 | None |
| 🧠 Memory (FTS5 + vector) | Yes | Rare |
| 🛡️ Guardrails (PII, injection, vision) | Yes | Rare |
| ☁️ Cloud agents | Codex, Cursor, Devin, Jules | None |
| 🥷 TLS fingerprint stealth | JA3/JA4 via wreq-js | None |
| 🖥️ Multi-platform | Web · Desktop · Termux · PWA | Web only |
| 🌍 i18n | 42 locales | 0–4 |
📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md
✨ What's New
Recent highlights from v3.8.20 → v3.8.43. Full history in
CHANGELOG.md.
- 🗜️ Compression hardening — a default-on inflation guard (discard the stacked result and send the verbatim original whenever compression would grow the prompt), completed Caveman rule packs for German / French / Japanese (dedup + ultra) plus a new Chinese (文言 / wényán) input pack with zh-vs-ja auto-detection, and RTK filters for Gradle & .NET (
dotnet) build output. → Compression - 💸 Honest flat-rate cost — subscription / coding-plan providers (ChatGPT Web, grok-web, the Minimax / Kimi / GLM / Alibaba Coding plans, Xiaomi MiMo…) now read $0 in cost analytics instead of an inflated per-token estimate, while budget / quota / routing keep estimating unchanged. → API Reference
- ⚖️ Quota-Share routing — a dedicated combo strategy that spreads load across accounts by available quota: Deficit-Round-Robin scheduling, per-connection
max_concurrentwith cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key, model) caps, session stickiness for prompt-cache integrity, and proactive saturation from upstream token-usage headers. → Resilience Guide - 🤖 One-command CLI/agent setup — a dedicated
setup-*command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode);omniroute launch/omniroute launch-codexare zero-config launchers. → CLI Integrations - 🛰️ Remote mode — drive a remote OmniRoute from any machine with scoped access tokens (
omniroute connect/omniroute contexts/omniroute tokens), plus anomniroute login antigravityhelper that runs Google "native/desktop" OAuth on your own machine and pastes a credential blob into a remote/VPS install (where the loopback redirect is unreachable). → Remote Mode - 🧭 Smarter auto-routing — OpenRouter-style
auto/<category>:<tier>combos (e.g.auto/coding:fast,auto/reasoning:pro), a Fusion strategy (fan out to a panel of models in parallel, then synthesize via a judge), task-aware routing (best-fit connection per task type), per-requestX-Route-Modeloverride, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, andweb_search-aware routing. → Auto-Combo - 🗜️ Pluggable compression — an async pipeline of 10 composable engines with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier Ultra, RTK, delegated Anthropic Context Editing, Output Styles (output-axis steering: terse-prose / less-code / terse-CJK), an adaptive context-budget dial (escalate only as far as needed to fit the context window), per-request
x-omniroute-compressioncontrol, an opt-in offline eval harness, one-click Headroom proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic compression playground (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in per-step fidelity gate that rejects a lossy engine before it degrades the prompt, a best-of-N candidate encoder (GCF vs TOON — keep whichever is shorter, with an A/B bytes/token table in the studio), CCR ranged/grep/stats retrieval (pull an exact byte/line slice or summary of a stored block instead of re-expanding it), a unified panel with named profiles + an active-profile selector, an opt-in per-engine pipeline circuit-breaker, an opt-in LLM-tier engine (a model pass for higher-ratio semantic compression), a read-lifecycle engine that collapses superseded file reads, usage-observed prefix freeze, a graduated CCR retrieval-feedback ramp, apreserveSystemPromptmode enum, and a drag-reorder pipeline editor in the studio. → Compression - 🕵️ Transparent MITM decrypt (TPROXY) — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → MITM/TPROXY
- 💸 Cost telemetry everywhere —
X-OmniRoute-*cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HITX-OmniRoute-Cost-Savedheader, and per-key USD spend quotas. → API Reference - 🧠 Memory you control — opt-in int8 vector quantization (Qdrant + sqlite-vec), opt-in typed memory decay (aged low-value memories fade on a per-type schedule), memory off by default, and a per-request
x-omniroute-no-memoryheader. → Memory - 🛡️ Security — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → Guardrails
- 🤝 More providers & agents — Cursor Cloud Agent (a 4th cloud agent), CodeBuddy CN (
copilot.tencent.com), a Google Flow video-generation provider, new gateways DGrid and Pioneer AI (Fastino Labs), inbound xAI Grok translators plus Grok Build (xAI) with an OAuth import-token flow, GPT-4 / GPT-4o-mini on the GitHub Copilot provider, multi-model Factory Droid, ZenMux Free (session-cookie free tier), Alibaba DashScope text-to-video (wan2.7-t2v), a refreshed 237-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech/transcription/music/video), a first-class Ollama local-provider card, the SenseNova free Token Plan (chat + text-to-image), and one-click account import from CLIProxyAPI (~/.cli-proxy-api/). → Providers - ⚡ Local performance & infra — a one-click local Redis launcher (
omniroute redis up, plus a dashboard Redis panel), one-click Cloudflare Workers and Deno Deploy relay deployers wired into the proxy pool, and an optional Bifrost Go sidecar that offloads the hottest relay path (BIFROST_BASE_URL, with automatic fallback to the TypeScript path on timeout) — now with a relay-backend selector (OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto) so the/v1/relayendpoint stays the stable surface while choosing the fastest backend internally. → Environment
🤖 Compatible CLIs & Coding Agents
One config —
http://localhost:20128/v1— and every AI IDE or CLI runs on free & low-cost models.
 Claude Code |
 Codex CLI |
 Cursor |
 Copilot |
 Continue |
|
 OpenCode |
 Kilo Code |
 Droid |
 OpenClaw |
 Kiro |
 Command |
＋ also works with · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · any OpenAI-compatible tool
📖 Per-tool setup for all 24+ tools → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @omniroute/opencode-provider
🌐 237 AI Providers — 90+ Free
The most complete catalog of any open-source router: 237 providers, 90+ with a free tier, 11 free forever.
🏢 Every major lab — through one endpoint
 OpenAI |
 Anthropic |
 Gemini |
 xAI Grok |
 DeepSeek |
 Mistral |
 Qwen |
 Meta Llama |
 Groq |
 NVIDIA |
 MiniMax |
 Cohere |
 Perplexity |
 HuggingFace |
 Together |
 Fireworks |
 Cloudflare |
 Baidu |
…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 Provider Reference
🆓 Free Forever — $0, no card
 AgentRouter GPT-5, Claude, Gemini $100 free credits |
 Qoder AI Kimi-K2, DeepSeek-R1 Unlimited FREE |
 Pollinations GPT-5, Claude, Llama 4 No key needed |
 LongCat LongCat-2.0 10M tokens one-time (KYC) 🔑 |
Cloudflare AI 50+ models 10K neurons/day |
NVIDIA NIM 129 models ~40 RPM free |
 Cerebras Qwen3 235B 1M tokens/day |
📖 Full machine-readable catalog → docs/reference/PROVIDER_REFERENCE.md
🖥️ Where OmniRoute Runs — Anywhere
Same app, your machine, your rules. From a global npm install to your phone via Termux.
| Platform | Install | Highlights |
|---|---|---|
| 📦 npm (global) | npm install -g omniroute |
One command, any OS |
| 🐳 Docker | docker run … diegosouzapw/omniroute |
Multi-arch AMD64 + ARM64 |
| 🖥️ Desktop (Electron) | npm run electron:build |
Native window + system tray — Windows / macOS / Linux |
| 💪 ARM | native arm64 |
Raspberry Pi, ARM servers, Apple Silicon |
| 📱 Android (Termux) | pkg install nodejs && npx -y omniroute |
Runs on your phone, 24/7, no root |
| 📲 PWA | "Add to Home Screen" | Fullscreen, offline, installable from browser |
| 🧩 OpenCode plugin | @omniroute/opencode-provider |
Native OpenCode integration |
| 🛠️ From source | npm install && npm run dev |
Hack on it, contribute |
📖 Docker Guide · Desktop · Termux · PWA · OpenCode
🔒 Private & Local-First
Your keys, your machine, your data. OmniRoute is a local proxy — it never phones home.
- 🏠 Runs 100% on your hardware — npm, Docker, desktop, or your phone. No OmniRoute cloud sits in the request path.
- 🔐 Credentials encrypted at rest — API keys & OAuth tokens sealed with AES-256-GCM.
- 🚫 Zero telemetry by default — your prompts go only to the providers you choose, nowhere else.
- 🛡️ Hardened gateway — API-key scoping, IP filtering, rate limits, prompt-injection guard, loopback-only process routes.
- 📜 MIT licensed & fully open-source — audit every line, self-host forever.
📖 Authorization · Guardrails · Compliance
🔌 Full CLI + A2A & MCP
OmniRoute isn't just a server — it's a full command-line cockpit with 80+ commands, plus open agent protocols so an AI agent can drive OmniRoute by itself.
⌨️ A real CLI (not just start)
omniroute # serve gateway + dashboard (port 20128)
omniroute chat # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup # guided first-run wizard
omniroute doctor # diagnose providers, ports, native deps
🛰️ Remote mode — run the CLI here, OmniRoute on a VPS
OmniRoute on a server? Drive it from your laptop with the same CLI. Log in once with a scoped access token; every command then targets the remote.
omniroute connect 192.168.0.15 # password → scoped token, saved as a context
omniroute models list # ← runs against the REMOTE server
omniroute configure codex # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read # mint narrower tokens for other machines
omniroute contexts use default # ← switch back to the local server
Tokens are scoped read / write / admin; process-spawning routes stay loopback-only.
📖 Remote Mode
providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …
🤝 Connect an agent — and it controls OmniRoute itself
Expose OmniRoute over MCP or A2A and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously.
| Protocol | Endpoint | Use it for |
|---|---|---|
| 🧰 MCP (stdio) | omniroute --mcp |
Plug into Claude Desktop, Cursor, any MCP client |
| 🌊 MCP (HTTP) | http://localhost:20128/api/mcp/stream |
Remote MCP — 95 tools, 30 scopes, full audit trail |
| 📡 MCP (SSE) | http://localhost:20128/api/mcp/sse |
Streaming MCP transport |
| 🤝 A2A | http://localhost:20128/.well-known/agent.json |
Agent-to-agent, JSON-RPC 2.0 + SSE, 6 skills |
# Give Claude Code the full OmniRoute toolset over MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
📖 MCP Server · A2A Server · Agent Protocols
🗜️ Save 15–95% Tokens — Automatically
Why use many tokens when few tokens do the trick? Every request passes through OmniRoute's compression pipeline transparently — no client changes. It's now a stack of 10 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman (⭐ 78K+), LLMLingua-2, and Troglodita (PT-BR).
🧱 The 10-engine stack
Engines run in pipeline order; each is independently toggleable and configurable per combo:
| # | Engine | What it does |
|---|---|---|
| 1 | Session-Dedup | Drops content repeated across turns (content-addressed, cross-turn) |
| 2 | CCR | Archives large blocks behind retrieve markers, fetched on demand |
| 3 | RTK | Smart tool-result filtering, dedup & truncation (command-aware) |
| 4 | Headroom | Lossless tabular compaction of homogeneous JSON arrays (~30%+) |
| 5 | Relevance | Extractive sentence scoring against the last user query |
| 6 | Caveman | Rule-based prose compression (~65–75% on output) |
| 7 | LLMLingua-2 | ML semantic pruning via MobileBERT ONNX — code-safe, async |
| 8 | Lite | Whitespace + image-URL trimming (latency-light baseline) |
| 9 | Aggressive | Summarization + progressive aging of old turns |
| 10 | Ultra | Heuristic token pruning with an optional small-model (SLM) tier |
Code blocks, URLs and structured data are always preserved byte-perfect. One-click presets combine the engines:
| Mode | Savings | Best for |
|---|---|---|
| 🪶 Lite | ~15% | Always-on safe default |
| 🪨 Standard (Caveman) | ~30% | Daily coding |
| ⚡ Aggressive | ~50% | Long tool-heavy sessions |
| 🔥 Ultra | ~75% | Maximum savings |
| 🧰 RTK | 60–90% | Shell/test/build/git output |
| 🔗 Stacked (RTK → Caveman) | 78–95% | Mixed prompts + tool logs |
Real example — Standard mode:
Before (69 tokens): "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."
After (19 tokens): "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
Same answer. 72% fewer tokens. Zero accuracy loss. ✅
PT-BR example — Troglodita mode:
Antes (42 tokens): "O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."
Depois (12 tokens): "Re-render: ref nova cada ciclo (objeto inline recriado). Usar
useMemo."Mesma resposta. ~70% menos tokens. Precisão técnica intacta. ✅
📖 How it works — pipeline, architecture & savings math
Client (10,000 tok) ──▶ OmniRoute Compression (10 engines) ──▶ Provider (~1,080 tok, up to 95% saved)
Default stacked combo runs RTK → Caveman. When both act on the same tool/context payload, savings compound:
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
Code blocks, URLs, JSON and structured data are always protected by the preservation engine.
🎚️ Beyond the engines — output styles, the adaptive dial & per-request control
The 10 engines above shrink what goes in. Three more layers shape how, when, and what comes out:
- 🪄 Output Styles (output-axis steering) — inject deterministic, cache-safe response-shaping instructions; combinable, each at
lite/full/ultraintensity. Adding a style is a one-line registry entry:- Terse prose — drop filler / articles / hedging; keep technical substance exact.
- Less code — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
- Terse CJK (文言) — classical-Chinese ultra-terse style (locale-gated to
zh).
- 🎯 Adaptive context-budget (the dial) — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to fit the model's context window. Policy:
reserve-output(default, model-aware) ·percentage·absolute. Mode:floor(guarantee fit) ·replace-autotrigger(your explicit choice wins) ·off(legacy threshold). - 🎛️ Where compression is decided (precedence, high → low) — per-request
x-omniroute-compressionheader › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in theX-OmniRoute-Compression: <mode>; source=<source>response header.
Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline eval harness (npm run eval:compression) scores fidelity vs. savings on a pinned corpus before you promote a change.
📖 COMPRESSION_GUIDE.md · RTK_COMPRESSION.md · COMPRESSION_ENGINES.md
⚡ Quick Start
1) Install & run
npm install -g omniroute
omniroute
Dashboard at http://localhost:20128 · API at http://localhost:20128/v1.
2) Connect a FREE provider (no signup)
Dashboard → Providers → connect Kiro AI (free Claude, ~50 credits/month per account) or OpenCode Free (no auth) → done.
3) Point your coding tool
Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto (zero-config smart routing — or any provider/model)
4) Verify it's working
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.
If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:
OpenAI catalog: http://localhost:20128/vscode/YOUR_KEY/
OpenAI models: http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat: http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat: http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags: http://localhost:20128/vscode/YOUR_KEY/api/tags
Use these only for clients that cannot attach Authorization: Bearer .... Header auth remains the preferred mode.
📦 More install methods — Docker, source, pnpm, Arch
🐳 Docker
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
🛠️ From source
cp .env.example .env && npm install
PORT=20128 npm run dev
📦 pnpm
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
🐧 Arch Linux (AUR)
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
🔧 Nix (Flake)
# Using Nix flakes
nix develop
npm run dev
# Or using devbox
devbox run npm run dev
📖 Docker Guide — Compose profiles, Caddy HTTPS, Cloudflare tunnels.
🦭 Podman
# 1. Build the image
podman build --target runner-base -t omniroute:base .
# 2. Fix data directory permissions for rootless Podman
mkdir -p data && podman unshare chown 1000:1000 ./data
# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d
📖 Podman Guide — Quadlet setup, podman-compose, Quadlet.
⚡ Faster / leaner install (skip the native build)
The native SQLite engine (better-sqlite3) is an optional dependency, so a global
install never blocks on compiling from source: it uses a prebuilt binary when one matches
your platform/Node, and otherwise falls back transparently to a pure-JS engine
(node:sqlite on Node 22+, else the bundled sql.js WASM) — no build tools required.
To skip the post-install native warm-up entirely (CI, headless, or slow machines):
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 also skips it
For the fastest installs prefer pnpm (content-addressed store + hard links — see above).
For a dashboard-free, headless runtime use the Docker base profile (above) or the
Termux guide. The CLI and the web dashboard are served by the
same process on one port, so there is no separate CLI-only package today.
🎬 OmniRoute in Action
 🇧🇷 Português Guia completo |
 🇺🇸 English Complete walkthrough |
 🇷🇺 Русский Полное руководство |
🎬 Made a video about OmniRoute? Open an issue or discussion with the link — we'll feature it here.
📚 Explore More
💰 Pricing at a glance & the $0 Free Stack (11 providers)
| Tier | Example | Cost |
|---|---|---|
| 💳 Subscription | Claude Code Pro / Codex / Copilot | $10–200/mo |
| 🔑 API Key (free tiers) | NVIDIA NIM, Cerebras, Groq | FREE |
| 💰 Cheap | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | pennies |
| 🆓 Free Forever | Kiro, Qoder, Qwen, Pollinations, LongCat | $0 |
The $0 Free Stack — combine into one unbreakable combo:
| Provider | Prefix | Free models | Quota |
|---|---|---|---|
| Kiro | kr/ |
Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 credits/mo |
| Qoder | if/ |
kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 | ♾️ Unlimited |
| Qwen | qw/ |
qwen3-coder-plus/flash/next | ♾️ Unlimited |
| Pollinations | pol/ |
GPT-5, Claude, Gemini, DeepSeek, Llama 4 | No key needed |
| LongCat | lc/ |
LongCat-2.0 | 10M one-time (KYC) |
| Cloudflare AI | cf/ |
50+ models | 10K neurons/day |
| NVIDIA NIM | nvidia/ |
129 models | ~40 RPM |
| Cerebras | cerebras/ |
Qwen3 235B, GPT-OSS 120B | 1M tok/day |
💡 The dashboard "cost" is a savings tracker, not a bill — OmniRoute never charges you. A "$290 total cost" using free models means $290 saved.
📖 Complete free directory → docs/reference/FREE_TIERS.md — 25+ providers, quotas, base URLs.
🎯 Use Cases — ready-made combo playbooks
$0 forever:
1. kr/claude-sonnet-4.5 (Kiro — ~50 credits/mo per acct)
2. if/kimi-k2-thinking (Qoder — unlimited)
3. pol/gpt-5 (Pollinations — no key)
4. lc/LongCat-2.0 (10M one-time backup, KYC)
Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
24/7 no interruptions: chain 2 subscriptions → cheap → free for 5 layers of fallback.
Blocked region: free providers + global/per-provider proxy → access AI from any country.
Max savings: subscription + cheap backup + ultra compression (~75%) → ~$150–300/mo saved for heavy users.
🌍 Bypass geo-blocks — 3-level proxy + stealth
🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 In a blocked region? OmniRoute's 3-level proxy (Global / Per-Provider / Per-Connection) proxies API requests, OAuth flows, connection tests, token refresh & model sync.
- Protocols: HTTP/HTTPS, SOCKS5, authenticated proxies
- 🆓 1proxy marketplace — hundreds of free validated proxies, quality scores, auto-rotation
- Anti-detection — TLS fingerprint spoofing (
wreq-js), CLI fingerprint matching, proxy IP preservation
✨ Full feature list — 30+ capabilities (memory, evals, observability)
Routing: 17 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection.
Compatibility: OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0.
Protocols: MCP (95 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Cursor, Devin, Jules).
Plugins: custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD).
Embedded services: one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter).
Quality & Ops: built-in Evals (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit.
AI Agent Skills: drop-in markdown manifests — point any agent at a skills/*/SKILL.md manifest. 43 skills available.
📖 MCP Server · A2A Server · Resilience Guide · Features Gallery
📖 Setup, env vars & FAQ
| Env var | Default | Purpose |
|---|---|---|
PORT |
20128 |
API + dashboard port |
REQUIRE_API_KEY |
false |
Require API key for all requests |
DATA_DIR |
~/.omniroute |
Database & config storage |
Will I be charged by OmniRoute? No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system. Are FREE providers really unlimited? Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0. Will compression hurt quality? No — it only compresses the input; code, URLs, JSON are always protected. Does it work where AI is blocked? Yes — 3-level proxy + 1proxy marketplace reach all 237 providers.
🐛 Troubleshooting
| Problem | Quick fix |
|---|---|
| "Language model did not provide messages" | Provider quota exhausted → use a combo fallback |
| Rate limiting (429) | Add fallback: cc/claude → glm/glm-4.7 → if/kimi-k2-thinking |
| OAuth token expired | Auto-refreshed; if stuck, delete + re-auth in Providers |
unsupported_country_region_territory |
Configure proxy in Settings → Proxy |
| Docker SQLite locks | Use --stop-timeout 40 for clean WAL checkpoint |
| Node runtime errors | Use Node >=22.0.0 <23 or >=24.0.0 <27 |
🐛 Reporting a bug? Run npm run system-info and attach system-info.txt. 📖 docs/guides/TROUBLESHOOTING.md
📸 Dashboard screenshots
| Page | Screenshot | Page | Screenshot |
|---|---|---|---|
| Providers |  |
Combos |  |
| Analytics |  |
Health |  |
| Translator |  |
Settings |  |
| CLI Tools |  |
Usage Logs |  |
📧 Support & Community
💬 Chat with the community — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the top of this README.
- 🌍 Website: omniroute.online
- 🐙 GitHub: github.com/diegosouzapw/OmniRoute
- 🐛 Issues: report a bug (attach
npm run system-infooutput) - 🤝 Contributing: see CONTRIBUTING.md or pick a
good first issue
🛠️ Tech Stack
- Runtime: Node.js 22.x or 24.x LTS (24 LTS recommended) —
>=22.0.0 <23 || >=24.0.0 <27 - Language: TypeScript 6.0 — 100% TypeScript across
src/andopen-sse/(zeroanyin core modules since v2.0) - Framework: Next.js 16 + React 19 + Tailwind CSS 4
- Database: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
- Schemas: Zod (MCP tool I/O validation, API contracts)
- Protocols: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
- Streaming: Server-Sent Events (SSE) + WebSocket bridge (
/v1/ws) - Auth: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
- Testing: Node.js test runner + Vitest (21,000+ test cases across 2,586 files — unit, integration, E2E, security, ecosystem)
- Platforms: Desktop (Electron), Android (Termux), PWA (any browser)
- CI/CD: GitHub Actions (auto npm publish + Docker Hub on release)
- Website: omniroute.online
- Package: npmjs.com/package/omniroute
- Docker: hub.docker.com/r/diegosouzapw/omniroute
- Resilience: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
📖 Documentation
📘 Getting Started
| Document | Description |
|---|---|
| User Guide | Providers, combos, CLI integration, deployment |
| Setup Guide | Full install methods, CLI tool configs, protocol setup, timeout tuning |
| CLI Tools Guide | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
| Remote Mode | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens |
| Claude Code Config | Point Claude Code at OmniRoute (local/remote) with launch + per-model profiles |
| Quick Start | 3-step install → connect → configure |
🔧 Operations & Deployment
| Document | Description |
|---|---|
| Docker Guide | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
| Podman Guide | Quadlet systemd integration, podman-compose, SELinux |
| VM Deployment | Complete guide: VM + nginx + Cloudflare setup |
| Fly.io Deployment | Deploy to Fly.io with persistent storage |
| Termux Guide | Run OmniRoute on Android via Termux |
| PWA Guide | Progressive Web App install, caching, architecture |
| Uninstall Guide | Clean removal for all install methods |
| Environment Config | Complete .env variables and references |
🧠 Features & Architecture
| Document | Description |
|---|---|
| Architecture | System architecture, data flow, and internals |
| Compression Guide | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |
| RTK Compression | Command-output compression, filters, trust, verify, raw-output recovery |
| Compression Engines | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |
| Compression Rules Format | JSON rule-pack schemas for Caveman and RTK filters |
| Compression Language Packs | Language detection and Caveman rule-pack authoring |
| Resilience Guide | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |
| Auto-Combo Engine | 9-factor scoring, mode packs, self-healing |
| Proxy Guide | 3-level proxy system, 1proxy marketplace, registry CRUD |
| Free Tiers | 25+ free API providers consolidated directory |
| Features Gallery | Visual dashboard tour with screenshots |
| Codebase Documentation | Beginner-friendly codebase walkthrough |
🤖 Protocols & APIs
| Document | Description |
|---|---|
| API Reference | All endpoints with examples |
| OpenAPI Spec | OpenAPI 3.0 specification |
| MCP Server | 95 MCP tools, IDE configs, Python/TS/Go clients |
| MCP Server Guide | MCP installation, transports, and tool reference |
| A2A Server | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
| A2A Server Guide | A2A agent card, tasks, skills, and streaming |
📋 Project & Quality
| Document | Description |
|---|---|
| Contributing | Development setup and guidelines |
| Changelog | Full per-version release history |
| Security Policy | Vulnerability reporting and security practices |
| i18n Guide | 40+ language support, translation workflow, RTL |
| Release Checklist | Pre-release validation steps |
| Coverage Plan | Test coverage strategy and 21,000+ test suite |
⭐ Top Contributors
OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. Thank you.
 oyi77 🥇 189 commits • +155K lines Analytics engine, SQL aggregations, proxy marketplace, test coverage |
 Chris Staley 🥈 70 commits • +5.7K lines SSE stream hardening, Responses API, Gemini pagination, test regression fixes |
 zenobit 🥉 62 commits • +24K lines CI/CD pipeline, i18n for 33 languages, Void Linux package, platform fixes |
 R.D. & Randi 🏅 108 commits • +30K lines Endpoints page, tunnel integrations, Docker workflows, A2A status, compression UI |
 benzntech 🏅 22 commits • +7.5K lines Electron desktop app, auto-updater, release build workflows, cross-platform CI |
 herjarsa 🏅 21 commits • +6K lines Zero-latency combos, vision-bridge auto-routing, catalog context-length, resilience 429 hints |
🙏 These contributors' features, bug fixes, and infrastructure improvements are a core part of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.
👥 280+ Contributors
How to Contribute
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
See CONTRIBUTING.md for detailed guidelines.
Releasing a New Version
# Create a release — npm publish happens automatically
gh release create v3.8.2 --title "v3.8.2" --generate-notes
📊 Stars
🌍 StarMapper
🙏 Acknowledgments
OmniRoute stands on the shoulders of giants. It started as a fork of 9router and a TypeScript port of the Go project CLIProxyAPI — and from there, every subsystem below was inspired by an open-source project that got there first. Each one shaped a concrete piece of OmniRoute. This is our thank-you to all of them. 🙏
⭐ star counts as of June 2026 — go give these projects a star.
🧬 Lineage & gateway
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| 9router · decolua | 19.0k | The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. |
| CLIProxyAPI · router-for-me | 38.8k | The Go implementation that inspired this JavaScript / TypeScript port. |
| LiteLLM · BerriAI | 52.1k | The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing. |
🗜️ Context & token compression — engines
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| Caveman · JuliusBrussee | 78.2k | The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. |
| RTK – Rust Token Killer · rtk-ai | 67.3k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. |
| headroom · headroomlabs-ai | 54.5k | Reversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern. |
| LLMLingua · Microsoft | 6.4k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine. |
| llmlingua-2-js · atjsh | 28 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. |
| Troglodita · Lenine Júnior | 16 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. |
| ponytail · DietrichGebert | 68.8k | The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts generated code (the output-axis sibling to Caveman's terse prose). |
🧩 Compact formats, token research & code-aware tooling
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| TOON · toon-format | 24.7k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. |
| GCF – Graph Compact Format · Blackwell Systems | 14 | Schema-aware "JSON for LLMs" notation — co-inspired our lossless homogeneous-array compaction with [N rows] markers. |
| token-optimizer-mcp · ooples | 421 | Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine. |
| token-savior · Mibayy | 1.0k | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. |
| token-saver · ppgranger | 110 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. |
| token-optimizer · alexgreensh | 1.5k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. |
| TokenMizer · Shweta-Mishra-ai | 2 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. |
| OmniCompress · jessefreitas | 2 | Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our headroom/ccr/session-dedup engine design and the cache-stable "compressed form is position-independent" invariant. |
| mcp-compressor · Atlassian Labs | 89 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. |
| RepoMapper · pdavis68 | 181 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. |
| quiet-shell-mcp · mrsimpson | 4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. |
| ts-morph · David Sherret | 6.1k | TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals. |
🧠 Memory & RAG
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| Mem0 · mem0ai | 59.8k | Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. |
| Letta (MemGPT) · letta-ai | 23.6k | Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. |
| WFGY · onestardao | 1.8k | The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide. |
🛰️ Traffic inspection, MITM & transparent proxy
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| llm-interceptor · chouzz | 48 | MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT). |
| ProxyBridge · InterceptSuite | 5.3k | Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture. |
📚 Model data, observability & UI
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| models.dev · SST / OpenCode | 5.6k | Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. |
| React Flow / xyflow · xyflow | 37.4k | The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. |
| LangGraph · LangChain | 36.1k | LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. |
| Langfuse · Langfuse | 30.1k | Its trace → span → generation observability model shaped our Compression Studio waterfall. |
| Kiali · Kiali | 3.6k | Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. |
| lobe-icons · LobeHub | 2.2k | AI/LLM brand logos that render the provider icons across our dashboard. |
🛡️ Security
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| awesome-secure-defaults · tldrsec | 708 | A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). |
❤️ Support
OmniRoute is free and open source, built and maintained in the open. If it saves you time or money, consider supporting development:
- ⭐ Star the repo — it genuinely helps visibility
- 💖 GitHub Sponsors — fund ongoing maintenance and new providers
- 🐛 Report bugs and share feedback in Discussions
📄 License
MIT License - see LICENSE for details.
⬆ Back to top · Built with ❤️ for the open-source AI community.
OmniRoute v3.8.43 · Node ≥22.0.0 · MIT License · omniroute.online