Release v3.8.44

.dockerignore

@@ -125,3 +125,4 @@ app.__qa_backup/
 .worktrees
 .next-playwright/
 cloud/
+electron/dist-electron

.env.example

@@ -73,6 +73,11 @@ DISABLE_SQLITE_AUTO_BACKUP=false
 # Default: 20128
 PORT=20128
 
+# Base path (URL subpath) when serving OmniRoute behind a reverse proxy under a subpath.
+# Used by: next.config.mjs — sets Next.js `basePath`; auth redirects are basePath-aware.
+# Default: "" (served at the domain root). Example: /omniroute to serve under https://host/omniroute
+# OMNIROUTE_BASE_PATH=
+
 # Split-port mode: serve Dashboard and API on separate ports for network isolation.
 # Used by: src/lib/runtime/ports.ts — overrides PORT for each service.
 # API_PORT=20129
@@ -413,6 +418,15 @@ NEXT_PUBLIC_BASE_URL=http://localhost:20128
 # Do not include /v1; if included accidentally it will be normalized away.
 # OMNIROUTE_PUBLIC_BASE_URL=http://192.168.0.15:20128
 
+# Absolute provider plugin manifest URL advertised to sidecar clients.
+# Used by: open-sse/config/providerPluginManifestUrl.ts. When unset, OmniRoute
+# derives the URL from request origin or HOST/PORT using OMNIROUTE_PUBLIC_PROTOCOL.
+# OMNIROUTE_PROVIDER_MANIFEST_URL=https://omniroute.example.com/api/v1/provider-plugin-manifest
+
+# Protocol used when deriving provider plugin manifest URLs without a request origin.
+# Used by: open-sse/config/providerPluginManifestUrl.ts. Defaults to http.
+# OMNIROUTE_PUBLIC_PROTOCOL=http
+
 # Max wait time for an async chatgpt-web image to land via the celsius
 # WebSocket, in milliseconds. Default 180000 (3 minutes). Increase during
 # upstream queue-deep windows ("Lots of people are creating images right now").
@@ -568,6 +582,8 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
 # CLI_CONTINUE_BIN=cn
 # CLI_QODER_BIN=qoder
 # CLI_QWEN_BIN=qwen
+# CLI_AUGGIE_BIN=auggie
+# AUGGIE_BIN=auggie
 
 # Override the Hermes Agent home directory (where OmniRoute reads/writes the
 # Hermes CLI config). Matches the env var the Hermes PowerShell installer sets
@@ -635,6 +651,14 @@ PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 # to opt out (restores fully concurrent fetches). Default: 1500
 PROVIDER_LIMITS_SYNC_SPACING_MS=1500
 
+# Min interval (ms) between consecutive UPSTREAM quota fetches on the per-request
+# preflight/monitor path (e.g. Codex /wham/usage), complementing the bulk-sync
+# spacing above. Many accounts on one IP fetching quota in the same second can look
+# like automation to the upstream and get an OAuth token revoked (#6009). This gate
+# serializes genuine network calls (cache hits are unaffected). Set to 0 to disable.
+# Default: 250 (clamped 0..5000).
+# OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS=250
+
 # Delay (ms) before refreshing provider limits after a real usage event (e.g. a
 # completed request). Gives the upstream quota API time to register the consumption
 # before the dashboard polls. Default: 5000
@@ -869,6 +893,8 @@ GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 # QODER_PERSONAL_ACCESS_TOKEN=
 # QODER_CLI_WORKSPACE=
 # OMNIROUTE_QODER_WORKSPACE=
+# Override the Qoder CLI config dir (isolated PAT session, avoids clobbering a browser login).
+# QODER_CLI_CONFIG_DIR=
 
 # ── Blackbox Web validated-token override (issue #2252) ──
 # Used by: open-sse/executors/blackbox-web.ts. Blackbox `/api/chat` rejects
@@ -1037,6 +1063,12 @@ CURSOR_USER_AGENT="Cursor/3.4"
 # fallback when FETCH_TIMEOUT_MS is unset. Default: 120000 (2 min).
 # OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS=120000
 
+# ── Firecrawl web-fetch executor ──
+# Point at a self-hosted Firecrawl instance (defaults to the public cloud API).
+# When set to a non-cloud base URL, the API key becomes optional.
+# FIRECRAWL_BASE_URL=https://api.firecrawl.dev
+# FIRECRAWL_TIMEOUT_MS=30000            # Per-request timeout (default: 30000 = 30s)
+
 # ── ChatGPT TLS sidecar (Firefox-fingerprinted client) ──
 # Used by: open-sse/services/chatgptTlsClient.ts — wire-level timeout for
 # the bogdanfinn/tls-client koffi binding and the JS-side grace window
@@ -1442,6 +1474,13 @@ APP_LOG_TO_FILE=true
 # CLIPROXYAPI_PORT=5544
 # CLIPROXYAPI_CONFIG_DIR=~/.cli-proxy-api
 
+# ── Mux embedded service ──
+# Override the port where the embedded Mux (coder/mux) agent-orchestration
+# daemon listens. Always bound to 127.0.0.1 — never configurable to 0.0.0.0.
+# Rarely needed — defaults to 8322.
+# Used by: src/lib/services/bootstrap.ts, src/app/api/services/mux/_lib.ts
+# MUX_SERVICE_PORT=8322
+
 # ── Local hostnames (Docker networking) ──
 # Comma-separated additional hostnames treated as "local" for provider routing.
 # Used by: open-sse/config/providerRegistry.ts — allows Docker service names.
@@ -1464,6 +1503,20 @@ APP_LOG_TO_FILE=true
 # healthy-result cache window under high concurrency.
 # PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS=2000
 
+# Background proxy health scheduler (src/lib/proxyHealth/scheduler.ts).
+# Periodically probes every registered proxy and (optionally) removes dead ones.
+# Set "false" to disable the scheduler entirely. Default: enabled.
+# PROXY_HEALTH_ENABLED=true
+# Sweep interval in ms (minimum 60000). Default: 600000 (10min).
+# PROXY_HEALTH_INTERVAL_MS=600000
+# Reachability probe target for the scheduler and the auto-test endpoint.
+# Point it at an internal/self-hosted URL to avoid the public default.
+# PROXY_HEALTH_TEST_URL=https://httpbin.org/ip
+# Set "true" to let the scheduler auto-remove proxies after repeated failures.
+# PROXY_AUTO_REMOVE=false
+# Consecutive failures before an auto-remove fires. Default: 3.
+# PROXY_AUTO_REMOVE_AFTER=3
+
 # Allow OAuth and provider validation flows to bypass a pinned proxy and connect
 # directly when proxy reachability pre-checks fail. Default: false.
 # Also configurable from Dashboard > Settings > Feature Flags.
@@ -1675,6 +1728,15 @@ APP_LOG_TO_FILE=true
 # FREE_PROXY_IPLOCATE_ENABLED=false
 # FREE_PROXY_IPLOCATE_BASE_URL=https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols
 
+# ── Free Proxy Pool (Webshare source) ──
+# Used by: src/lib/freeProxyProviders/webshare.ts
+# Paid, per-account proxy list — requires FREE_PROXY_WEBSHARE_API_KEY to activate,
+# regardless of FREE_PROXY_WEBSHARE_ENABLED.
+# FREE_PROXY_WEBSHARE_ENABLED=true
+# FREE_PROXY_WEBSHARE_API_KEY=
+# FREE_PROXY_WEBSHARE_API_URL=https://proxy.webshare.io/api/v2/proxy/list/
+# FREE_PROXY_WEBSHARE_MAX=500
+
 # ── Vercel Relay ──
 # Used by: src/app/api/settings/proxy/vercel-deploy/route.ts
 # Hides the "Deploy Relay" button when set to false.
@@ -1879,6 +1941,10 @@ QUOTA_STORE_DRIVER=sqlite              # sqlite | redis
 # duplicated). Falls back to TS path via X-Bifrost-Fallback header on
 # timeout/failure. See bin/omniroute for the local-redis companion.
 # BIFROST_BASE_URL=
+# Port the supervised Bifrost embedded service binds to (127.0.0.1:<port>), read by
+# src/lib/services/bootstrap.ts when OmniRoute manages the Bifrost sidecar lifecycle.
+# Default: 8080.
+# BIFROST_PORT=8080
 # API key for the Bifrost gateway (sent as Authorization: Bearer ...). If
 # unset, the route expects the request to carry a valid OmniRoute API key;
 # this key is for gateway-side auth only.

.github/workflows/ci.yml

@@ -624,7 +624,7 @@ jobs:
           cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,executors,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
   test-vitest:
     name: Vitest (MCP / autoCombo / UI components)
@@ -676,7 +676,7 @@ jobs:
           cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,executors,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
   node-26-compat-build:
     name: Node 26 Compatibility Build
@@ -729,7 +729,7 @@ jobs:
           cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
-      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
+      - run: node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,executors,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
 
   test-coverage-shard:
     name: Coverage Shard (${{ matrix.shard }}/8)
@@ -770,7 +770,7 @@ jobs:
             --exclude=tests/** \
             --exclude=**/*.test.* \
             node --max-old-space-size=4096 --import tsx --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 \
-              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
+              --test-shard=${{ matrix.shard }}/8 tests/unit/*.test.ts "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,executors,gamification,guardrails,lib,mcp,memory,runtime,security,services,settings,shared,ui,usage}/**/*.test.ts"
       - name: Upload raw shard coverage
         if: always()
         uses: actions/upload-artifact@v7

.github/workflows/quality.yml

@@ -145,4 +145,4 @@ jobs:
           --import ./tests/_setup/isolateDataDir.ts
           --test --test-force-exit --test-concurrency=4 --test-shard=${{ matrix.shard }}/2
           tests/unit/*.test.ts
-          "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"
+          "tests/unit/{api,auth,authz,build,cli,cli-helper,combo,compression,correctness,cors,dashboard,db,db-adapters,docs,executors,gamification,guardrails,lib,mcp,runtime,security,services,settings,shared,ui}/**/*.test.ts"

AGENTS.md

@@ -8,9 +8,9 @@ Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepI
 SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
 with **MCP Server** (94 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
-> **Live counts (v3.8.40)**: providers 237 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
-> open-sse services 298 · routing strategies 17 · auto-combo scoring factors 12 ·
-> DB modules 94 · DB migrations 106 · base tables 17 · search providers 11 ·
+> **Live counts (v3.8.43)**: providers 237 · MCP tools 94 · MCP scopes 30 · A2A skills 6 ·
+> open-sse services 134 · routing strategies 17 · auto-combo scoring factors 12 ·
+> DB modules 95 · DB migrations 110 · base tables 17 · search providers 11 ·
 > i18n locales 42. **Refresh with `npm run check:docs-all`.**
 
 ## Doc Accuracy Discipline (read before writing any doc)
@@ -178,7 +178,7 @@ Always run `prettier --write` on changed files.
 
 ### Data Layer (`src/lib/db/`)
 
-All persistence uses SQLite through **83 domain-specific modules** in `src/lib/db/`. Top modules:
+All persistence uses SQLite through **95 domain-specific modules** in `src/lib/db/`. Top modules:
 
 - Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
 - Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
@@ -188,8 +188,8 @@ All persistence uses SQLite through **83 domain-specific modules** in `src/lib/d
 - Storage: `backup.ts`, `cleanup.ts`, `jsonMigration.ts`, `healthCheck.ts`, `databaseSettings.ts`
 - Extension modules: `evals.ts`, `webhooks.ts`, `reasoningCache.ts`, `readCache.ts`, `tierConfig.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `batches.ts`, `files.ts`, `syncTokens.ts`, `proxies.ts`, `oneproxy.ts`, `upstreamProxy.ts`, `versionManager.ts`, `cliToolState.ts`, `prompts.ts`, `detailedLogs.ts`, `contextHandoffs.ts`, `compression.ts`, `stats.ts`
 
-Live count: `ls src/lib/db/*.ts | wc -l` (currently 83). Drift detection: `npm run check:docs-counts`.
-Schema migrations live in `db/migrations/` (**97 files** as of v3.8.24) and run via `migrationRunner.ts`.
+Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Drift detection: `npm run check:docs-counts`.
+Schema migrations live in `db/migrations/` (**110 files** as of v3.8.43) and run via `migrationRunner.ts`.
 `src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
 
 #### DB Internals
@@ -198,7 +198,7 @@ Schema migrations live in `db/migrations/` (**97 files** as of v3.8.24) and run
   journaling. `SCHEMA_SQL` defines **17 base tables** (verify with `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for the bookkeeping `_omniroute_migrations` table). Helpers: `rowToCamel`, `encryptConnectionFields`.
 - **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
   Tracks applied migrations in `_omniroute_migrations` table.
-- **Migrations**: 97 files (`001_initial_schema.sql` → `099_*.sql`).
+- **Migrations**: 110 files (`001_initial_schema.sql` → `110_*.sql`).
   Each migration is idempotent and runs in a transaction. Live count: `ls src/lib/db/migrations/*.sql | wc -l`.
 - **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
   Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
@@ -336,7 +336,7 @@ Includes request/response translators with helpers for image handling.
 
 ### Services (`open-sse/services/`)
 
-115 service modules in `open-sse/services/` (top-level only; 184 including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules:
+134 service modules in `open-sse/services/` (top-level only; more including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules:
 `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
 `rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
 `autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
@@ -378,8 +378,8 @@ Modular prompt compression that runs proactively before the existing reactive co
   and iterates through targets in order until one succeeds or all fail.
 - **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
   `ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
-- **Strategies** (15): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
-  reset-window, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
+- **Strategies** (17): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
+  reset-window, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, headroom, fusion. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
 - Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
   per-target error handling and circuit breaker checks.