diff --git a/.env.example b/.env.example
index a2156902a6..c1a1f06e67 100644
--- a/.env.example
+++ b/.env.example
@@ -1027,6 +1027,16 @@ PROVIDER_LIMITS_SYNC_SPACING_MS=1500
# Used by: open-sse/services/compression/engines/rtk/filterLoader.ts. Default: 0.
#OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=0
+# Maximum concurrent synchronous compression workers. Excess jobs wait FIFO.
+# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 2.
+#OMNI_COMPRESSION_WORKERS=2
+# Per-job worker timeout (ms). A timed-out worker is terminated and the request fails open.
+# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 120000.
+#OMNI_COMPRESSION_WORKER_TIMEOUT_MS=120000
+# Terminate idle compression workers after this many milliseconds.
+# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 60000.
+#OMNI_COMPRESSION_WORKER_IDLE_MS=60000
+
# T02 stacked-pipeline engine circuit-breaker (OPT-IN, default off). When enabled, a compression
# engine that throws repeatedly across requests is skipped (fail-open) for a cooldown.
# Used by: open-sse/services/compression/pipelineEngineBreaker.ts.
@@ -2011,6 +2021,9 @@ APP_LOG_TO_FILE=true
# CLIPROXYAPI_HOST=127.0.0.1
# CLIPROXYAPI_PORT=5544
# CLIPROXYAPI_CONFIG_DIR=~/.cli-proxy-api
+# Management key for an externally managed instance. Embedded instances use
+# OmniRoute's encrypted service key.
+# CLIPROXYAPI_MANAGEMENT_KEY=
# ── Mux embedded service ──
# Override the port where the embedded Mux (coder/mux) agent-orchestration
@@ -2420,10 +2433,10 @@ APP_LOG_TO_FILE=true
# test suite must NEVER mutate the OS trust store (a fake test PEM installed via
# update-ca-certificates broke all system TLS on a persistent runner, 2026-07-05).
# OMNIROUTE_SKIP_SYSTEM_TRUST=1
-# check-changelog-integrity.mjs (anti CHANGELOG-eat gate): explicit base ref
-# override, and the justified-removal escape hatch for intentional bullet removals.
+# check-changelog-integrity.mjs (anti CHANGELOG-eat gate): explicit base ref override.
+# Intentional transformations require an exact reviewed entry in
+# config/release/changelog-reconciliations.json; there is no runtime bypass.
# CHANGELOG_BASE_REF=origin/release/v0.0.0
-# ALLOW_CHANGELOG_REMOVALS=1
# ── Remote audio provider nodes ──
# Used by: src/app/api/v1/_shared/audioProviderNodes.ts — lets the /v1/audio/*
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05d3989c59..3d2349f8a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -180,6 +180,7 @@ _Living section — regenerated 2026-08-12 from all cycle commits (cycle open `e
### 🐛 Bug Fixes
+- **fix(build):** every route no longer answers HTTP 500 on artifacts built from the release tip ([#11343](https://github.com/diegosouzapw/OmniRoute/issues/11343)) — `next.config.mjs` aliased `better-sqlite3` to its build-time stub **unconditionally**, on the premise that `serverExternalPackages` still won at runtime. It does not: a Turbopack `resolveAlias` rewrites the request *before* the externals check, so the request stopped matching the `better-sqlite3` external entry and the stub was baked into the shipped bundle. The sync driver then failed with `r(...) is not a constructor`, fell through `node:sqlite` and sql.js, and the instrumentation hook aborted at boot. Same failure shape as [#6344](https://github.com/diegosouzapw/OmniRoute/issues/6344), so it gets the same treatment: the alias is opt-in via `OMNIROUTE_BETTER_SQLITE3_STUB=1` through the shared `scripts/build/better-sqlite3-stub-flag.mjs` helper — set it only on a build host that actually hits the SIGABRT build-worker teardown ([#10060](https://github.com/diegosouzapw/OmniRoute/issues/10060)); default builds externalize the real native addon. Regression guards: `tests/unit/better-sqlite3-stub-alias-11343.test.mjs` (5) and the env matrix in `tests/unit/next-config.test.ts`.
- **security(search)**: block SSRF via `/v1/search` `provider_options.baseUrl` for the Firecrawl search provider — the client-controlled override is now validated as a public URL before it is used to build the server-side fetch target, so a caller with a valid API key can no longer redirect search requests at loopback, RFC1918, or cloud-metadata hosts — thanks @zmf963
- **providers**: honor `PATCH /api/providers/[id]` so `omniroute providers rotate` stops 405ing (the OpenAPI spec and CLI already use PATCH) (PR #10366)
- **cli**: route provider test commands through configured connection test endpoints (#10570)
diff --git a/Dockerfile b/Dockerfile
index 848d25c109..a35f57e280 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -181,10 +181,23 @@ ENV NODE_OPTIONS="--max-old-space-size=${OMNIROUTE_BUILD_MEMORY_MB}"
# workers for page-data collection (31 on a 32-core builder); on memory-tight
# hosts 31 workers + webpack's multi-GB heap blow past RAM and a worker dies
# with SIGSEGV at teardown ("worker exited with code: null and signal: SIGSEGV"),
-# silently leaving no standalone bundle. Next derives the default worker count
-# from CIRCLE_NODE_TOTAL (workers = N-1), so N=8 → 7 workers: fast enough while
-# fitting comfortably in RAM on any host. (#10060)
-ENV CIRCLE_NODE_TOTAL=8
+# silently leaving no standalone bundle. Next derives the worker count from
+# CIRCLE_NODE_TOTAL (workers = N-1). (#10060)
+#
+# Lowered 8 → 3 (7 workers → 2). Every page-data worker inherits NODE_OPTIONS
+# above, so the ceiling is per PROCESS, not per build: 7 workers on a 16 GB
+# GitHub runner (ubuntu-24.04 / ubuntu-24.04-arm, 4 vCPU) exhausted the host and
+# buildkit failed the whole step with `ResourceExhausted: ... cannot allocate
+# memory`. The compile phase always finished ("✓ Compiled successfully in
+# 4.2min"); the kernel killed the build right after "Collecting page data using
+# 7 workers". It was intermittent for a while and went 100% on 2026-08-22, which
+# is what a threshold being crossed by ordinary codebase growth looks like.
+# tests/unit/docker-build-memory-budget.test.ts does the arithmetic and fails if
+# either knob is raised past what a 16 GB runner holds. 2 workers also stops
+# oversubscribing the runner's 4 vCPU, which 7 did. Override for a big builder:
+# `--build-arg OMNIROUTE_BUILD_WORKERS=8`.
+ARG OMNIROUTE_BUILD_WORKERS=3
+ENV CIRCLE_NODE_TOTAL=${OMNIROUTE_BUILD_WORKERS}
COPY . ./
RUN --mount=type=cache,id=s/92ca8a61-c1ba-421f-a389-d48ac7258c2d-next-cache,target=/app/.build/next/cache \
diff --git a/README.md b/README.md
index 373c1ef558..9a8e877f16 100644
--- a/README.md
+++ b/README.md
@@ -17,9 +17,9 @@
-> 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 **42 provider pools / 495 models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`).
+> Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute catalogs **455 free-tier entries across 40 recurring pool keys** and computes the token headline from the **20 pools with a published positive monthly budget**, deduplicated by shared pool. The result stays visible on the dashboard (`/dashboard/free-tiers`).
-
+
> Animated summary of the live `/dashboard/free-tiers` page. Full methodology (pool dedupe, credit tiers, provider terms): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
@@ -61,14 +61,14 @@
@@ -318,7 +318,7 @@ curl http://localhost:20128/v1/chat/completions \
-> 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.** 🛡️
+> A **combo** is a chain of models OmniRoute routes across **automatically**. If quota runs out, a provider fails, or costs spike, the combo can move to the next eligible healthy model. 🛡️
### ⚡ Zero-config — just use `auto`
@@ -429,7 +429,7 @@ All **19** strategies — mix & match per combo step:
17
auto
-
14-factor live scoring across every connection 🤖
+
15-factor live scoring across every connection 🤖
18
@@ -443,7 +443,7 @@ All **19** strategies — mix & match per combo step:
-The Auto-Combo engine scores every candidate on **14 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).
+The Auto-Combo engine scores every candidate on **15 factors** (health, quota, cost, latency, task fit, quality, session availability…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).
##
@@ -461,7 +461,7 @@ All **19** strategies — mix & match per combo step:
-
+📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)
@@ -517,9 +517,9 @@ Pix copia-e-cola:
## 📡 OmniRoute Radar
-The main free-tier headline remains **~1.53B tokens/month** from the documented,
+The main free-tier headline remains **~1.51B tokens/month** from the documented,
pool-deduplicated catalog above. Temporary provider signup credits can separately lift the first
-month to **~2.15B**. Radar is an optional, signed catalog overlay for people who want fresher
+month to **~2.13B**. Radar is an optional, signed catalog overlay for people who want fresher
free-model availability between OmniRoute releases; the community catalog and every existing free
feature remain free.
@@ -548,7 +548,7 @@ the current catalog at **[radar.omniroute.online/planos](https://radar.omniroute
- **🗜️ Compression hardening** — default-on inflation guard, Caveman packs for DE / FR / JA + Chinese (wényán), RTK filters for Gradle & .NET. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
- **💸 Honest flat-rate cost** — subscription / coding-plan providers read **$0** in cost analytics; budget, quota & routing keep estimating. → [API Reference](docs/reference/API_REFERENCE.md)
- **⚖️ Quota-Share routing** — split a shared account's quota fairly across pooled keys, work-conserving so idle slices are lent out. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
-- **🤖 One-command CLI/agent setup** — `setup-*` configures 12+ coding tools; `omniroute run` launches 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI) with zero config written; `omniroute configure` is an interactive provider+model picker with per-context favorites. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
+- **🤖 One-command CLI/agent setup** — 12 registered `setup-*` commands; `omniroute run` launches 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` supports 9 targets with an interactive provider+model picker and per-context favorites. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Remote mode** — drive a remote OmniRoute with scoped tokens (`connect` / `contexts` / `tokens`) + an `antigravity` OAuth helper for VPS installs. → [Remote Mode](docs/guides/REMOTE-MODE.md)
- **🧭 Smarter auto-routing** — `auto/:` combos, **Fusion** (model panel + judge), task-aware routing, per-request model / mode / USD-budget overrides. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Pluggable compression** — 12 composable engines + Compression Studios: LLMLingua-2, two-tier Ultra, omniglyph, per-step fidelity gate, GCF v3.2, drag-reorder editor. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
@@ -642,11 +642,11 @@ of your shell history. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
-## 🌐 349 AI Providers — 90+ Free
+## 🌐 350 AI Providers — 154 Catalog-Marked Free
-> The most complete catalog of any open-source router: **350 providers**, **90+ with a free tier**, **56 free forever**.
+> **350 registered providers** across the canonical chat, media, search, local, cloud-agent and system collections, including **154 carrying `hasFree: true` discovery metadata**. The chat model registry covers **268 providers / 2,566 distinct provider-model pairs / 1,312 raw model IDs**; the separate free-budget catalog has **455 per-model rows**, **40 recurring pools** and **56 recurring/keyless free-forever providers**. These are different denominators by design; definitions and pool-deduped calculations live in the [Provider Reference](docs/reference/PROVIDER_REFERENCE.md) and [Free Tiers](docs/reference/FREE_TIERS.md).
@@ -679,7 +679,7 @@ of your shell history. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
-…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)
+…and 330+ more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)
@@ -769,7 +769,7 @@ From inside the editor: open the **Extensions** view, search **"OmniRoute"**, cl
@@ -846,7 +846,7 @@ claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp
### 📖 How it works — pipeline, architecture & savings math
-
+
Default stacked combo runs `RTK → Caveman`. When both act on the same tool/context payload, savings compound:
@@ -1013,6 +1013,7 @@ Full table: [Docker Guide — runtime RAM](docs/guides/DOCKER_GUIDE.md#runtime-r
**🥟 Bun**
Standard `bun install` and global installation (`bun install -g omniroute`) are supported via Bun runtime detection:
+
- **Built-in `bun:sqlite`**: OmniRoute uses Bun's built-in `bun:sqlite` driver when running under Bun, falling back to `better-sqlite3` on Node.js or `sql.js`.
- **Automatic Webpack bundler selection**: Development (`bun run dev`) and production builds (`bun run build`) automatically detect Bun and disable Turbopack in favor of Webpack to prevent native V8 binding incompatibilities.
- **Dedicated Bun Dockerfile**: Multi-stage `Dockerfile.bun` for native Bun production deployments (`docker build -f Dockerfile.bun -t omniroute:bun .`).
@@ -1105,7 +1106,7 @@ same process on one port, so there is no separate CLI-only package today.
@@ -1114,52 +1115,52 @@ same process on one port, so there is no separate CLI-only package today.
🎬 #1 — Instagram
- nick_saraev — 1,628,910 views
+ nick_saraev — 3,042,474 views
+
+
Test coverage strategy for 39,000+ static test declarations across 5,100+ tracked test files
@@ -1302,93 +1303,123 @@ Métricas de validação: 1002 vídeos rastreados · 7,069,190 visualizações c
> 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.**
+### External contributors by merged pull requests
+
+
+
+Frozen at live release/v3.8.50 tip dafb4ae808, with merges through 2026-08-24 05:26:03 UTC. The paginated GitHub GraphQL census contains 5,911 merged PRs: 2,707 by the repository owner, 179 by Dependabot, and 3,025 external PRs from 535 distinct contributors. “Changed lines” is GitHub additions + deletions and includes generated files, lockfiles, catalogs, translations and documentation; it is churn, not authored LOC. Ties at the cutoff are retained.
+
+### GitHub-attributed commits
+
+Rechecked at 2026-08-24 06:14:31 UTC: GitHub-attributed commits reported by the repository Contributors API for the release/v3.8.50 default branch. The API returned 525 identities (415 users, 2 bots, 108 anonymous); this table excludes the maintainer, bots and anonymous identities and retains competition ties. It is distinct from both the merged-PR ranking above and the 639-person Git-metadata census below.
+
> 🙏 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.
@@ -1405,25 +1436,48 @@ A heartfelt thank-you to the people who fund OmniRoute out of their own pocket
… and others who prefer to stay private 💛
+Public GitHub Sponsors revalidated on 2026-08-24. GitHub's activeOnly status determines the active labels above; previously disclosed public one-time supporters remain thanked, and private sponsors remain anonymous.
+
💖 Become a sponsor → — every dollar keeps OmniRoute free and independent.
@@ -1432,11 +1486,13 @@ A heartfelt thank-you to the people who fund OmniRoute out of their own pocket
-## 👥 320+ Contributors
+## 👥 600+ Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+
+Audited on 2026-08-24 at frozen base ac02c5b42f and rechecked at live release/v3.8.50 tip dafb4ae808: 639 normalized human Git identities — 407 appear as commit authors (including the maintainer) and 232 only in explicit Co-authored-by trailers. The census normalizes GitHub noreply handles, excludes 26 bot/agent/service/placeholder identities, and does not merge ordinary email addresses merely because their display names match.
### How to Contribute
@@ -1453,7 +1509,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
```bash
# Create a release — npm publish happens automatically
-gh release create v3.8.2 --title "v3.8.2" --generate-notes
+VERSION=x.y.z
+gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes
```
@@ -1495,88 +1552,108 @@ gh release create v3.8.2 --title "v3.8.2" --generate-notes
OmniRoute stands on the shoulders of giants. It started as a fork of **[9router](https://github.com/decolua/9router)** and a TypeScript port of the Go project **[CLIProxyAPI](https://github.com/router-for-me/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 July 2026 — go give these projects a star.
+> ⭐ star counts verified from GitHub's REST API on August 24, 2026 — go give these projects a star. Counts are an exact dated snapshot and will naturally change.
### 🧬 Lineage & gateway
Its Grok model mappings, fake-TypeError Statsig generator, request and device defaults, and NDJSON response processor were materially adapted into OmniRoute's Grok Web executor.
The principal transitive code source behind grok2api-merged; its model, header, payload, Statsig and processor implementations are preserved in the Grok Web lineage.
The underlying MIT source for Grok payload and device defaults, the Statsig generator, and the result.response processor carried through TQZHR and grok2api-merged.
A transitive source credited by grok2api-merged for its proxy-pool layer; OmniRoute preserves that lineage notice but does not claim a proxy-pool port in its bounded Grok Web executor.
The original Grok Web implementation consulted its HTTP/browser upstream design; its direct HTTP path derives from GrokProxy, so no independent code port is claimed.
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.
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.
First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), with later numeric-domain and count-mismatch correctness fixes.
MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking. The upstream's complete license text is still under provenance review.
Identified the Grok Build quota surface; OmniRoute then verified and corrected the live wire format independently.
## 📄 License
@@ -1589,7 +1666,7 @@ MIT License - see [LICENSE](LICENSE) for details.
**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community.
-OmniRoute v3.8.49 · Node ≥22.22.2 · MIT License · omniroute.online
+OmniRoute v3.8.50 · Node ≥22.22.2 · MIT License · omniroute.online
diff --git a/bin/cli/commands/setup-claude.mjs b/bin/cli/commands/setup-claude.mjs
index 6567824490..d6c8fad593 100644
--- a/bin/cli/commands/setup-claude.mjs
+++ b/bin/cli/commands/setup-claude.mjs
@@ -169,7 +169,8 @@ export async function runSetupClaudeCommand(opts = {}) {
let detail = `HTTP ${res.status}`;
try {
const errorBody = await res.json();
- const serverMsg = errorBody?.error?.message || errorBody?.error || errorBody?.message || "";
+ const serverMsg =
+ errorBody?.error?.message || errorBody?.error || errorBody?.message || "";
if (serverMsg) detail += ` — ${serverMsg}`;
} catch {}
throw new Error(detail);
diff --git a/bin/cli/commands/update.mjs b/bin/cli/commands/update.mjs
index afdaff68e4..c1722f4bcb 100644
--- a/bin/cli/commands/update.mjs
+++ b/bin/cli/commands/update.mjs
@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { t } from "../i18n.mjs";
+import { npmBin, npmExecOptions } from "../npm-exec.mjs";
const execFileAsync = promisify(execFile);
@@ -31,9 +32,13 @@ export async function getCurrentVersion() {
// they were already on the latest version (#4376). `execFn` is injectable for tests.
export async function getLatestVersion(execFn = execFileAsync) {
try {
- const { stdout } = await execFn("npm", ["view", "omniroute", "version", "--prefer-online"], {
- timeout: 15000,
- });
+ // argv is all literals, so enabling the shell on win32 cannot splice a
+ // runtime value into the command line (Hard Rule #13).
+ const { stdout } = await execFn(
+ npmBin(),
+ ["view", "omniroute", "version", "--prefer-online"],
+ npmExecOptions(process.platform, { timeoutMs: 15000 })
+ );
return stdout.trim();
} catch {
return null;
@@ -114,9 +119,11 @@ export async function runUpdateCommand(opts = {}) {
if (showChangelog) {
try {
- const { stdout } = await execFileAsync("npm", ["view", "omniroute", "changelog"], {
- timeout: 10000,
- });
+ const { stdout } = await execFileAsync(
+ npmBin(),
+ ["view", "omniroute", "changelog"],
+ npmExecOptions(process.platform, { timeoutMs: 15000 })
+ );
if (stdout.trim()) {
console.log(stdout.trim());
} else {
diff --git a/bin/cli/locales/pt-BR.json b/bin/cli/locales/pt-BR.json
index c821bf976c..eec1b42a0e 100644
--- a/bin/cli/locales/pt-BR.json
+++ b/bin/cli/locales/pt-BR.json
@@ -26,7 +26,8 @@
"testFailed": "Teste do provedor falhou: {error}",
"loginEnabled": "Login: habilitado (senha atualizada)",
"loginDisabled": "Login: desabilitado",
- "providerInfo": "Provedor: {info}"
+ "providerInfo": "Provedor: {info}",
+ "opencode": "Instala e configura o plugin @omniroute/opencode-plugin incluído para o OpenCode"
},
"doctor": {
"title": "OmniRoute Doctor",
@@ -254,7 +255,9 @@
"no_recovery": "Desabilitar reinício automático em crash (modo debug)",
"max_restarts": "Máximo de reinícios em 30s antes de desistir (padrão: 2)",
"tray": "Mostrar ícone na bandeja do sistema (apenas desktop, opt-in)",
- "no_tray": "Desabilitar ícone na bandeja do sistema"
+ "no_tray": "Desabilitar ícone na bandeja do sistema",
+ "tls_cert": "Caminho para um certificado TLS (PEM) para servir HTTPS (também OMNIROUTE_TLS_CERT)",
+ "tls_key": "Caminho para a chave privada TLS (PEM) para servir HTTPS (também OMNIROUTE_TLS_KEY)"
},
"backup": {
"title": "Backup",
diff --git a/bin/cli/locales/zh-CN.json b/bin/cli/locales/zh-CN.json
index 92a2657191..31be9d4c16 100644
--- a/bin/cli/locales/zh-CN.json
+++ b/bin/cli/locales/zh-CN.json
@@ -38,7 +38,8 @@
"testFailed": "提供者测试失败：{error}",
"loginEnabled": "登录：已启用（密码已更新）",
"loginDisabled": "登录：已禁用",
- "providerInfo": "提供者：{info}"
+ "providerInfo": "提供者：{info}",
+ "opencode": "安装并配置随附的 @omniroute/opencode-plugin 以用于 OpenCode"
},
"doctor": {
"title": "OmniRoute 诊断",
@@ -252,7 +253,9 @@
"no_recovery": "禁用崩溃自动重启（调试模式）",
"max_restarts": "30 秒内的最大崩溃重启次数（默认：2）",
"tray": "显示系统托盘图标（仅桌面，选择加入）",
- "no_tray": "禁用系统托盘图标"
+ "no_tray": "禁用系统托盘图标",
+ "tls_cert": "用于提供 HTTPS 服务的 TLS 证书（PEM）路径（也可用 OMNIROUTE_TLS_CERT）",
+ "tls_key": "用于提供 HTTPS 服务的 TLS 私钥（PEM）路径（也可用 OMNIROUTE_TLS_KEY）"
},
"backup": {
"title": "备份",
@@ -1258,5 +1261,69 @@
"search": "搜索 npm 注册表中的可用插件",
"update": "更新已安装的插件",
"scaffold": "搭建新的插件模板"
+ },
+ "authExport": {
+ "description": "导出已解密的提供者凭据（仅限本地，明文输出）",
+ "idOpt": "仅导出与此 id/名称/提供者匹配的连接",
+ "formatOpt": "输出格式：json 或 env",
+ "outOpt": "将输出写入文件而非标准输出（以 0600 权限写入）",
+ "forceOpt": "确认你了解此操作会打印/写入明文密钥",
+ "warning": "⚠ 此操作会打印/写入已解密的明文 API 密钥和 OAuth 令牌。请确保你的屏幕、shell 历史记录以及任何输出文件保持私密。",
+ "confirmHeading": "⚠ 警告：此操作会以明文导出已解密的提供者凭据",
+ "confirmBody": "此命令会为所选连接解密并打印/写入 apiKey、accessToken、refreshToken 和\nidToken。请将输出视为机密。",
+ "confirmFooter": "如需确认，请运行：\n omniroute auth export --force",
+ "missingKey": "导出凭据需要 STORAGE_ENCRYPTION_KEY。",
+ "notFound": "未找到连接：{id}",
+ "invalidFormat": "无效格式：{format}。请使用 json 或 env。"
+ },
+ "radar": {
+ "description": "检查并同步本地 Radar 目录订阅源",
+ "status": "显示本地 Radar 设置和订阅源缓存状态",
+ "sync": "通过本地服务器同步目录、推荐、优惠和 Intel"
+ },
+ "launch": {
+ "description": "启动指向 OmniRoute 的 Claude Code（本地或远程，使用 --profile）",
+ "token": "Claude 客户端应发送的令牌（ANTHROPIC_AUTH_TOKEN）",
+ "notRunning": "无法在 {port} 访问 OmniRoute。请使用 “omniroute serve” 启动它。",
+ "notFound": "在 PATH 中未找到 “claude” CLI。"
+ },
+ "run": {
+ "description": "通过 OmniRoute 启动受支持的 CLI 目标"
+ },
+ "setupClaude": {
+ "description": "从 OmniRoute 模型目录生成 ~/.claude/profiles 的 Claude Code 配置文件"
+ },
+ "connect": {
+ "description": "连接到远程 OmniRoute 服务器并进入远程模式"
+ },
+ "tokens": {
+ "description": "管理限定范围的 CLI 访问令牌（远程模式）"
+ },
+ "configure": {
+ "description": "从活动服务器选择提供者+模型并配置受支持的本地 CLI"
+ },
+ "launchCodex": {
+ "description": "启动指向 OmniRoute 的 Codex CLI（本地或远程 VPS）"
+ },
+ "setupCodex": {
+ "description": "从 OmniRoute 实时模型目录生成 ~/.codex 配置文件"
+ },
+ "packs": {
+ "description": "管理可选的运行时包（ML / 浏览器自动化）",
+ "listDescription": "列出可选包及其安装状态",
+ "installDescription": "将可选包安装到 DATA_DIR",
+ "verifyDescription": "根据随附的校验和索引验证已安装的包",
+ "removeDescription": "移除已安装的可选包",
+ "sourceOpt": "存放包负载和包索引的目录",
+ "warnNoIndex": "未找到 optional-packs.index.json —— 此检出无法进行安装/验证（桌面捆绑包会附带它）",
+ "errUnknown": "未知的包：{name}",
+ "errNoIndex": "未找到包索引；请通过 --source 传入存放包负载的目录（桌面捆绑包会将其附带在应用旁）",
+ "installed": "包 “{name}” 已安装并在 {dir} 验证通过",
+ "restartHint": "请重启 OmniRoute 服务器（或桌面应用），以便运行时加载该包",
+ "removed": "包 “{name}” 已移除",
+ "notInstalled": "包 “{name}” 未安装",
+ "verifyOk": "所有已安装的包均已验证通过",
+ "verifyFailed": "{count} 个包验证失败",
+ "noneInstalled": "未安装可选包"
}
}
diff --git a/bin/cli/locales/zh-TW.json b/bin/cli/locales/zh-TW.json
index 6880b8fb77..fa7ca866b8 100644
--- a/bin/cli/locales/zh-TW.json
+++ b/bin/cli/locales/zh-TW.json
@@ -38,7 +38,8 @@
"testFailed": "提供者測試失敗：{error}",
"loginEnabled": "登入：已啟用（密碼已更新）",
"loginDisabled": "登入：已停用",
- "providerInfo": "提供者：{info}"
+ "providerInfo": "提供者：{info}",
+ "opencode": "安裝並配置隨附的 @omniroute/opencode-plugin 以用於 OpenCode"
},
"doctor": {
"title": "OmniRoute 診斷",
@@ -252,7 +253,9 @@
"no_recovery": "停用崩潰自動重啟（除錯模式）",
"max_restarts": "30 秒內的最大崩潰重啟次數（預設：2）",
"tray": "顯示系統托盤圖示（僅桌面，選擇加入）",
- "no_tray": "停用系統托盤圖示"
+ "no_tray": "停用系統托盤圖示",
+ "tls_cert": "用於提供 HTTPS 服務的 TLS 憑證（PEM）路徑（也可用 OMNIROUTE_TLS_CERT）",
+ "tls_key": "用於提供 HTTPS 服務的 TLS 私鑰（PEM）路徑（也可用 OMNIROUTE_TLS_KEY）"
},
"backup": {
"title": "備份",
@@ -1258,5 +1261,69 @@
"search": "搜尋 npm 登錄檔中的可用外掛",
"update": "更新已安裝的外掛",
"scaffold": "搭建新的外掛模板"
+ },
+ "authExport": {
+ "description": "匯出已解密的提供者憑據（僅限本機，明文輸出）",
+ "idOpt": "僅匯出與此 id/名稱/提供者相符的連線",
+ "formatOpt": "輸出格式：json 或 env",
+ "outOpt": "將輸出寫入檔案而非標準輸出（以 0600 權限寫入）",
+ "forceOpt": "確認你了解此操作會列印/寫入明文密鑰",
+ "warning": "⚠ 此操作會列印/寫入已解密的明文 API 金鑰和 OAuth 令牌。請確保你的螢幕、shell 歷史記錄以及任何輸出檔案保持私密。",
+ "confirmHeading": "⚠ 警告：此操作會以明文匯出已解密的提供者憑據",
+ "confirmBody": "此命令會為所選連線解密並列印/寫入 apiKey、accessToken、refreshToken 和\nidToken。請將輸出視為機密。",
+ "confirmFooter": "如需確認，請執行：\n omniroute auth export --force",
+ "missingKey": "匯出憑據需要 STORAGE_ENCRYPTION_KEY。",
+ "notFound": "找不到連線：{id}",
+ "invalidFormat": "無效格式：{format}。請使用 json 或 env。"
+ },
+ "radar": {
+ "description": "檢查並同步本機 Radar 目錄訂閱來源",
+ "status": "顯示本機 Radar 設定和訂閱來源快取狀態",
+ "sync": "透過本機伺服器同步目錄、推薦、優惠和 Intel"
+ },
+ "launch": {
+ "description": "啟動指向 OmniRoute 的 Claude Code（本機或遠端，使用 --profile）",
+ "token": "Claude 用戶端應傳送的令牌（ANTHROPIC_AUTH_TOKEN）",
+ "notRunning": "無法在 {port} 存取 OmniRoute。請使用「omniroute serve」啟動它。",
+ "notFound": "在 PATH 中找不到「claude」CLI。"
+ },
+ "run": {
+ "description": "透過 OmniRoute 啟動受支援的 CLI 目標"
+ },
+ "setupClaude": {
+ "description": "從 OmniRoute 模型目錄產生 ~/.claude/profiles 的 Claude Code 配置檔"
+ },
+ "connect": {
+ "description": "連線到遠端 OmniRoute 伺服器並進入遠端模式"
+ },
+ "tokens": {
+ "description": "管理限定範圍的 CLI 存取令牌（遠端模式）"
+ },
+ "configure": {
+ "description": "從使用中的伺服器選擇提供者+模型並配置受支援的本機 CLI"
+ },
+ "launchCodex": {
+ "description": "啟動指向 OmniRoute 的 Codex CLI（本機或遠端 VPS）"
+ },
+ "setupCodex": {
+ "description": "從 OmniRoute 即時模型目錄產生 ~/.codex 配置檔"
+ },
+ "packs": {
+ "description": "管理可選的執行階段套件（ML / 瀏覽器自動化）",
+ "listDescription": "列出可選套件及其安裝狀態",
+ "installDescription": "將可選套件安裝到 DATA_DIR",
+ "verifyDescription": "根據隨附的總和檢查碼索引驗證已安裝的套件",
+ "removeDescription": "移除已安裝的可選套件",
+ "sourceOpt": "存放套件負載和套件索引的目錄",
+ "warnNoIndex": "找不到 optional-packs.index.json —— 此檢出無法進行安裝/驗證（桌面套件會隨附它）",
+ "errUnknown": "未知的套件：{name}",
+ "errNoIndex": "找不到套件索引；請透過 --source 傳入存放套件負載的目錄（桌面套件會將其隨附在應用程式旁）",
+ "installed": "套件「{name}」已安裝並在 {dir} 驗證通過",
+ "restartHint": "請重新啟動 OmniRoute 伺服器（或桌面應用程式），以便執行階段載入該套件",
+ "removed": "套件「{name}」已移除",
+ "notInstalled": "套件「{name}」未安裝",
+ "verifyOk": "所有已安裝的套件均已驗證通過",
+ "verifyFailed": "{count} 個套件驗證失敗",
+ "noneInstalled": "未安裝可選套件"
}
}
diff --git a/bin/cli/npm-exec.mjs b/bin/cli/npm-exec.mjs
new file mode 100644
index 0000000000..b54dc3d5da
--- /dev/null
+++ b/bin/cli/npm-exec.mjs
@@ -0,0 +1,34 @@
+// Spawning npm from the CLI, on every platform.
+//
+// On Windows npm is `npm.cmd`, a batch wrapper. Node ≥ 24 refuses to spawn a
+// `.cmd` without a shell (nodejs/node#52554), and a bare `npm` can additionally
+// resolve to an extensionless shim that `CreateProcess` cannot execute — so the
+// call fails with `EINVAL` or `ENOENT` while npm works fine in the same terminal.
+// `src/lib/services/installers/utils.ts` already solves this for the server; this
+// is the same rule for the `bin/cli` entry points, which cannot import TypeScript.
+//
+// SECURITY (Hard Rule #13): enabling the shell means the SHELL splits the command
+// line, not `execFile`. Every argv element passed alongside these options must be
+// a literal — never a runtime value — or it must be validated first. Callers that
+// need to pass a user-supplied name have to guard it themselves.
+
+/** The npm binary to spawn on this platform. */
+export function npmBin(platform = process.platform) {
+ const isBun = Boolean(process.versions.bun);
+ if (platform === "win32") return isBun ? "bun.exe" : "npm.cmd";
+ return isBun ? "bun" : "npm";
+}
+
+/**
+ * `execFile` / `spawnSync` options for an npm call.
+ *
+ * @param {NodeJS.Platform} platform
+ * @param {{ timeoutMs?: number, stdio?: string }} [options]
+ */
+export function npmExecOptions(platform = process.platform, options = {}) {
+ const base = {};
+ if (options.timeoutMs !== undefined) base.timeout = options.timeoutMs;
+ if (options.stdio !== undefined) base.stdio = options.stdio;
+ if (platform !== "win32") return { ...base, shell: false };
+ return { ...base, shell: true, windowsHide: true };
+}
diff --git a/bin/cli/runtime/trayRuntime.ts b/bin/cli/runtime/trayRuntime.ts
index 98a3abfccc..ef8894dc04 100644
--- a/bin/cli/runtime/trayRuntime.ts
+++ b/bin/cli/runtime/trayRuntime.ts
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
import { execSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
const RUNTIME_DIR = join(homedir(), ".omniroute", "runtime");
// systray2 is a maintained fork with prebuilt binaries — installed lazily at runtime,
@@ -16,6 +17,16 @@ export const SYSTRAY_PACKAGE = "systray2";
export const SYSTRAY_VERSION = "2.1.4";
const SYSTRAY_SPEC = `${SYSTRAY_PACKAGE}@${SYSTRAY_VERSION}`;
+// Dynamic `import()` resolves its specifier as a URL, not a filesystem path.
+// On Windows the lazily-installed systray2 lives at an absolute path whose
+// leading drive letter the ESM loader parses as an unsupported URL scheme
+// (e.g. `c:`) and rejects. Build a file:// URL so the tray import works on
+// Windows too. Same defect fixed for the CLI db-fallback imports in #11238,
+// missed at this call site.
+export function systrayModuleSpecifier(runtimeDir: string): string {
+ return pathToFileURL(join(runtimeDir, "node_modules", SYSTRAY_PACKAGE)).href;
+}
+
export function resolveSystrayBinName(platform: NodeJS.Platform): string | null {
if (platform === "win32") return "tray_windows_release.exe";
if (platform === "darwin") return "tray_darwin_release";
@@ -60,8 +71,7 @@ export async function loadSystray(): Promise<(new (...args: unknown[]) => unknow
// drop the +x bit on extraction (observed on macOS).
chmodSystrayBinAt(RUNTIME_DIR, process.platform);
try {
- const modPath = join(RUNTIME_DIR, "node_modules", SYSTRAY_PACKAGE);
- const mod = await import(modPath);
+ const mod = await import(systrayModuleSpecifier(RUNTIME_DIR));
return (mod.default ?? mod.SysTray ?? mod) as (new (...args: unknown[]) => unknown) | null;
} catch (err) {
console.warn(`[omniroute] tray runtime import failed: ${(err as Error).message}`);
diff --git a/bin/cli/tray/autostart.mjs b/bin/cli/tray/autostart.mjs
index 3462c2711f..f554f4554c 100644
--- a/bin/cli/tray/autostart.mjs
+++ b/bin/cli/tray/autostart.mjs
@@ -114,10 +114,13 @@ function writeLinuxSystemdUnit(cliPath) {
const unitDir = dirname(linuxSystemdUnitPath());
mkdirSync(unitDir, { recursive: true });
const envFile = join(userHomeDir(), ".omniroute", ".env");
+ const nodeBinDir = dirname(process.execPath);
+ const userLocalBin = join(userHomeDir(), ".local", "bin");
+ const pathEnv = `${nodeBinDir}:${userLocalBin}:/usr/local/sbin:/usr/local/bin:/usr/bin:/bin`;
const lines = [
"[Unit]",
"Description=OmniRoute AI proxy router",
- "After=network-online.target",
+ "After=network-online.target graphical-session.target",
"Wants=network-online.target",
"",
"[Service]",
@@ -134,6 +137,7 @@ function writeLinuxSystemdUnit(cliPath) {
`ExecStart=${buildServeExecLine(cliPath, { tray: false })}`,
"Restart=on-failure",
"RestartSec=5",
+ `Environment="PATH=${pathEnv}"`,
];
if (existsSync(envFile)) lines.push(`EnvironmentFile=-${envFile}`);
lines.push("", "[Install]", "WantedBy=default.target", "");
diff --git a/changelog.d/features/10556-elevenlabs-native-routes.md b/changelog.d/features/10556-elevenlabs-native-routes.md
new file mode 100644
index 0000000000..3fcb68d0aa
--- /dev/null
+++ b/changelog.d/features/10556-elevenlabs-native-routes.md
@@ -0,0 +1 @@
+- **feat(audio):** proxy native ElevenLabs voices, text-to-speech, and speech-to-text HTTP routes through stored OmniRoute credentials, preserving query strings, multipart uploads, binary responses, and upstream errors (#10556).
diff --git a/changelog.d/features/10590-google-ai-studio-tts.md b/changelog.d/features/10590-google-ai-studio-tts.md
new file mode 100644
index 0000000000..9fcf931919
--- /dev/null
+++ b/changelog.d/features/10590-google-ai-studio-tts.md
@@ -0,0 +1 @@
+- Added Google AI Studio Gemini batch text-to-speech support through `POST /v1/audio/speech`.
diff --git a/changelog.d/features/11023-compression-worker-pool.md b/changelog.d/features/11023-compression-worker-pool.md
new file mode 100644
index 0000000000..4d9c1b9d60
--- /dev/null
+++ b/changelog.d/features/11023-compression-worker-pool.md
@@ -0,0 +1,3 @@
+- Run synchronous RTK and Caveman request compression in a bounded worker-thread pool, keeping
+ large `/v1/responses` compression heaps outside the HTTP isolate while preserving strict
+ fail-open behavior and per-engine telemetry.
diff --git a/changelog.d/features/11369-video-bridge-drilldown-isolation.md b/changelog.d/features/11369-video-bridge-drilldown-isolation.md
new file mode 100644
index 0000000000..b0b499304d
--- /dev/null
+++ b/changelog.d/features/11369-video-bridge-drilldown-isolation.md
@@ -0,0 +1 @@
+- **feat(video bridge):** harden the optional drill-down cache substrate with exact-path broker policy, canonical principal/session/media isolation, independent retained-byte quotas, cancellation-safe commits, rejection of excess or non-canonical Base64 padding and non-JPEG/truncated media, warning-sensitive full JPEG canonicalization that strips trailing polyglot bytes, server-derived dimensions, and auditable derivation metadata; production tenant binding and multi-resolution selection remain follow-up work ([#11369](https://github.com/diegosouzapw/OmniRoute/pull/11369))
diff --git a/changelog.d/features/11383-video-bridge-focused-mode.md b/changelog.d/features/11383-video-bridge-focused-mode.md
new file mode 100644
index 0000000000..a5d06efb00
--- /dev/null
+++ b/changelog.d/features/11383-video-bridge-focused-mode.md
@@ -0,0 +1 @@
+- **feat(video):** add an opt-in focused analysis mode that safely uses a normalized, 500-code-point latest-user hint for task-aware frame captions while preserving full-mode prompts, temporal-window isolation, and cache identity without storing raw task text ([#11383](https://github.com/diegosouzapw/OmniRoute/pull/11383)).
diff --git a/changelog.d/features/6342-cliproxy-account-health.md b/changelog.d/features/6342-cliproxy-account-health.md
new file mode 100644
index 0000000000..69b57b41fd
--- /dev/null
+++ b/changelog.d/features/6342-cliproxy-account-health.md
@@ -0,0 +1 @@
+- feat(services): show sanitized CLIProxyAPI account health from its authenticated management API without exposing credentials, file paths, or raw account metadata (#6342)
diff --git a/changelog.d/fixes/10352-github-access-token-health.md b/changelog.d/fixes/10352-github-access-token-health.md
new file mode 100644
index 0000000000..732f6ef713
--- /dev/null
+++ b/changelog.d/fixes/10352-github-access-token-health.md
@@ -0,0 +1 @@
+- **fix(github):** proactive credential health now verifies GitHub access tokens through the existing Copilot token exchange, marks only a confirmed `401 Unauthorized` as expired, and leaves rate limits, permission failures, upstream failures, and network errors routable ([#10352](https://github.com/diegosouzapw/OmniRoute/issues/10352)) — thanks @RaviTharuma
diff --git a/changelog.d/fixes/11284-antigravity-empty-projectid-rejection.md b/changelog.d/fixes/11284-antigravity-empty-projectid-rejection.md
new file mode 100644
index 0000000000..f86208d9a7
--- /dev/null
+++ b/changelog.d/fixes/11284-antigravity-empty-projectid-rejection.md
@@ -0,0 +1 @@
+- **fix(providers):** Antigravity OAuth marks connects with no Cloud Code projectId as degraded instead of a false "Connected"; BYOP detection at connect time, auto-disable of confirmed-missing accounts, and selection-side rotation ([#11284](https://github.com/diegosouzapw/OmniRoute/issues/11284))
diff --git a/changelog.d/fixes/11311-group-model-pattern-regex-escape.md b/changelog.d/fixes/11311-group-model-pattern-regex-escape.md
new file mode 100644
index 0000000000..dad1fa1e16
--- /dev/null
+++ b/changelog.d/fixes/11311-group-model-pattern-regex-escape.md
@@ -0,0 +1 @@
+- **fix(db):** group model patterns escape regex metacharacters, so `gpt-4.1*` no longer matches `gpt-4o1-preview` and a pattern like `gpt-4(*` no longer throws `SyntaxError` out of the completion and `/v1/models` paths ([#11311](https://github.com/diegosouzapw/OmniRoute/pull/11311))
diff --git a/changelog.d/fixes/11319-upstream-proxy-host-spelling.md b/changelog.d/fixes/11319-upstream-proxy-host-spelling.md
new file mode 100644
index 0000000000..a16ec17bba
--- /dev/null
+++ b/changelog.d/fixes/11319-upstream-proxy-host-spelling.md
@@ -0,0 +1 @@
+- **fix(db):** the upstream proxy URL check judges the host by address instead of by spelling, so `http://[::ffff:169.254.169.254]`, `[::ffff:10.0.0.5]`, ULA/link-local and CGNAT targets are refused like their dotted equivalents ([#11319](https://github.com/diegosouzapw/OmniRoute/pull/11319))
diff --git a/changelog.d/fixes/11325-i18n-pt-placeholder-parity.md b/changelog.d/fixes/11325-i18n-pt-placeholder-parity.md
new file mode 100644
index 0000000000..97a2370955
--- /dev/null
+++ b/changelog.d/fixes/11325-i18n-pt-placeholder-parity.md
@@ -0,0 +1 @@
+- **fix(i18n):** three `pt` strings had dropped their placeholders — the cache tile's subtitle repeated its own label instead of showing `{total}` — and a unit test now enforces placeholder parity with `en` across all locales ([#11325](https://github.com/diegosouzapw/OmniRoute/pull/11325))
diff --git a/changelog.d/fixes/11326-kie-market-google-imagen-ids.md b/changelog.d/fixes/11326-kie-market-google-imagen-ids.md
new file mode 100644
index 0000000000..62dacb5d48
--- /dev/null
+++ b/changelog.d/fixes/11326-kie-market-google-imagen-ids.md
@@ -0,0 +1 @@
+- **fix(kie):** map the remaining `google-imagen/*` KIE Market catalog ids (`nano-banana`, `nano-banana-pro`, `nano-banana-edit`) to their real, KIE-documented upstream `model` values — `#11225`'s fix only covered `nano-banana-2` ([#11326](https://github.com/diegosouzapw/OmniRoute/pull/11326)).
diff --git a/changelog.d/fixes/11328-upstream-headers-proxy-auth.md b/changelog.d/fixes/11328-upstream-headers-proxy-auth.md
new file mode 100644
index 0000000000..2155b9ea90
--- /dev/null
+++ b/changelog.d/fixes/11328-upstream-headers-proxy-auth.md
@@ -0,0 +1 @@
+- **fix(security):** `proxy-authorization` and `proxy-authenticate` are refused as upstream/custom headers, so a proxy credential is no longer forwarded to the model provider — the canonical denylist now matches the RFC 7230 §6.1 set the rest of the codebase already strips ([#11328](https://github.com/diegosouzapw/OmniRoute/pull/11328))
diff --git a/changelog.d/fixes/11344-video-bridge-scene-aware-sampler.md b/changelog.d/fixes/11344-video-bridge-scene-aware-sampler.md
new file mode 100644
index 0000000000..e33e40fab7
--- /dev/null
+++ b/changelog.d/fixes/11344-video-bridge-scene-aware-sampler.md
@@ -0,0 +1 @@
+- **fix(video-bridge):** fall back to the deterministic active-window midpoint when a one-frame scene-aware budget cannot preserve both timeline ends; a real FFmpeg fixture matrix now covers rapid cuts, gradual changes, static and short clips, and detector failure ([#11344](https://github.com/diegosouzapw/OmniRoute/pull/11344)).
diff --git a/changelog.d/fixes/11347-codex-claude-empty-tool-use.md b/changelog.d/fixes/11347-codex-claude-empty-tool-use.md
new file mode 100644
index 0000000000..1c845d510f
--- /dev/null
+++ b/changelog.d/fixes/11347-codex-claude-empty-tool-use.md
@@ -0,0 +1 @@
+- **fix(translator):** Codex Responses tool calls translated for Claude clients no longer emit a duplicate `tool_use` block with the same ID and an empty name, preventing Claude Code from terminating with `No such tool available` ([#11347](https://github.com/diegosouzapw/OmniRoute/pull/11347))
diff --git a/changelog.d/fixes/11350-video-bridge-contact-sheet-labels.md b/changelog.d/fixes/11350-video-bridge-contact-sheet-labels.md
new file mode 100644
index 0000000000..5a4f4b2fba
--- /dev/null
+++ b/changelog.d/fixes/11350-video-bridge-contact-sheet-labels.md
@@ -0,0 +1 @@
+- **fix(video-bridge):** burn high-contrast timestamps into every bounded contact-sheet cell and add a real-model A/B harness whose promotion verdict stays `HOLD` until token, latency, and quality evidence is actually executed ([#11350](https://github.com/diegosouzapw/OmniRoute/pull/11350))
diff --git a/changelog.d/fixes/11362-video-bridge-result-cache.md b/changelog.d/fixes/11362-video-bridge-result-cache.md
new file mode 100644
index 0000000000..122d287aec
--- /dev/null
+++ b/changelog.d/fixes/11362-video-bridge-result-cache.md
@@ -0,0 +1 @@
+- **fix(video):** fingerprint protected Video Bridge bytes, coalesce concurrent work, and fail open when the bounded TTL/LRU result cache is unavailable or corrupt ([#11362](https://github.com/diegosouzapw/OmniRoute/pull/11362))
diff --git a/changelog.d/fixes/11367-catalog-eventloop-9147.md b/changelog.d/fixes/11367-catalog-eventloop-9147.md
new file mode 100644
index 0000000000..5f2efe48f8
--- /dev/null
+++ b/changelog.d/fixes/11367-catalog-eventloop-9147.md
@@ -0,0 +1 @@
+- **fix(catalog):** keep large `/v1/models` builds responsive by reusing the build-local capability snapshot throughout enrichment and Auto-Combo preparation, yielding cooperatively while constructing virtual candidate pools, and avoiding unrelated synchronous database diagnostics on the cache-TTL read path ([#11367](https://github.com/diegosouzapw/OmniRoute/pull/11367))
diff --git a/changelog.d/fixes/11382-video-bridge-dedup-policy.md b/changelog.d/fixes/11382-video-bridge-dedup-policy.md
new file mode 100644
index 0000000000..e12d71ac4b
--- /dev/null
+++ b/changelog.d/fixes/11382-video-bridge-dedup-policy.md
@@ -0,0 +1 @@
+- **fix(video):** apply the caption-frame cap after bounded visual deduplication, preserve first/final candidates plus small high-contrast motion and text changes, and version the dedup policy in result-cache identity ([#11382](https://github.com/diegosouzapw/OmniRoute/pull/11382)).
diff --git a/changelog.d/fixes/11394-modelsdev-interval-slider.md b/changelog.d/fixes/11394-modelsdev-interval-slider.md
new file mode 100644
index 0000000000..6f5e955c8e
--- /dev/null
+++ b/changelog.d/fixes/11394-modelsdev-interval-slider.md
@@ -0,0 +1 @@
+- **fix(dashboard):** Model Database sync interval slider ticks now match the thumb position — checkpoint-space slider with magnetic snap on release ([#11394](https://github.com/diegosouzapw/OmniRoute/pull/11394)) — thanks @An0nym0us92
diff --git a/changelog.d/fixes/cli-update-npm-win32-11335.md b/changelog.d/fixes/cli-update-npm-win32-11335.md
new file mode 100644
index 0000000000..fae14f20a9
--- /dev/null
+++ b/changelog.d/fixes/cli-update-npm-win32-11335.md
@@ -0,0 +1 @@
+- **fix(cli):** `omniroute update` now finds npm on Windows. It called `execFile("npm", …)` with no shell, and on Node ≥ 24 a `.cmd` wrapper cannot be spawned that way (nodejs/node#52554) — while a bare `npm` can also resolve to an extensionless shim `CreateProcess` refuses. The result was `✖ Could not check latest version. Is npm available?` in a terminal where `npm view omniroute version` worked fine, so the updater was unusable on Windows even though nothing was wrong with the install. This is the same class as #5379/#5542, which fixed the server-side calls; the CLI entry points were missed because they are plain `.mjs` and cannot import the TypeScript helper. `bin/cli/npm-exec.mjs` now states the same rule for them: `npm.cmd` plus a shell on win32, no shell anywhere else. Both npm lookups in `update.mjs` (version and changelog) pass a literal argv array, so enabling the shell cannot splice a runtime value into the command line — a test asserts that and fails if a future edit interpolates one. (#11335)
diff --git a/changelog.d/fixes/compression-worker-bundler-resolve.md b/changelog.d/fixes/compression-worker-bundler-resolve.md
new file mode 100644
index 0000000000..3a867303d6
--- /dev/null
+++ b/changelog.d/fixes/compression-worker-bundler-resolve.md
@@ -0,0 +1 @@
+- **fix(compression):** use `pathToFileURL` in `compressionWorkerPool` so bundlers (Webpack / Turbopack) do not attempt static asset resolution of missing `compressionWorker.js` during build
diff --git a/changelog.d/fixes/glm-credit-limit-quota.md b/changelog.d/fixes/glm-credit-limit-quota.md
new file mode 100644
index 0000000000..e46eb96ee9
--- /dev/null
+++ b/changelog.d/fixes/glm-credit-limit-quota.md
@@ -0,0 +1 @@
+- **fix(usage):** z.ai/GLM coding-plan subscription keys now render their quota cards again, with absolute credits. Z.ai's `/api/monitor/usage/quota/limit` switched these keys from `TOKENS_LIMIT` to `CREDIT_LIMIT` rows (same `unit`/`number` semantics: unit=3/number=5 → 5-hour window, unit=6/number=1 → weekly), and the parser only matched `TOKENS_LIMIT`/`TIME_LIMIT`, so both rows were dropped and the subscription card rendered empty. `CREDIT_LIMIT` is now accepted alongside `TOKENS_LIMIT`, and when the row carries absolute credit fields (`usage`/`currentValue`/`remaining`) they are preferred over the percent-only scale, so the card shows `3341 / 28000` like z.ai's own dashboard instead of `11 / 100`
diff --git a/changelog.d/fixes/lasterror-provider-error-detail.md b/changelog.d/fixes/lasterror-provider-error-detail.md
new file mode 100644
index 0000000000..60872c52cc
--- /dev/null
+++ b/changelog.d/fixes/lasterror-provider-error-detail.md
@@ -0,0 +1 @@
+- **fix(auth):** a connection's `lastError` now names the real upstream failure instead of the bare string `Provider error`. `markAccountUnavailable` kept the reason only when it was already a string, so every other shape collapsed to that literal — and the shape that matters most is not a string: a failed `fetch` arrives as `TypeError: fetch failed` with the actionable part on `error.cause.code`, which means a wrong port, a firewall, a DNS failure and a blocked proxy all looked identical in the dashboard and in the console line. `describeUpstreamFailure` (in `src/shared/utils/upstreamError.ts`, reusing the `extractErrorMessage` that already parsed provider bodies) reads Error messages and appends the transport code when the message does not already carry it, reads the usual provider JSON shapes (`error.message`, `message`, string `error`, `detail`, `errors[]`), and falls back to the code alone before giving up. It never serializes the error object wholesale, so a request body or header attached to an error cannot leak into the stored reason — pinned by a test.
diff --git a/changelog.d/fixes/live-ws-public-url-runtime.md b/changelog.d/fixes/live-ws-public-url-runtime.md
new file mode 100644
index 0000000000..a46a9798f8
--- /dev/null
+++ b/changelog.d/fixes/live-ws-public-url-runtime.md
@@ -0,0 +1 @@
+- **fix(live-ws):** the Live dashboard socket can now be pointed at a reverse proxy without rebuilding the image. `NEXT_PUBLIC_*` is inlined at BUILD time, so a prebuilt Docker or npm image never carries an operator's `NEXT_PUBLIC_LIVE_WS_PUBLIC_URL` — which is exactly why the browser discovers the socket through `/api/v1/ws?handshake=1` instead. The server side of that handshake, however, read only the `NEXT_PUBLIC_`-prefixed name, so it had nothing to echo: behind Traefik the dashboard kept dialling `wss://:20132/live-ws` and sat on "Live disabled — WebSocket disconnected. Showing last known state." `LIVE_WS_PUBLIC_URL` is now read at runtime alongside the existing `LIVE_WS_HOST` / `LIVE_WS_PORT`, and the prefixed name stays supported as the fallback, so deployments that already set it are unaffected. Only `ws://` and `wss://` values are accepted, matching the guard the client already applies. (#11331)
diff --git a/changelog.d/maintenance/11342-pnpm-optional-peers-license-policy.md b/changelog.d/maintenance/11342-pnpm-optional-peers-license-policy.md
new file mode 100644
index 0000000000..55df9af673
--- /dev/null
+++ b/changelog.d/maintenance/11342-pnpm-optional-peers-license-policy.md
@@ -0,0 +1,3 @@
+- **fix(deps):** prevent pnpm from auto-installing the unused `@lobehub/ui` peer subtree of
+ `@lobehub/icons`, keeping six unneeded packages with incompatible or unverifiable license
+ metadata out of production installs ([#11342](https://github.com/diegosouzapw/OmniRoute/pull/11342)).
diff --git a/changelog.d/maintenance/11345-changelog-reconciliation-ledger.md b/changelog.d/maintenance/11345-changelog-reconciliation-ledger.md
new file mode 100644
index 0000000000..e9cb8e877c
--- /dev/null
+++ b/changelog.d/maintenance/11345-changelog-reconciliation-ledger.md
@@ -0,0 +1 @@
+- **ci(changelog):** replace the broad removal bypass with an exact, hash-bound reconciliation ledger and bind merge-train checks to their requested release base ([#11345](https://github.com/diegosouzapw/OmniRoute/pull/11345)).
diff --git a/changelog.d/maintenance/11356-readme-live-metrics.md b/changelog.d/maintenance/11356-readme-live-metrics.md
new file mode 100644
index 0000000000..3d06965062
--- /dev/null
+++ b/changelog.d/maintenance/11356-readme-live-metrics.md
@@ -0,0 +1,5 @@
+- **docs(readme):** reconcile live v3.8.50 provider, free-tier, CLI, routing, test,
+ community, sponsor, acknowledgment, and SVG metrics with their audited source
+ denominators, including a deduplicated OmniRoute-in-Action snapshot and distinct
+ contributor rankings for merged pull requests, GitHub-attributed commits, and Git history
+ ([#11356](https://github.com/diegosouzapw/OmniRoute/pull/11356)).
diff --git a/changelog.d/maintenance/11363-openapi-try-operation-coverage.md b/changelog.d/maintenance/11363-openapi-try-operation-coverage.md
new file mode 100644
index 0000000000..f666967041
--- /dev/null
+++ b/changelog.d/maintenance/11363-openapi-try-operation-coverage.md
@@ -0,0 +1 @@
+- **docs(openapi):** document the conditionally management-authenticated, same-origin `POST /api/openapi/try` proxy contract and restore the release branch's operation-coverage ratchet ([#11363](https://github.com/diegosouzapw/OmniRoute/pull/11363))
diff --git a/changelog.d/maintenance/11381-video-bridge-fu07-structural-sampling.md b/changelog.d/maintenance/11381-video-bridge-fu07-structural-sampling.md
new file mode 100644
index 0000000000..17a48aa416
--- /dev/null
+++ b/changelog.d/maintenance/11381-video-bridge-fu07-structural-sampling.md
@@ -0,0 +1 @@
+- **fix(video-bridge):** make opt-in segment-aware sampling use one bounded structural FFmpeg pass (scene, freeze, blur, exposure, and SI/TI), preserve long trailing segments, fail open to uniform sampling, and add real-media structural-oracle, overhead, post-dedup caption-call, and false-positive evidence while holding unconfigured model quality and gain-versus-cost claims ([#11381](https://github.com/diegosouzapw/OmniRoute/pull/11381)).
diff --git a/config/quality/eslint-suppressions.json b/config/quality/eslint-suppressions.json
index d873a51adb..5926a541ba 100644
--- a/config/quality/eslint-suppressions.json
+++ b/config/quality/eslint-suppressions.json
@@ -3445,7 +3445,7 @@
},
"tests/integration/qdrant-routes.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 19
+ "count": 3
}
},
"tests/integration/quota-pools-usage.test.ts": {
@@ -4029,10 +4029,10 @@
},
"tests/unit/cli-combo-suggest-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 16
+ "count": 14
},
"@typescript-eslint/no-unused-vars": {
- "count": 2
+ "count": 1
}
},
"tests/unit/cli-completion-dynamic.test.ts": {
@@ -4042,7 +4042,7 @@
},
"tests/unit/cli-compression-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 32
+ "count": 20
}
},
"tests/unit/cli-context-eng-commands.test.ts": {
@@ -4099,7 +4099,7 @@
},
"tests/unit/cli-mcp-call-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 16
+ "count": 10
}
},
"tests/unit/cli-memory-commands.test.ts": {
@@ -4130,7 +4130,7 @@
},
"tests/unit/cli-oneproxy-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 22
+ "count": 14
},
"@typescript-eslint/no-unused-vars": {
"count": 1
@@ -4203,9 +4203,6 @@
"tests/unit/cli-resilience-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
"count": 16
- },
- "@typescript-eslint/no-unused-vars": {
- "count": 2
}
},
"tests/unit/cli-runtime-extended.test.ts": {
@@ -4238,7 +4235,7 @@
},
"tests/unit/cli-skills-commands.test.ts": {
"@typescript-eslint/no-explicit-any": {
- "count": 22
+ "count": 16
}
},
"tests/unit/cli-stop-supervisor-respawn-9455.test.ts": {
@@ -6620,4 +6617,4 @@
"count": 2
}
}
-}
+}
\ No newline at end of file
diff --git a/config/quality/file-size-baseline.json b/config/quality/file-size-baseline.json
index 4515d85e25..1b2a30f8ab 100644
--- a/config/quality/file-size-baseline.json
+++ b/config/quality/file-size-baseline.json
@@ -227,7 +227,9 @@
"tests/unit/translator-resp-gemini-to-openai.test.ts": 1604,
"tests/unit/usage-service-hardening.test.ts": 1928,
"tests/unit/vscode-token-routes.test.ts": 1633,
- "tests/unit/executor-antigravity.test.ts": 1427
+ "tests/unit/executor-antigravity.test.ts": 1427,
+ "tests/unit/guardrails/videoBridgeResultCache.test.ts": 1040,
+ "_rebaseline_2026_08_24_video_bridge_fu01_fu03_fu04_result_cache_tests": "PRs #11362 (FU-01 cache hardening) + #11382 (FU-03 visual dedup policy identity) + #11383 (FU-04 focused analysis mode) own test growth: videoBridgeResultCache.test.ts <1000->1040, +40 (sum of three stacked PRs boarded together in the same merge-batch, each adding its own cache-identity assertions on the shared result-cache seam). Owner pre-authorized rebaseline for legitimate PR growth (2026-08-19 directive)."
},
"_rebaseline_2026_06_09": "Re-baseline consciente pre-release v3.8.19: 9 arquivos cresceram durante o ciclo (features mergeadas: RequestLoggerV2 +281 request-logger rework, stream +101, combo +73, chatCore +45, catalog +32 fable-5/catalog-flag, callLogs +4, accountFallback +2, usageHistory novo 840) + core.ts +7 (fix resetAllDbModuleState, PR 3536). A catraca segue valendo destes valores — proximo crescimento falha. Decisao: encolher (esp. RequestLoggerV2/chatCore) e a issue #3501 ficam para o ciclo seguinte.",
"_rebaseline_2026_06_11_phase1f": "Phase 1f (#3501): ProviderDetailPageClient.tsx 4948→4062 (-886 LOC); 3 novos hooks extraídos. useProviderConnections.ts=954 acima do cap=800 — justificado: extração direta do god-component (zero lógica nova), própria redução do cliente supera o custo. useProviderSettings.ts=263 e useProviderModels.ts=154 já abaixo do cap.",
@@ -308,7 +310,7 @@
"_rebaseline_2026_07_27_v3849_train1h": "Merge-train 1H (31 PRs) — owner-approved 2026-07-27. Two distinct causes, kept separate on purpose: (1) GENUINE irreducible growth at existing chokepoints — providerLimits/auth (#8632 Kimi quota-reset recovery), rateLimitManager (#8616 idle wedged limiters), models-catalog-route.test (#8610 OpenCode Go effort aliases); (2) COLLISION with #8585, which banked shrinks measured on the pre-train release tip while 30 sibling PRs in the SAME train grew those files again — chat/accountFallback (#8628), chatCore (#8613), videoGeneration (#8581), imageGeneration. The zero-headroom frozen entries cannot absorb either. Ceilings re-pinned to the post-merge tip; #8612 (also in this train) automates shrink-banking so this self-inflicted drift stops recurring. Detail: src/lib/usage/providerLimits.ts 1006->1013 (#8632); src/sse/services/auth.ts 2492->2508 (#8632); open-sse/services/rateLimitManager.ts 1014->1060 (#8616); src/sse/handlers/chat.ts 1842->1845 (#8628); open-sse/handlers/chatCore.ts 4939->4955 (#8613); open-sse/handlers/imageGeneration.ts 3100->3101 ((sem PR — teto do #8585)); open-sse/handlers/videoGeneration.ts 1038->1063 (#8581); open-sse/services/accountFallback.ts 1965->1966 (#8628); tests/unit/models-catalog-route.test.ts 1608->1636 (#8610)",
"frozen": {
"_rebaseline_2026_08_20_10878_10799_provider_health_probes": "PRs #10878 (unsupported OpenAI-like validation probes stay neutral) + #10799 (preserve credential health on inconclusive NVIDIA-timeout/Antigravity-400 probes) own growth: src/app/api/providers/[id]/test/route.ts 946->1025 (+79, sum of both boarded together). Both add narrowly-scoped classification branches at the existing test-route dispatch chokepoint (unsupported-capability skip, credential-inconclusive detection) rather than new files, mirroring the prior 2026_06_27_5193 rebaseline of the same file. Covered by tests/unit/provider-validation-unsupported-neutral.test.ts + tests/unit/provider-health-inconclusive-probes.test.ts.",
- "src/app/api/providers/[id]/test/route.ts": 1215,
+ "src/app/api/providers/[id]/test/route.ts": 1237,
"_rebaseline_2026_08_23_11141_oauth_400_recovery": "PR #11141 (HouMinXi) own growth: test/route.ts 1025->1215 (+190, the reactive-400 recovery path — a fully rebuilt probe for refresh+retry on refreshable non-rotating connections, with inconclusive-status preservation and rotating-provider exclusion; all growth is the new probe builder + guards at the existing test-route dispatch, extraction would split the retry flow mid-logic). Covered by tests/unit/oauth-400-recovery.test.ts (8, bug-injection proof). Owner pre-authorized baseline bumps 2026-08-22.",
"_rebaseline_2026_06_22_4644_deepseek_web_tools": "PR #4644 (BugsBag/robust deepseek-web tool-call parsing): open-sse/executors/deepseek-web.ts 1117->1125 (+8). The new agentic tool-call path emits surrounding text + reasoning before tool_calls and swaps to the dedicated deepseekWebTools.ts parser; the +8 lines are cohesive wiring at the existing transformSSE chokepoint (the parser itself lives in the new deepseekWebTools.ts file, already under cap). The PR's own fast-gate (PR->release) does not run check:file-size, so this surfaced only at release reconcile. Covered by tests/unit/deepseek-web-tools-variants.test.ts + deepseek-web-tools-execute.test.ts.",
"_rebaseline_2026_06_23_4712_deepseek_web_tool_results": "PR for #4712 (deepseek-web drops role:tool): open-sse/executors/deepseek-web.ts 1125->1148 (+23). messagesToPrompt() now folds role:\"tool\" results into the single-prompt transcript (recovering the tool name from the preceding assistant tool_calls by tool_call_id) instead of silently dropping them; the lines are cohesive wiring inside the existing function. Covered by tests/unit/deepseek-web-tool-result-prompt-4712.test.ts.",
@@ -433,7 +435,8 @@
"src/shared/components/analytics/charts.tsx": 1346,
"src/shared/services/cliRuntime.ts": 1459,
"src/sse/handlers/chat.ts": 2493,
- "src/sse/services/auth.ts": 3344,
+ "src/sse/services/auth.ts": 3346,
+ "_rebaseline_2026_08_24_lasterror_provider_error_detail": "PR (ntdat812) own growth: src/sse/services/auth.ts 3344->3346 (+2). One line is the import of describeUpstreamFailure from @/shared/utils/upstreamError, which replaces the string-only collapse `typeof errorText === \"string\" ? errorText.slice(0, 100) : \"Provider error\"` at the single markAccountUnavailable chokepoint (net 0 lines there) — the logic itself lives in upstreamError.ts, next to the extractErrorMessage it reuses, so nothing else moved into this file. The second line is the repo's own lint-staged prettier pass splitting a pre-existing two-statements-on-one-line at getProviderCredentials (`invalidateManagedLease(...); log.warn(...)`); it re-applies on any commit that touches this file, so it is not separable from the change. Covered by tests/unit/provider-error-detail-lastError.test.ts.",
"_rebaseline_2026_08_23_11186_synced_inventory_routing": "PR #11186 (pacocartones) own growth: src/sse/services/auth.ts 3260->3337 (+77, loadAdvertisedModelsForSelfHostedConnections + the modelNotAdvertised candidate-filter predicate — pins chat routing to the connection whose synced inventory actually advertises the model, fixing spurious model-not-found on multi-host self-hosted setups; at the existing credential-selection chokepoint, not extractable without splitting the selection flow). Covered by tests/unit/chat-routing-synced-inventory-11089.test.ts. Owner pre-authorized baseline bumps 2026-08-22.",
"tests/unit/account-fallback-service.test.ts": 2044,
"tests/unit/provider-validation-specialty.test.ts": 3880,
@@ -472,7 +475,10 @@
"_rebaseline_2026_08_21_10907_sticky_pin_clear": "#10907 own growth: open-sse/executors/commandCode.ts 1023->1038 (+15, effort-suffix sanitization threading for the sticky-pin-clear fix). Cohesive change at the existing executor chokepoint. Covered by tests/unit/command-code-executor.test.ts.",
"_rebaseline_2026_08_21_10986_reasoning_only_content": "#10986 own growth: open-sse/executors/commandCode.ts 1038->1059 (+21, reasoning-only content fallback — when upstream emits only reasoning-delta events and never a text-delta, surface the reasoning text as message.content in createJsonResponse and emit a synthetic content delta in createStreamResponse). Cohesive bug fix at the existing executor chokepoint (mirrors precedent style of #10907/#10859). Covered by tests/unit/command-code-executor.test.ts (2 new cases: non-stream + streaming).",
"_rebaseline_2026_08_21_11069_m365_har_import": "#11069 own growth: AddApiKeyModal.tsx 1073->1080 (+7 = Import .har file button for the copilot-m365-web credential modal — M365 is the only provider whose credential (access_token+chathubPath) must be extracted from a DevTools HAR WebSocket URL, added as a new modal affordance). Cohesive UI at the existing modal chokepoint; not extractable. Covered by tests/unit/m365-har-import*.test.ts.",
- "_rebaseline_2026_08_23_tip_drift_post_batch0823": "Tip drift after the 2026-08-23 merge wave: chatBodyAdmission.ts 1009->1118 (+109, gate count incl. +1) and auth.ts 3337->3344 (+7), both grown by merges already on origin/release/v3.8.50 (verified identical on the pristine tip) — not by the codex-appserver-hardening PR that carries this bump. Owner pre-authorized baseline bumps 2026-08-22."
+ "_rebaseline_2026_08_23_tip_drift_post_batch0823": "Tip drift after the 2026-08-23 merge wave: chatBodyAdmission.ts 1009->1118 (+109, gate count incl. +1) and auth.ts 3337->3344 (+7), both grown by merges already on origin/release/v3.8.50 (verified identical on the pristine tip) — not by the codex-appserver-hardening PR that carries this bump. Owner pre-authorized baseline bumps 2026-08-22.",
+ "_rebaseline_2026_08_24_11355_cooldown_recovery_guards": "PR #11355 own growth: test/route.ts 1215->1237, +22 (startup crash-recovery guard: clearStaleCrashCooldowns() now parses the persisted rate_limited_until deadline and skips clearing rows still genuinely in the future, instead of clearing every non-terminal cooldown unconditionally). Cohesive fix at the existing test-route dispatch chokepoint alongside the #11141 probe builder. Covered by tests/unit/startup-stale-cooldown-recovery.test.ts + tests/unit/repro-zai-cooldown-cleared-by-connection-test.test.ts.",
+ "src/lib/guardrails/videoBridgeRuntime.ts": 1009,
+ "_rebaseline_2026_08_24_video_bridge_fu02_fu07_sampler": "PRs #11344 (FU-02 one-frame scene-aware determinism) + #11381 (FU-07 opt-in segment_aware structural sampling) own growth: videoBridgeRuntime.ts <1000->1009, +9 (sum of both boarded together in the same merge-batch). #11344 adds the deterministic one-frame midpoint fallback + policyEffective=uniform report at the existing scene_aware seam; #11381 adds the bounded local-only FFmpeg structural pre-analysis pass (scene/freeze/blur/exposure/SI-TI) and its budget-reallocation logic. Covered by tests/unit/guardrails/videoBridgeSampler.test.ts, tests/unit/guardrails/videoBridgeFu07StructuralSampling.test.ts, tests/integration/video-bridge-sampler-ffmpeg.test.ts. Owner pre-authorized rebaseline for legitimate PR growth (2026-08-19 directive)."
},
"_rebaseline_base_2026_08_10_proxyfetch": "Base-red fix (green-prs sweep, issue #9985): open-sse/utils/proxyFetch.ts 1207 > cap 1000 — new proxied-TLS fetch helper introduced by the Fal reference-image work. Owner-authorized quick rebaseline to green; structural slim tracked for v3.9.0.",
"_rebaseline_2026_07_27_v3849_train2": "Merge-train 2 (7 PRs) — owner-approved 2026-07-27. Single entry: chatCore.ts 4955->5006 (#8595, Responses multi-turn image compaction before the context hard-reject). Genuine irreducible growth at the existing compaction chokepoint in handleChatCore — the PR adds a last-resort retry against the concrete budget plus the estimateFinalInputTokens helper, both wired at the pre-existing call site rather than a new branch. Covered by tests/unit/8560-responses-image-compaction.test.ts (4 tests).",
diff --git a/config/release/changelog-reconciliations.json b/config/release/changelog-reconciliations.json
new file mode 100644
index 0000000000..db944ff34b
--- /dev/null
+++ b/config/release/changelog-reconciliations.json
@@ -0,0 +1,4 @@
+{
+ "schemaVersion": 1,
+ "reconciliations": []
+}
diff --git a/docs/architecture/AUTHZ_GUIDE.md b/docs/architecture/AUTHZ_GUIDE.md
index c12efe8c4c..911b1bd72c 100644
--- a/docs/architecture/AUTHZ_GUIDE.md
+++ b/docs/architecture/AUTHZ_GUIDE.md
@@ -108,24 +108,48 @@ A successful policy returns `AuthSubject` with `kind ∈ { client_api_key, dashb
`src/shared/constants/publicApiRoutes.ts` is the explicit allowlist:
+The list is split by **shape**, and the split is load-bearing (GHSA-74g9-q8f6-793h): a prefix is
+matched with `startsWith()`, so it also matches every adjacent path sharing its leading characters.
+`/api/usage/om-usage` as a prefix marked `/api/usage/om-usage` PUBLIC, and Next resolves
+that to `/api/usage/[connectionId]` — a handler with no auth of its own.
+
```ts
+// Genuine subtrees. Every entry MUST end in "/" (asserted by a unit test).
PUBLIC_API_ROUTE_PREFIXES = [
+ "/api/auth/oidc/",
+ "/api/v1/", // treated as CLIENT_API in classify, not as "no-auth public"
+ "/api/oauth/",
+ "/api/codex/connect/",
+ "/api/telegram/",
+ "/api/cursor-cli/",
+];
+
+// Single routes, matched EXACTLY (with or without a trailing slash).
+PUBLIC_API_ROUTES_EXACT = new Set([
"/api/auth/login",
"/api/auth/logout",
"/api/auth/status",
"/api/init",
- "/api/v1/", // treated as CLIENT_API in classify, not as "no-auth public"
- "/api/cloud/",
"/api/sync/bundle",
- "/api/oauth/",
+ "/api/cli/connect",
+ "/api/usage/om-usage",
+ "/api/skills/collect/chaos",
+]);
+
+// Read-only single routes that also take the CORS origin relaxation.
+PUBLIC_READONLY_CORS_API_ROUTES = [
+ "/api/health/ping",
+ "/api/monitoring/health",
+ "/api/settings/require-login",
];
-PUBLIC_READONLY_API_ROUTE_PREFIXES = ["/api/monitoring/health", "/api/settings/require-login"];
+// Read-only single route WITHOUT the CORS relaxation.
+PUBLIC_READONLY_API_ROUTES_EXACT = new Set(["/api/health"]);
PUBLIC_READONLY_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
```
-Read-only prefixes are public **only** for safe methods. Note: `classifyRoute()` excludes `/api/v1/*` and `/api/v1beta/*` from the PUBLIC fall-through — those are always `CLIENT_API` so the Bearer-key policy still applies.
+Read-only routes are public **only** for safe methods. Note: `classifyRoute()` excludes `/api/v1/*` and `/api/v1beta/*` from the PUBLIC fall-through — those are always `CLIENT_API` so the Bearer-key policy still applies.
## Adding a New Route
@@ -168,7 +192,7 @@ export async function POST(request: Request) {
### Pattern 3 — Adding to the public allowlist
-Add the prefix to `PUBLIC_API_ROUTE_PREFIXES` (or `PUBLIC_READONLY_API_ROUTE_PREFIXES` for GET-only). Update unit tests at `tests/unit/public-api-routes.test.ts` and `tests/unit/authz/classify.test.ts`.
+Pick the set by shape, not by convenience. One route goes in `PUBLIC_API_ROUTES_EXACT` (or `PUBLIC_READONLY_CORS_API_ROUTES` for GET-only); only a genuine subtree goes in `PUBLIC_API_ROUTE_PREFIXES`, and it **must end in `/`**. Putting a single route in the prefix list also publishes every adjacent path that shares its leading characters — including dynamic-segment siblings added later (GHSA-74g9-q8f6-793h). Update unit tests at `tests/unit/public-api-routes.test.ts`, `tests/unit/authz/public-route-exact-match.test.ts` and `tests/unit/authz/classify.test.ts`.
## Scopes
diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md
index 7b6fd18f9a..ccd553555c 100644
--- a/docs/diagrams/README.md
+++ b/docs/diagrams/README.md
@@ -16,7 +16,7 @@ Mermaid sources (`.mmd`) and exported SVGs for OmniRoute v3.8.0 architecture flo
| [auto-combo-12factor.mmd](./auto-combo-12factor.mmd) | [SVG](./exported/auto-combo-12factor.svg) | docs/routing/AUTO-COMBO.md |
| [resilience-3layers.mmd](./resilience-3layers.mmd) | [SVG](./exported/resilience-3layers.svg) | docs/architecture/RESILIENCE_GUIDE.md, CLAUDE.md |
| [i18n-flow.mmd](./i18n-flow.mmd) | [SVG](./exported/i18n-flow.svg) | docs/guides/I18N.md |
-| [mcp-tools-107.mmd](./mcp-tools-107.mmd) | [SVG](./exported/mcp-tools-107.svg) | docs/frameworks/MCP-SERVER.md |
+| [mcp-tools-107.mmd](./mcp-tools-107.mmd) | [SVG](./exported/mcp-tools-107.svg) | docs/frameworks/MCP-SERVER.md |
| [cloud-agent-flow.mmd](./cloud-agent-flow.mmd) | [SVG](./exported/cloud-agent-flow.svg) | docs/frameworks/CLOUD_AGENT.md |
| [authz-pipeline.mmd](./authz-pipeline.mmd) | [SVG](./exported/authz-pipeline.svg) | docs/architecture/AUTHZ_GUIDE.md |
| [db-schema-overview.mmd](./db-schema-overview.mmd) | [SVG](./exported/db-schema-overview.svg) | docs/architecture/CODEBASE_DOCUMENTATION.md |
@@ -34,11 +34,11 @@ inside GitHub's `` sandbox:
| [combo-always-on.svg](./combo-always-on.svg) | style reference | Animated priority-combo fallback (4 layers, 16s loop). Edit the SVG directly — there is no `.mmd` source. |
| [cli-terminal.svg](./cli-terminal.svg) | README.md (root) | Compact half-height animated terminal (1200×350): 3 real CLI commands cycling with typewriter + scrolling subcommand ticker; first frame = completed providers screen. Edit the SVG directly — there is no `.mmd` source. |
| [compression-pipeline.svg](./compression-pipeline.svg) | README.md (root) | Animated 10-engine compression funnel (8s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [free-tier-budget.svg](./free-tier-budget.svg) | README.md (root) | Animated free-tier budget card (~1.53B/mo quantified headline, 19-pool budget bar, per-model grid, signup credits, 10s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [readme-hero.svg](./readme-hero.svg) | README.md (root) | Animated hero card (tagline, live provider/free-access headline, full-width compression bar demo, 6 stat chips). Edit the SVG directly — there is no `.mmd` source. |
+| [free-tier-budget.svg](./free-tier-budget.svg) | README.md (root) | Animated free-tier budget card (~1.51B/mo quantified headline, 20-pool budget bar, per-pool grid, signup credits, 10s loop). Edit the SVG directly — there is no `.mmd` source. |
+| [readme-hero.svg](./readme-hero.svg) | README.md (root) | Animated hero card (tagline, live provider/free-access headline, full-width compression bar demo, 6 stat chips). Edit the SVG directly — there is no `.mmd` source. |
| [promise-pillars.svg](./promise-pillars.svg) | README.md (root) | Animated "The Promise" 6-pillar card (12s border-highlight sweep). Edit the SVG directly — there is no `.mmd` source. |
| [why-pain-fix.svg](./why-pain-fix.svg) | README.md (root) | Animated "Why OmniRoute" 10-row pain-vs-fix ledger (15s green row sweep). Edit the SVG directly — there is no `.mmd` source. |
-| [strategies-grid.svg](./strategies-grid.svg) | README.md (root) | Animated grid illustrating 18 of the 19 routing strategies; `cache-optimized` remains documented in the adjacent table. Edit the SVG directly — there is no `.mmd` source. |
+| [strategies-grid.svg](./strategies-grid.svg) | README.md (root) | Animated grid illustrating 18 of the 19 routing strategies; `cache-optimized` remains documented in the adjacent table. Edit the SVG directly — there is no `.mmd` source. |
| [privacy-local.svg](./privacy-local.svg) | README.md (root) | Animated "Private & Local-First" 11-row guarantee ledger with receipt chips (16s green row sweep). Edit the SVG directly — there is no `.mmd` source. |
| [resilience-layers.svg](./resilience-layers.svg) | README.md (root) | Animated 3-layer resilience card (breaker states CLOSED→OPEN→HALF-OPEN, key cooldown with ×2 backoff, model lockout — 18s loops). Edit the SVG directly — there is no `.mmd` source. |
diff --git a/docs/diagrams/auto-combo-12factor.mmd b/docs/diagrams/auto-combo-12factor.mmd
index 3c7f967534..a5e54711ee 100644
--- a/docs/diagrams/auto-combo-12factor.mmd
+++ b/docs/diagrams/auto-combo-12factor.mmd
@@ -1,24 +1,28 @@
-%% Auto-Combo 13-factor scoring
+%% Auto-Combo 15-factor scoring
%% Reflects: open-sse/services/autoCombo/scoring.ts (DEFAULT_WEIGHTS, sum = 1.0)
-%% v3.8.49
+%% v3.8.50
+%% svg-title: OmniRoute Auto-Combo 15-factor scoring
+%% svg-description: Flow from an incoming request through eligible candidates, the 15 weighted scoring factors, descending score sort, top-N selection, and sequential dispatch.
flowchart TB
Request["Incoming request"] --> Candidates["Eligible candidates (provider × model × account)"]
Candidates --> Score["Compute composite score per candidate"]
- subgraph Factors["13-factor scoring weights (sum = 1.0)"]
- f1["health (0.20)"]
- f2["quota (0.15)"]
- f3["costInv (0.15)"]
- f4["latencyInv (0.12)"]
- f5["taskFit (0.08)"]
- f6["stability (0.05)"]
- f7["tierPriority (0.05)"]
- f8["tierAffinity (0.05)"]
- f9["specificityMatch (0.05)"]
- f10["contextAffinity (0.05)"]
- f11["connectionDensity (0.05)"]
- f12["cacheAffinity (0.00)"]
- f13["resetWindowAffinity (0.00)"]
+ subgraph Factors["15-factor scoring weights (sum = 1.0)"]
+ f1["quota (0.1429)"]
+ f2["health (0.1605)"]
+ f3["costInv (0.1429)"]
+ f4["latencyInv (0.1143)"]
+ f5["taskFit (0.0762)"]
+ f6["stability (0.0476)"]
+ f7["tierPriority (0.0476)"]
+ f8["tierAffinity (0.0476)"]
+ f9["specificityMatch (0.0476)"]
+ f10["contextAffinity (0.0476)"]
+ f11["cacheAffinity (0.0000)"]
+ f12["sessionAvailability (0.0476)"]
+ f13["resetWindowAffinity (0.0000)"]
+ f14["connectionDensity (0.0476)"]
+ f15["quality (0.0300)"]
end
Score --> Factors
diff --git a/docs/diagrams/cli-terminal.svg b/docs/diagrams/cli-terminal.svg
index 3a8d056e5c..1a2f50bd9e 100644
--- a/docs/diagrams/cli-terminal.svg
+++ b/docs/diagrams/cli-terminal.svg
@@ -1,12 +1,12 @@
-
diff --git a/docs/diagrams/comparison-table.svg b/docs/diagrams/comparison-table.svg
index 24018c7fed..fbbef865f5 100644
--- a/docs/diagrams/comparison-table.svg
+++ b/docs/diagrams/comparison-table.svg
@@ -23,7 +23,7 @@
Providers
- 338
+ 35040+400+*~5
@@ -57,7 +57,7 @@
Built-in MCP server (own tools)
- 109
+ 110
diff --git a/docs/diagrams/exported/auto-combo-12factor.svg b/docs/diagrams/exported/auto-combo-12factor.svg
index d0f2e00d7c..7f165626c3 100644
--- a/docs/diagrams/exported/auto-combo-12factor.svg
+++ b/docs/diagrams/exported/auto-combo-12factor.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/diagrams/free-tier-budget.svg b/docs/diagrams/free-tier-budget.svg
index 393ee00594..b96da3272d 100644
--- a/docs/diagrams/free-tier-budget.svg
+++ b/docs/diagrams/free-tier-budget.svg
@@ -1,4 +1,5 @@
-
@@ -91,7 +91,7 @@
Every tool works
- 33 coding agents — Claude Code, Codex,
+ 35 CLI/agent integrations — Claude Code, Codex,Cursor, Cline, Copilot, Antigravity —through one config.
@@ -127,7 +127,7 @@
Production-gradeCircuit breakers, TLS stealth, MCP (110tools), A2A, memory, guardrails, evals —
- 25,000+ tests.
+ 39,000+ static test declarations.
diff --git a/docs/diagrams/readme-hero.svg b/docs/diagrams/readme-hero.svg
index e3faa34758..52e4d168db 100644
--- a/docs/diagrams/readme-hero.svg
+++ b/docs/diagrams/readme-hero.svg
@@ -66,7 +66,7 @@
- 338
+ 350AI PROVIDERS90+
diff --git a/docs/diagrams/resilience-layers.svg b/docs/diagrams/resilience-layers.svg
index 022e35f365..369277e0fb 100644
--- a/docs/diagrams/resilience-layers.svg
+++ b/docs/diagrams/resilience-layers.svg
@@ -17,6 +17,6 @@
The right layer for the right failure — never kill more than what actually broke.PROVIDERCONNECTION / KEYMODEL
- LAYER 1 · SCOPE: WHOLE PROVIDERProvider circuit breakerisolate a provider failing upstream —reroute now, auto-probe to recovertrips only on 408 · 500 · 502 · 503 · 504threshold — oauth 3× · api-key 5× · local 2×reset — 60s · 30s · 15s → HALF-OPEN probelazy recovery — reads refresh expired staterouterprovider Afails ×15provider B ← nextCLOSEDOPENHALF-OPENLAYER 2 · SCOPE: ONE KEY / ACCOUNTConnection cooldownskip one rate-limited key while theother keys keep serving the providerbase cooldown — oauth 5s · api-key 3srepeat fails — backoff ×2 (anti-herd guard)429 honors Retry-After / reset headerssuccess → clearAccountError() resets allprovider · 3 keyskey-1429key-2key-3cooling ×2ⁿLAYER 3 · SCOPE: ONE MODELModel lockoutquarantine a single model — never killthe whole connection for one 429scope — provider + connection + modelper-model 429 · local 404 · mode denialslocked model ≠ dead keyother models keep serving instantlykey-1model-amodel-bmodel-c
+ LAYER 1 · SCOPE: WHOLE PROVIDERProvider circuit breakerisolate a provider failing upstream —reroute now, auto-probe to recovertrips only on 408 · 500 · 502 · 503 · 504threshold — oauth 10× · api-key 15× · local 2×reset — 60s · 30s · 15s → HALF-OPEN probelazy recovery — reads refresh expired staterouterprovider Afails ×15provider B ← nextCLOSEDOPENHALF-OPENLAYER 2 · SCOPE: ONE KEY / ACCOUNTConnection cooldownskip one rate-limited key while theother keys keep serving the providerbase cooldown — oauth 5s · api-key 3srepeat fails — backoff ×2 (anti-herd guard)429 honors Retry-After / reset headerssuccess → clearAccountError() resets allprovider · 3 keyskey-1429key-2key-3cooling ×2ⁿLAYER 3 · SCOPE: ONE MODELModel lockoutquarantine a single model — never killthe whole connection for one 429scope — provider + connection + modelper-model 429 · local 404 · mode denialslocked model ≠ dead keyother models keep serving instantlykey-1model-amodel-bmodel-cwhich failure trips what → 5xx / 408 : breaker · key 429 / 401 : cooldown · one-model 429 / 404 : lockout · banned / expired / credits : terminal (operator)
\ No newline at end of file
diff --git a/docs/diagrams/strategies-grid.svg b/docs/diagrams/strategies-grid.svg
index d518f85d06..1706f36e7e 100644
--- a/docs/diagrams/strategies-grid.svg
+++ b/docs/diagrams/strategies-grid.svg
@@ -95,7 +95,7 @@
auto72916455
-live 13-factor scoring
+live 15-factor scoringfusion
diff --git a/docs/getting-started/FREE-TIERS-GUIDE.md b/docs/getting-started/FREE-TIERS-GUIDE.md
index 6fd9dcc35b..400343affe 100644
--- a/docs/getting-started/FREE-TIERS-GUIDE.md
+++ b/docs/getting-started/FREE-TIERS-GUIDE.md
@@ -1,6 +1,6 @@
# Free Tiers Guide: Understand and Combine Free AI Access
-> **TL;DR**: OmniRoute registers 329 providers, with **155 catalog entries marked free/no-auth**. The stricter audited budget currently covers **43 recurring pools / 522 model budget entries**. Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
+> **TL;DR**: OmniRoute registers 350 provider IDs, with **154 provider-catalog entries marked `hasFree`**. The stricter audited free-model catalog covers **40 recurring pool keys / 455 entries** (448 active + 7 discontinued). Connect several suitable providers for broader fallback capacity; every quota, approval rule, privacy policy, and paid-overage condition still applies.
---
@@ -21,38 +21,38 @@ OmniRoute **aggregates** these free tiers into one endpoint. Instead of signing
These providers have a recurring, keyless, or uncapped free-access path in the audited catalog. “Uncapped” means no published token cap; rate, concurrency, account, regional, and policy limits can still apply:
-| Provider | Models | Quota | How to Connect |
-|----------|--------|-------|----------------|
-| **Kiro AI** | Claude Sonnet 4.5, Haiku 4.5, DeepSeek V3.2, and others | Audited catalog estimates a 25K-token shared monthly pool | OAuth/account flow; ToS flagged `avoid` in the catalog |
-| **OpenCode Free** | Current `*-free` model set in the provider registry | Keyless; no published token cap | No provider credential; ToS flagged `avoid` |
-| **Pollinations** | Current keyless model set; some former models are discontinued or key-required | Keyless; no published token cap | No provider credential for the keyless models |
-| **Logfare** | kimi-k3, deepseek-v4-pro, glm-5.2, gpt-5.6-luna, minimax-m3, and more | Free API key (no rate limits, no card); **every request is logged** for research (opt out at logfare.ai/consent) | Instant key at logfare.ai/register; ToS/privacy at logfare.ai/tos and logfare.ai/privacy |
-| **Cloudflare AI** | Workers AI catalog | Audited pool estimates ~30M tokens/month from published usage units | Cloudflare account and API credentials |
-| **Gemini** | Gemini Flash family | Audited pool estimates ~60M tokens/month | Google AI Studio API key; rate limits apply |
-| **Groq** | Llama, GPT-OSS, and Qwen models | Audited pool estimates ~15M tokens/month | Groq API key; rate limits apply |
-| **Cerebras** | GLM 4.7 and GPT-OSS 120B | Audited pool estimates ~30M tokens/month | Cerebras API key; rate limits apply |
+| Provider | Models | Quota | How to Connect |
+| ----------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Kiro AI** | Claude Sonnet 4.5, Haiku 4.5, DeepSeek V3.2, and others | Audited catalog estimates a 25K-token shared monthly pool | OAuth/account flow; ToS flagged `avoid` in the catalog |
+| **OpenCode Free** | Current `*-free` model set in the provider registry | Keyless; no published token cap | No provider credential; ToS flagged `avoid` |
+| **Pollinations** | Current keyless model set; some former models are discontinued or key-required | Keyless; no published token cap | No provider credential for the keyless models |
+| **Logfare** | kimi-k3, deepseek-v4-pro, glm-5.2, gpt-5.6-luna, minimax-m3, and more | Free API key (no rate limits, no card); **every request is logged** for research (opt out at logfare.ai/consent) | Instant key at logfare.ai/register; ToS/privacy at logfare.ai/tos and logfare.ai/privacy |
+| **Cloudflare AI** | Workers AI catalog | Audited pool estimates ~30M tokens/month from published usage units | Cloudflare account and API credentials |
+| **Gemini** | Gemini Flash family | Audited pool estimates ~60M tokens/month | Google AI Studio API key; rate limits apply |
+| **Groq** | Llama, GPT-OSS, and Qwen models | Audited pool estimates ~15M tokens/month | Groq API key; rate limits apply |
+| **Cerebras** | GLM 4.7 and GPT-OSS 120B | Audited pool estimates ~30M tokens/month | Cerebras API key; rate limits apply |
### Signup Grants and Provider-Specific Credits
These providers give you **free credits** when you sign up:
-| Provider | Free Credits | Models | How to Get |
-|----------|-------------|--------|------------|
-| **DeepSeek** | 5M free tokens | DeepSeek V4 | Sign up at platform.deepseek.com |
-| **LongCat** | 10M-token one-time grant | LongCat 2.0 | API key + KYC; pay-as-you-go after the grant |
-| **Together** | $25 signup credit represented as ~25M tokens in the budget model | Provider catalog | Sign up and verify current terms |
+| Provider | Free Credits | Models | How to Get |
+| ------------- | ------------------------------------------------------------------ | ------------------------- | --------------------------------------------------------- |
+| **DeepSeek** | 5M free tokens | DeepSeek V4 | Sign up at platform.deepseek.com |
+| **LongCat** | 10M-token one-time grant | LongCat 2.0 | API key + KYC; pay-as-you-go after the grant |
+| **Together** | $25 signup credit represented as ~25M tokens in the budget model | Provider catalog | Sign up and verify current terms |
| **Vertex AI** | $300 signup credit represented as ~300M tokens in the budget model | Gemini and partner models | Google Cloud account; billing and eligibility rules apply |
### Other Limited Access
These providers have **free tiers** with specific limits:
-| Provider | Free Limit | Models | Best For |
-|----------|-----------|--------|----------|
-| **GitHub Models** | Audited shared pool estimates ~18M tokens/month | Broad model evaluation |
-| **Hugging Face** | Small recurring monthly pool | Experiments and model variety |
-| **OpenRouter free models** | Shared request-limited pool; optional one-time top-up increases the recurring allowance | Broad fallback catalog |
-| **AI Horde** | Keyless community capacity; availability varies | Opportunistic distributed inference |
+| Provider | Free Limit | Models | Best For |
+| -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | -------- |
+| **GitHub Models** | Audited shared pool estimates ~18M tokens/month | Broad model evaluation |
+| **Hugging Face** | Small recurring monthly pool | Experiments and model variety |
+| **OpenRouter free models** | Shared request-limited pool; optional one-time top-up increases the recurring allowance | Broad fallback catalog |
+| **AI Horde** | Keyless community capacity; availability varies | Opportunistic distributed inference |
---
@@ -70,6 +70,7 @@ Connect several providers to reduce dependence on any single quota:
4. **LongCat** — one-time signup grant (requires KYC)
Then use `model: "auto"` and OmniRoute will:
+
- Try the highest-ranked eligible connection first
- If its quota or health check fails → try the next configured provider
- If the keyless provider is unavailable → continue through the remaining targets
@@ -135,6 +136,7 @@ If one free provider is busy or down, OmniRoute automatically tries the next one
### 2. Smart Routing
OmniRoute picks the **best free provider** for each request based on:
+
- Speed — Which provider is fastest right now?
- Quality — Which provider is best for this task?
- Capacity — Which provider has quota remaining?
@@ -157,13 +159,13 @@ provider's quota or access policy.
The live, pool-deduplicated catalog currently reports:
-| Metric | Current audited value | Interpretation |
-| --- | ---: | --- |
-| Recurring quantified grant | **~1.53B tokens/month** | Shared pools counted once; excludes uncapped providers from the sum |
-| First month with signup grants | **~2.15B tokens** | Recurring total plus one-time and recurring credits |
-| Quantified inventory | **43 pools / 522 model budget entries** | Budget-model coverage, not the full 329-provider catalog |
-| Recurring/keyless/uncapped providers represented | **58** | Provider presence in recurring forms of the audited budget catalog |
-| Free/no-auth discovery entries | **155** | Broader provider metadata; not all have a quantifiable recurring quota |
+| Metric | Current audited value | Interpretation |
+| ---------------------------------------------------- | -----------------------------------------------: | ----------------------------------------------------------------------------------------- |
+| Recurring quantified grant | **~1.51B tokens/month** | Shared pools counted once; excludes uncapped providers from the sum |
+| First month with signup grants | **~2.13B tokens** | Recurring total plus one-time and recurring credits |
+| Audited free-model inventory | **40 recurring pool keys / 455 catalog entries** | 448 active + 7 discontinued; distinct from the 350-provider catalog |
+| Recurring/keyless free-forever providers represented | **56** | Unique providers across recurring daily/monthly/credit/uncapped and keyless catalog types |
+| Provider catalog entries marked `hasFree` | **154 / 350** | Broader provider metadata; not all have a quantifiable recurring quota |
These values are computed from `open-sse/config/freeModelCatalog.ts`; see the
[Free Tiers Reference](../reference/FREE_TIERS.md) for pool deduplication, ToS flags,
diff --git a/docs/guides/DOCKER_GUIDE.md b/docs/guides/DOCKER_GUIDE.md
index b24e7b7f61..5c650df5da 100644
--- a/docs/guides/DOCKER_GUIDE.md
+++ b/docs/guides/DOCKER_GUIDE.md
@@ -219,13 +219,23 @@ docker build --target runner-cli -t omniroute:cli .
### Build-time resources
-Two build args control what the `builder` stage costs. They are build-time only —
+Three build args control what the `builder` stage costs. They are build-time only —
`OMNIROUTE_MEMORY_MB` (below) is a separate, runtime knob.
-| Build arg | Default | Effect |
-| --------------------------- | ------- | ---------------------------------------------------------------------- |
-| `OMNIROUTE_USE_TURBOPACK` | `1` | `0` builds with webpack instead. Lower peak memory, slower. |
-| `OMNIROUTE_BUILD_MEMORY_MB` | `4096` | V8 heap ceiling (`--max-old-space-size`) for the spawned `next build`. |
+| Build arg | Default | Effect |
+| --------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `OMNIROUTE_USE_TURBOPACK` | `1` | `0` builds with webpack instead. Lower peak memory, slower. |
+| `OMNIROUTE_BUILD_MEMORY_MB` | `6144` | V8 heap ceiling (`--max-old-space-size`) for the spawned `next build`. |
+| `OMNIROUTE_BUILD_WORKERS` | `3` | Feeds `CIRCLE_NODE_TOTAL`; Next derives `workers = N - 1` for page-data collection. |
+
+`OMNIROUTE_BUILD_WORKERS` is the one to raise on a big builder and the one to
+suspect when a constrained build dies **after** `✓ Compiled successfully`. Each
+page-data worker is its own process and inherits `NODE_OPTIONS`, so the heap
+ceiling is per process, not per build: the default of `3` (→ 2 workers) is sized
+for the 16 GB / 4 vCPU GitHub-hosted runners the publish pipeline uses. At `8`
+(→ 7 workers) that runner ran out of memory and buildkit failed the step with
+`ResourceExhausted: ... cannot allocate memory`. `tests/unit/docker-build-memory-budget.test.ts`
+does the arithmetic and fails if either knob outgrows the runner.
Turbopack compiles in native Rust memory that lives **outside** the V8 heap, so
`OMNIROUTE_BUILD_MEMORY_MB` does not bound it. On a host with a memory ceiling the
@@ -268,12 +278,12 @@ The 1 GiB Docker default is a dashboard/light-chat floor, not a production siz
Size **cgroup `--memory` above the heap** — native buffers, SQLite, and compression intermediates sit outside V8.
-| Workload | `OMNIROUTE_MEMORY_MB` | Container / cgroup | Notes |
-| --- | --- | --- | --- |
-| Dashboard, one light chat | `1024` (image default) | ≥2 GiB | |
-| One coding agent (Claude/Codex/Grok) | `8192` | ≥10 GiB | Typical single-session `/v1/responses` |
-| Two concurrent long `/v1/responses` | `10240`–`12288` | ≥12–16 GiB | Measured V8 abort at ~12 GiB heap |
-| Three+ concurrent long contexts | do not on one process | serialize / more RAM | Default heavyweight admission is 1 in-flight; raising it without RAM reintroduces the abort |
+| Workload | `OMNIROUTE_MEMORY_MB` | Container / cgroup | Notes |
+| ------------------------------------ | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| Dashboard, one light chat | `1024` (image default) | ≥2 GiB | |
+| One coding agent (Claude/Codex/Grok) | `8192` | ≥10 GiB | Typical single-session `/v1/responses` |
+| Two concurrent long `/v1/responses` | `10240`–`12288` | ≥12–16 GiB | Measured V8 abort at ~12 GiB heap |
+| Three+ concurrent long contexts | do not on one process | serialize / more RAM | Default heavyweight admission is 1 in-flight; raising it without RAM reintroduces the abort |
`omniroute serve` on bare metal calibrates ~35% of RAM (clamped `[512, 4096]`) when `OMNIROUTE_MEMORY_MB` is **unset**. Docker always sets `1024`, so that calibration never runs in the official image.
@@ -287,19 +297,19 @@ docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
Beyond the defaults documented in [ENVIRONMENT.md](../reference/ENVIRONMENT.md), the following variables matter most when running under Docker:
-| Variable | Purpose | Default |
-| ----------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------ |
-| `OMNIROUTE_WS_BRIDGE_SECRET` | Shared secret for the WebSocket bridge. **Required in production** — set to a strong random string. | unset (must be provided) |
-| `REDIS_URL` | Connection string for the rate limiter / cache backend | `redis://redis:6379` |
-| `REDIS_PORT` | Host-side port for the bundled Redis container | `6379` |
-| `REDIS_BIND_HOST` | Host interface the bundled Redis port is published on (loopback unless you add AUTH) | `127.0.0.1` |
-| `AUTO_UPDATE_HOST_REPO_DIR` | Host path mounted into `cli` profile at `/workspace/omniroute` for self-update workflows | `.` (current directory) |
+| Variable | Purpose | Default |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `OMNIROUTE_WS_BRIDGE_SECRET` | Shared secret for the WebSocket bridge. **Required in production** — set to a strong random string. | unset (must be provided) |
+| `REDIS_URL` | Connection string for the rate limiter / cache backend | `redis://redis:6379` |
+| `REDIS_PORT` | Host-side port for the bundled Redis container | `6379` |
+| `REDIS_BIND_HOST` | Host interface the bundled Redis port is published on (loopback unless you add AUTH) | `127.0.0.1` |
+| `AUTO_UPDATE_HOST_REPO_DIR` | Host path mounted into `cli` profile at `/workspace/omniroute` for self-update workflows | `.` (current directory) |
| `OMNIROUTE_MEMORY_MB` | Runtime Node heap ceiling for the Docker standalone server; overrides the image default above. Coding agents: `8192`+ (see [runtime RAM](#runtime-ram-for-coding-agents)). | `1024` |
-| `DASHBOARD_PORT` / `API_PORT` | Override exposed ports for dashboard (20128) and API (20129) | `20128` / `20129` |
-| `OMNIROUTE_BASE_PATH` | URL subpath when the app is published behind a reverse proxy (e.g. `/omniroute`) | _(empty = root)_ |
-| `NEXT_PUBLIC_BASE_URL` | Public browser origin including the subpath (e.g. `https://host/omniroute`) | unset |
-| `PROD_DASHBOARD_PORT` | Host-side dashboard port for `docker-compose.prod.yml` | `20130` |
-| `CLIPROXYAPI_PORT` | Host-side port for the `cliproxyapi` sidecar | `8317` |
+| `DASHBOARD_PORT` / `API_PORT` | Override exposed ports for dashboard (20128) and API (20129) | `20128` / `20129` |
+| `OMNIROUTE_BASE_PATH` | URL subpath when the app is published behind a reverse proxy (e.g. `/omniroute`) | _(empty = root)_ |
+| `NEXT_PUBLIC_BASE_URL` | Public browser origin including the subpath (e.g. `https://host/omniroute`) | unset |
+| `PROD_DASHBOARD_PORT` | Host-side dashboard port for `docker-compose.prod.yml` | `20130` |
+| `CLIPROXYAPI_PORT` | Host-side port for the `cliproxyapi` sidecar | `8317` |
## Reverse Proxy on a Subpath (Traefik / nginx)
@@ -361,11 +371,11 @@ intervals.
For orchestrators (Kubernetes, Nomad, etc.):
-| Probe | Prefer | Avoid |
-| --- | --- | --- |
-| Liveness | HTTP `GET /livez`, or TCP on the main port (`PORT`, default `20128`) | `/api/monitoring/health` as liveness |
-| Readiness | HTTP `GET /healthz` | Tight timeouts that treat event-loop busy as dead |
-| Deep / blackbox | `/api/monitoring/health` | — |
+| Probe | Prefer | Avoid |
+| --------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
+| Liveness | HTTP `GET /livez`, or TCP on the main port (`PORT`, default `20128`) | `/api/monitoring/health` as liveness |
+| Readiness | HTTP `GET /healthz` | Tight timeouts that treat event-loop busy as dead |
+| Deep / blackbox | `/api/monitoring/health` | — |
`/healthz` reports process lifecycle (`ok` / `starting` / `stopping`). `/livez` is
process-alive only (200 whenever the handler can run; it does not wait for
@@ -431,10 +441,10 @@ Endpoint tunnel panels (Cloudflare, Tailscale, ngrok) can be shown or hidden fro
## Image Tags
-| Image | Tag | Size | Description |
-| ------------------------ | -------- | ------ | --------------------- |
+| Image | Tag | Size | Description |
+| ------------------------ | -------- | ------ | ---------------------------------------------------- |
| `diegosouzapw/omniroute` | `latest` | ~250MB | Highest **published** stable SemVer (not git `main`) |
-| `diegosouzapw/omniroute` | `3.8.0` | ~250MB | Pin this class of tag for GitOps |
+| `diegosouzapw/omniroute` | `3.8.0` | ~250MB | Pin this class of tag for GitOps |
Multi-platform manifest: `linux/amd64` + `linux/arm64` native (Apple Silicon, AWS Graviton, Raspberry Pi). Docker selects the matching architecture automatically; pass `--platform linux/amd64` if you need to force AMD64 emulation on ARM hosts.
@@ -442,12 +452,12 @@ Multi-platform manifest: `linux/amd64` + `linux/arm64` native (Apple Silicon, AW
OmniRoute publishes separate Docker channels for stable releases, active release-branch testing, and development builds.
-| Channel | Source | Mutability | Recommended use |
-| ------------------------------- | ----------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
-| `:` / `:-web` | Signed/versioned release | Immutable | Production deployments that pin an exact release |
+| Channel | Source | Mutability | Recommended use |
+| ------------------------------- | ----------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `:` / `:-web` | Signed/versioned release | Immutable | Production deployments that pin an exact release |
| `:latest` / `:latest-web` | Highest **published** stable SemVer | Mutable stable pointer | Follows stable releases **after** a SemVer publish job — does **not** track `main` or unreleased `release/v*` commits |
-| `:next` / `:next-web` | Current default `release/v*` branch | Mutable pre-release pointer | Testing fixes that have landed on the active release branch but are not yet in a stable release |
-| `:main` / `:main-web` | `main` branch | Mutable development pointer | Development and integration testing only |
+| `:next` / `:next-web` | Current default `release/v*` branch | Mutable pre-release pointer | Testing fixes that have landed on the active release branch but are not yet in a stable release |
+| `:main` / `:main-web` | `main` branch | Mutable development pointer | Development and integration testing only |
#### Using the pre-release channel
@@ -491,30 +501,30 @@ A release-branch build can never move `latest`; only an eligible stable semantic
**`latest` is not a currency guarantee for git.** Merged fixes on `main` or on the active `release/v*` branch are **not** in `:latest` until a stable SemVer image is published and the publish job promotes `:latest` (same digest as that SemVer). If `latest` looks frozen while GitHub already shows the fix, pull `:next` to test the release branch or wait for the SemVer tag.
-| You want | Use |
-| --- | --- |
-| GitOps / production that must not drift | Pin `:X.Y.Z` (or the image digest) |
-| Follow published stables and accept a recreate on each release | `:latest` |
-| Test unreleased `release/v*` commits | `:next` (not production) |
-| Test `main` | `:main` (not production) |
+| You want | Use |
+| -------------------------------------------------------------- | ---------------------------------- |
+| GitOps / production that must not drift | Pin `:X.Y.Z` (or the image digest) |
+| Follow published stables and accept a recreate on each release | `:latest` |
+| Test unreleased `release/v*` commits | `:next` (not production) |
+| Test `main` | `:main` (not production) |
## Availability: default SQLite is single-replica
Stock Docker / Kubernetes OmniRoute is **one Node process + one SQLite writer**. High availability is **not supported** on that topology.
-| Constraint | Consequence |
-| --- | --- |
-| Single writer | Do **not** run multiple replicas against the same SQLite file. That corrupts the DB. |
+| Constraint | Consequence |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Single writer | Do **not** run multiple replicas against the same SQLite file. That corrupts the DB. |
| Recreate / restart / HEALTHCHECK kill | **Full outage** of in-flight SSE, dashboard sessions, and in-memory state. Every connected client drops. New requests during the empty-endpoint window get a reverse-proxy **`502 Bad Gateway: Unknown error`**, not OmniRoute JSON — clients cannot distinguish this from a provider failure (#11015). |
-| Same event loop as `/healthz` | A busy catalog or compression tick can delay probes; a short timeout then restarts the **only** replica. |
+| Same event loop as `/healthz` | A busy catalog or compression tick can delay probes; a short timeout then restarts the **only** replica. |
**Probe matrix** (see also [Kubernetes probe recommendations](../ops/MONITORING_GUIDE.md#kubernetes-probe-recommendations)):
-| Probe | Target | Do not use |
-| --- | --- | --- |
-| Liveness | TCP on `PORT` (default `20128`), or soft HTTP `/healthz` | `/api/monitoring/health` |
-| Readiness | HTTP `GET /healthz` | Tight timeouts that treat event-loop busy as dead |
-| Deep / humans | `/api/monitoring/health` | Automated kubelet liveness |
+| Probe | Target | Do not use |
+| ------------- | -------------------------------------------------------- | ------------------------------------------------- |
+| Liveness | TCP on `PORT` (default `20128`), or soft HTTP `/healthz` | `/api/monitoring/health` |
+| Readiness | HTTP `GET /healthz` | Tight timeouts that treat event-loop busy as dead |
+| Deep / humans | `/api/monitoring/health` | Automated kubelet liveness |
**Upgrades:** expect every session to drop. Drain clients if you can; there is no rolling update on default SQLite. Compose `restart: unless-stopped` plus Docker `HEALTHCHECK` will also replace the only process when the container is Unhealthy — same blast radius.
@@ -555,13 +565,13 @@ One Node process is **one V8 heap**. Two overlapping ~3 MiB / ~750k-token codi
To go beyond two concurrent **large** jobs **today**:
-| Do | Do not |
-| --- | --- |
-| Run **N containers/pods**, each with its **own** `DATA_DIR` / volume | Set `replicas > 1` against one SQLite file |
-| Keep each instance at 1–2 heavy in-flight and 12–16 Gi cgroup | Give one process 8× RAM and `max=8` |
-| Optional: `QUOTA_STORE_DRIVER=redis` + `QUOTA_STORE_REDIS_URL` for **shared quota counters** | Treat Redis as shared SQLite — it is not |
-| Duplicate provider secrets into each instance (or accept partitioned dashboards) | Expect one dashboard / one call-log across instances |
-| Front with any load balancer; sticky by API key or session is enough | Require a vendor-specific size-aware middleware |
+| Do | Do not |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Run **N containers/pods**, each with its **own** `DATA_DIR` / volume | Set `replicas > 1` against one SQLite file |
+| Keep each instance at 1–2 heavy in-flight and 12–16 Gi cgroup | Give one process 8× RAM and `max=8` |
+| Optional: `QUOTA_STORE_DRIVER=redis` + `QUOTA_STORE_REDIS_URL` for **shared quota counters** | Treat Redis as shared SQLite — it is not |
+| Duplicate provider secrets into each instance (or accept partitioned dashboards) | Expect one dashboard / one call-log across instances |
+| Front with any load balancer; sticky by API key or session is enough | Require a vendor-specific size-aware middleware |
Hardware: `concurrent_large ≈ N × 2` at ~8–12 Gi heap / ~12–16 Gi cgroup **per instance**. Host RAM must cover `N × cgroup`, not “one 16 Gi pod with N=8.”
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 540f2abd52..9fae13e631 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -5719,17 +5719,28 @@ paths:
x-loopback-only: true
tags: [System]
summary: Read a bounded Video Bridge drill-down slice
- description: Internal loopback/token-authenticated lookup into a short-lived per-session frame cache. It never downloads media or starts a subprocess; start/end and frame count only select already materialized frames.
+ description: Internal loopback/token-authenticated lookup into a short-lived cache isolated by an opaque principal, session, and media reference. It never downloads media or starts a subprocess; start/end and frame count only select already materialized, canonicalized JPEG frames whose dimensions were derived from their bytes. This cache substrate is not yet wired to the transparent Video Bridge request path and does not yet expose multi-resolution selection.
security: []
parameters:
+ - in: header
+ name: x-omniroute-video-bridge-principal
+ required: true
+ description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 256
+ pattern: "^[!-~]{1,256}$"
- in: query
name: sessionId
required: true
- schema: { type: string, maxLength: 128 }
+ description: Canonical opaque ID without surrounding whitespace
+ schema: { type: string, minLength: 1, maxLength: 128 }
- in: query
name: videoRef
required: true
- schema: { type: string, maxLength: 4096 }
+ description: Canonical opaque reference without surrounding whitespace
+ schema: { type: string, minLength: 1, maxLength: 4096 }
- in: query
name: start
required: false
@@ -5743,25 +5754,58 @@ paths:
required: false
schema: { type: integer, minimum: 1, maximum: 16 }
responses:
- "200": { description: Bounded cached frame slice }
- "403": { description: Trusted loopback/token identity required }
+ "200": { description: Bounded cached frame slice with derivation audit metadata }
+ "403": { description: Trusted loopback/token identity and principal required }
"404": { description: Drill-down session or media key was not found }
post:
x-loopback-only: true
tags: [System]
summary: Store a bounded Video Bridge drill-down result
- description: Internal lifecycle operation for explicitly authorized callers. The short-lived session cache is isolated by session and media reference and does not alter the primary request cost.
+ description: Internal lifecycle operation for explicitly authorized callers. The short-lived cache is isolated by principal, session, and media reference; enforces independent per-principal and global retained-byte quotas; accepts canonical Base64 only after a warning-sensitive bounded full JPEG decode/re-encode; strips trailing polyglot bytes; retains and charges only the canonical JPEG output; derives resolution from decoded bytes; and does not alter the primary request cost. The JSON wire budget includes Base64 overhead for the 32 MiB decoded-input ceiling.
security: []
+ parameters:
+ - in: header
+ name: x-omniroute-video-bridge-principal
+ required: true
+ description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 256
+ pattern: "^[!-~]{1,256}$"
requestBody:
required: true
content:
application/json:
schema:
type: object
- required: [sessionId, videoRef, durationSeconds, frames]
+ additionalProperties: false
+ required: [sessionId, videoRef, derivation, durationSeconds, frames]
properties:
- sessionId: { type: string, maxLength: 128 }
- videoRef: { type: string, maxLength: 4096 }
+ sessionId:
+ type: string
+ minLength: 1
+ maxLength: 128
+ description: Canonical opaque ID without surrounding whitespace
+ videoRef:
+ type: string
+ minLength: 1
+ maxLength: 4096
+ description: Canonical opaque reference without surrounding whitespace
+ derivation:
+ type: object
+ additionalProperties: false
+ required: [parentContentHash, policy, version]
+ properties:
+ parentContentHash:
+ type: string
+ pattern: "^sha256:[a-f0-9]{64}$"
+ policy:
+ type: string
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$"
+ version:
+ type: string
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$"
durationSeconds: { type: number, exclusiveMinimum: 0, maximum: 600 }
frames:
type: array
@@ -5769,27 +5813,43 @@ paths:
maxItems: 16
items:
type: object
+ additionalProperties: false
required: [timestampSeconds, dataUri]
properties:
timestampSeconds: { type: number, minimum: 0 }
- dataUri: { type: string, pattern: "^data:image/jpeg;base64," }
+ dataUri:
+ type: string
+ minLength: 27
+ maxLength: 5592431
+ description: Canonical Base64 data URI whose decoded bytes pass a warning-sensitive bounded full JPEG decode/re-encode; trailing bytes are discarded and width and height are derived server-side
responses:
"201": { description: Drill-down result stored }
- "403": { description: Trusted loopback/token identity required }
+ "403": { description: Trusted loopback/token identity and principal required }
"413": { description: Payload exceeds the bounded session budget }
+ "499": { description: Caller cancelled before the derivation was committed }
delete:
x-loopback-only: true
tags: [System]
summary: Delete a Video Bridge drill-down session
security: []
parameters:
+ - in: header
+ name: x-omniroute-video-bridge-principal
+ required: true
+ description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+ schema:
+ type: string
+ minLength: 1
+ maxLength: 256
+ pattern: "^[!-~]{1,256}$"
- in: query
name: sessionId
required: true
- schema: { type: string, maxLength: 128 }
+ description: Canonical opaque ID without surrounding whitespace
+ schema: { type: string, minLength: 1, maxLength: 128 }
responses:
"200": { description: Session entries removed }
- "403": { description: Trusted loopback/token identity required }
+ "403": { description: Trusted loopback/token identity and principal required }
/api/cache/stats:
get:
@@ -6931,6 +6991,104 @@ paths:
"500":
description: Failed to parse OpenAPI spec
+ /api/openapi/try:
+ post:
+ tags: [System]
+ summary: Proxy an API Explorer request to an OmniRoute endpoint
+ description: >-
+ Executes an API Explorer request through a server-side, same-origin proxy. The target
+ must start with `/api/`, `/v1/`, `/v1beta/`, `/a2a`, or
+ `/.well-known/agent.json`; protocol-relative and cross-origin targets are rejected.
+ Hop-by-hop, proxy, host, cookie, and forwarding headers supplied in `headers` are
+ stripped, while any dashboard cookie on the original request is forwarded separately.
+ When `requireLogin` is disabled, the management-auth bypass mirrors the runtime setting;
+ otherwise a management Bearer credential or dashboard session is required. Failures
+ caught after authentication, including request JSON parsing, fetch, and response-body
+ parsing failures, are returned in the normal HTTP 200 result envelope so the Explorer
+ can display them; `status: 0` identifies that caught-failure path.
+ security:
+ - BearerAuth: []
+ - ManagementSessionAuth: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [path]
+ properties:
+ method:
+ type: string
+ enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
+ default: GET
+ path:
+ type: string
+ minLength: 1
+ pattern: "^/(?:api/|v1/|v1beta/|a2a|\\.well-known/agent\\.json)"
+ description: Same-origin OmniRoute API path, optionally including a query string.
+ headers:
+ type: object
+ default: {}
+ additionalProperties:
+ type: string
+ description: >-
+ Headers to forward after removing connection, content-length, cookie, host,
+ keep-alive, proxy-authenticate, proxy-authorization, te, trailer,
+ transfer-encoding, upgrade, x-forwarded-for, x-forwarded-host, and
+ x-forwarded-proto headers.
+ body:
+ description: >-
+ Optional JSON value. A truthy value is serialized unless it is already a
+ string, and is not forwarded when `method` is `GET`.
+ responses:
+ "200":
+ description: Upstream response or displayable caught-failure envelope
+ content:
+ application/json:
+ schema:
+ type: object
+ additionalProperties: false
+ required: [status, statusText, headers, body, latencyMs, contentType]
+ properties:
+ status:
+ type: integer
+ minimum: 0
+ description: Upstream HTTP status, or 0 when request processing throws.
+ statusText:
+ type: string
+ headers:
+ type: object
+ additionalProperties:
+ type: string
+ body:
+ description: >-
+ Parsed JSON, response text truncated after 10,000 characters, or a sanitized
+ caught-error object.
+ latencyMs:
+ type: integer
+ minimum: 0
+ contentType:
+ type: string
+ "400":
+ description: Invalid request body or non-same-origin path
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - $ref: "#/components/schemas/ValidationErrorResponse"
+ - type: object
+ required: [error]
+ properties:
+ error:
+ type: string
+ example: Path must be same-origin
+ "401":
+ $ref: "#/components/responses/ManagementAuthenticationRequired"
+ "403":
+ $ref: "#/components/responses/ManagementInvalidToken"
+ "503":
+ $ref: "#/components/responses/InternalError"
+
# ─── Agent Skills Catalog ────────────────────────────────────────────────────
/api/agent-skills:
diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md
index e9ef0df9c2..b383b5696f 100644
--- a/docs/reference/ENVIRONMENT.md
+++ b/docs/reference/ENVIRONMENT.md
@@ -531,6 +531,9 @@ detection above).
| `OMNIROUTE_CONFIG_HOT_RELOAD_MS` | `5000` | `src/lib/config/hotReload.ts` | Polling interval (ms) for config hot-reload. Lower than `1000` is rejected. |
| `OMNIROUTE_DISABLE_REDIS_AUTH_CACHE` | _(enabled)_ | `src/lib/db/apiKeys.ts` | Set `1` to bypass the Redis-backed API-key auth cache (forces DB reads). |
| `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS` | `0` | `open-sse/services/compression/engines/rtk/filterLoader.ts` | Trust user-managed RTK project filter rules without strict signature checks. |
+| `OMNI_COMPRESSION_WORKERS` | `2` | `open-sse/services/compression/compressionWorkerPool.ts` | Maximum concurrent synchronous RTK/Caveman workers; excess jobs wait FIFO. |
+| `OMNI_COMPRESSION_WORKER_TIMEOUT_MS` | `120000` | `open-sse/services/compression/compressionWorkerPool.ts` | Per-job timeout in milliseconds. Timed-out workers are terminated and the request fails open unchanged. |
+| `OMNI_COMPRESSION_WORKER_IDLE_MS` | `60000` | `open-sse/services/compression/compressionWorkerPool.ts` | Idle lifetime in milliseconds before an unused compression worker is terminated. |
| `COMPRESSION_PIPELINE_BREAKER_ENABLED` | `false` | `open-sse/services/compression/pipelineEngineBreaker.ts` | T02 stacked-pipeline per-engine circuit-breaker master switch. **Opt-in (default off)** — when on, an engine that throws repeatedly across requests is skipped (fail-open) for a cooldown; off = byte-identical legacy behavior. |
| `COMPRESSION_PIPELINE_BREAKER_THRESHOLD` | `3` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Consecutive cross-request failures before an engine's breaker opens. |
| `COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS` | `30000` | `open-sse/services/compression/pipelineEngineBreaker.ts` | Milliseconds an opened engine stays skipped before a half-open probe. |
@@ -1041,6 +1044,7 @@ desktop install.
| `EMBED_WS_PROXY_PORT` | `20131` | `src/lib/services/embedWsProxy.ts` | Port for the embedded-service WebSocket proxy server. |
| `CLIPROXYAPI_HOST` | `127.0.0.1` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI bridge host (legacy integration). |
| `CLIPROXYAPI_PORT` | `5544` | `open-sse/executors/cliproxyapi.ts` | CLIProxyAPI bridge port. |
+| `CLIPROXYAPI_MANAGEMENT_KEY` | _(empty)_ | `src/lib/services/cliproxyAccountHealth.ts` | Management key for account-health reads from an externally managed CLIProxyAPI instance. |
| `CLIPROXYAPI_CONFIG_DIR` | `~/.cli-proxy-api` | `src/lib/versionManager/processManager.ts` | CLIProxyAPI config directory. |
| `MUX_SERVICE_PORT` | `8322` | `src/lib/services/bootstrap.ts` | Override the port where the embedded Mux (coder/mux) agent-orchestration daemon listens (always 127.0.0.1). |
| `DARIO_HOST` | `127.0.0.1` | `open-sse/executors/dario.ts` | Dario embedded-service bind/connect host (loopback only by default). |
@@ -1277,7 +1281,6 @@ Provider quota endpoints, network tunnels (Tailscale, Ngrok, MITM debug proxy),
| `OMNIROUTE_SKIP_DNS_WRITE` | _(unset)_ | `src/mitm/dns/dnsConfig.ts` | Set `1` to skip writing to the hosts file when adding/removing DNS entries — for sandboxed or read-only test environments. |
| `OMNIROUTE_SKIP_SYSTEM_TRUST` | `0` | `src/mitm/cert/install.ts`, `src/mitm/tproxy/caTrust.ts` | Test/CI-only guard: set `1` to make cert trust install/uninstall a no-op so the suite never mutates the OS trust store. Set automatically by the test setup and CI workflows. |
| `CHANGELOG_BASE_REF` | _(auto)_ | `scripts/check/check-changelog-integrity.mjs` | Explicit base ref for the anti CHANGELOG-eat gate (defaults to the PR base branch in CI, or the highest `release/v*`). |
-| `ALLOW_CHANGELOG_REMOVALS` | `0` | `scripts/check/check-changelog-integrity.mjs` | Set `1` to turn intentional CHANGELOG bullet removals into a report instead of a failure (justify in the PR body). |
| `ONEPROXY_ENABLED` | `true` | `src/lib/oneproxySync.ts` | Enable the 1Proxy egress pool sync. |
| `ONEPROXY_API_URL` | `https://1proxy-api.aitradepulse.com` | `src/lib/oneproxySync.ts` | 1Proxy service API URL override. |
| `ONEPROXY_MAX_PROXIES` | `500` | `src/lib/oneproxySync.ts` | Maximum proxies imported per sync. |
diff --git a/docs/routing/AUTO-COMBO.md b/docs/routing/AUTO-COMBO.md
index bad9aa43dd..eacd1a700b 100644
--- a/docs/routing/AUTO-COMBO.md
+++ b/docs/routing/AUTO-COMBO.md
@@ -183,30 +183,31 @@ See [#7992](https://github.com/diegosouzapw/OmniRoute/issues/7992) and [#7111](h
## How It Works (Persisted Auto-Combos)
-The Auto-Combo Engine dynamically selects the best provider/model for each request using a **14-factor scoring function** (defined in `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). Weights form a normalized distribution (custom weights are renormalized by `normalizeScoringWeights()`).
+The Auto-Combo Engine dynamically selects the best provider/model for each request using a **15-factor scoring function** (defined in `open-sse/services/autoCombo/scoring.ts` → `DEFAULT_WEIGHTS`). The default weights sum to `1.0`; custom weights are renormalized by `normalizeScoringWeights()`.
-
+
-> Source: [diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd) (regenerate via `npm run docs:render-diagrams`). The filename predates the current factor set; the diagram shows 13 of the 14 factors (missing `sessionAvailability`).
+> Source: [diagrams/auto-combo-12factor.mmd](../diagrams/auto-combo-12factor.mmd) (regenerate via `npm run docs:render-diagrams`). The filename is historical; the source and rendered diagram show all 15 factors declared in `DEFAULT_WEIGHTS`.
| Factor | Default Weight | Description |
| :-------------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `health` | 0.20 | Health score from circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) |
-| `quota` | 0.15 | Remaining quota / rate-limit headroom [0..1] |
-| `costInv` | 0.15 | Inverse **blended** cost (60% input + 40% output token price, normalized) — cheaper = higher score |
-| `latencyInv` | 0.12 | Inverse p95 latency normalized to pool — faster = higher score |
-| `taskFit` | 0.08 | Task-type fitness (coding, review, planning, analysis, debugging, docs) |
-| `stability` | 0.05 | Variance-based stability (low latency stdDev / error rate) |
-| `tierPriority` | 0.05 | Account-tier priority — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 |
-| `tierAffinity` | 0.05 | Affinity between the candidate's tier and the manifest-recommended tier |
-| `specificityMatch` | 0.05 | Match between request specificity (manifest hint) and model tier |
-| `contextAffinity` | 0.05 | Affinity between the request's context-window need and the model's context window |
-| `sessionAvailability` | 0.05 | OAuth session availability of the candidate connection for this session (`getOAuthSessionAvailability()`; non-OAuth connections score 1.0) |
-| `connectionDensity` | 0.05 | Spreads load across connections of the same provider (anti-concentration) |
+| `quota` | 0.1429 | Remaining quota / rate-limit headroom [0..1] |
+| `health` | 0.1605 | Health score from circuit breaker (CLOSED=1.0, HALF_OPEN=0.5, OPEN=0.0) |
+| `costInv` | 0.1429 | Inverse **blended** cost (60% input + 40% output token price, normalized) — cheaper = higher score |
+| `latencyInv` | 0.1143 | Inverse p95 latency normalized to pool — faster = higher score |
+| `taskFit` | 0.0762 | Task-type fitness (coding, review, planning, analysis, debugging, docs) |
+| `stability` | 0.0476 | Variance-based stability (low latency stdDev / error rate) |
+| `tierPriority` | 0.0476 | Account-tier priority — Ultra=1.0, Pro=0.67, Standard=0.33, Free=0.0 |
+| `tierAffinity` | 0.0476 | Affinity between the candidate's tier and the manifest-recommended tier |
+| `specificityMatch` | 0.0476 | Match between request specificity (manifest hint) and model tier |
+| `contextAffinity` | 0.0476 | Affinity between the request's context-window need and the model's context window |
+| `sessionAvailability` | 0.0476 | OAuth session availability of the candidate connection for this session (`getOAuthSessionAvailability()`; non-OAuth connections score 1.0) |
+| `connectionDensity` | 0.0476 | Spreads load across connections of the same provider (anti-concentration) |
| `cacheAffinity` | 0.00 | Rendezvous-hash affinity toward the connection likeliest to already hold this request's prompt-cache prefix (`open-sse/services/combo/promptCacheAffinity.ts`); disabled by default (#8008) |
| `resetWindowAffinity` | 0.00 | Bias toward connections whose quota reset window is favorable (disabled by default) |
+| `quality` | 0.03 | Feedback-driven output-quality signal from the routing-event quality tracker; candidates without observations receive a neutral 0.5 |
-**Sum:** `0.20 + 0.15 + 0.15 + 0.12 + 0.08 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.05 + 0.00 + 0.00 = 1.05` as literally declared in `DEFAULT_WEIGHTS`; user-configured weights are renormalized into a distribution by `normalizeScoringWeights()` before scoring.
+**Sum:** `0.1429 + 0.1605 + 0.1429 + 0.1143 + 0.0762 + (7 × 0.0476) + 0.00 + 0.00 + 0.03 = 1.0` as declared in `DEFAULT_WEIGHTS`; user-configured weights are renormalized into a distribution by `normalizeScoringWeights()` before scoring.
## Mode Packs
@@ -677,8 +678,8 @@ Including the bare `auto` (default) plus the 6 `AutoVariant` values declared in
## How tiers fit Auto-Combo
-The 14-factor scoring function (`open-sse/services/autoCombo/scoring.ts`) treats tier
-membership as two signals: `tierPriority` (0.05) and `tierAffinity` (0.05). See the
+The 15-factor scoring function (`open-sse/services/autoCombo/scoring.ts`) treats tier
+membership as two signals: `tierPriority` (0.0476) and `tierAffinity` (0.0476). See the
canonical [scoring factor table](#how-it-works-persisted-auto-combos) above for the full
`DEFAULT_WEIGHTS` set — the per-pack overrides (ship-fast/cost-saver/quality-first/
offline-friendly) are listed in the "Weight profiles per pack" table.
diff --git a/docs/screenshots/free-tier-budget-card.svg b/docs/screenshots/free-tier-budget-card.svg
index 4a861867d6..42bf89d20c 100644
--- a/docs/screenshots/free-tier-budget-card.svg
+++ b/docs/screenshots/free-tier-budget-card.svg
@@ -1,77 +1,80 @@
-
+
+
+
-> 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.** 🛡️
+> A **combo** is a chain of models OmniRoute routes across **automatically**. If quota runs out, a provider fails, or costs spike, the combo can move to the next eligible healthy model. 🛡️
### ⚡ Zero-config — just use `auto`
@@ -429,7 +429,7 @@ All **19** strategies — mix & match per combo step:
+
+
+
+
+ 
+
+ 
- 
