mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-09-19 05:12:16 +03:00
4d1282be31
* fix(quality): drain the 09-18 base-reds, part 1 — thinking gate parity, inventory, webpack externals Reproduced on the clean tip7cc454d9before touching anything. Five of the failures trace to one commit, #12905 (b7192b72): it gated thinking-block emission on `requestedThinking === true` in the streaming translator, while its own non-streaming path documents `undefined` as the legacy caller shape that keeps "always a thinking block". The two paths disagreed on the same input, and the streaming side also synthesized the reasoning into a TEXT block for that legacy shape. chatCore always resolves a boolean, so production never sends `undefined` — but every direct caller and the older #5786 suites do. Aligned the streaming gate to the documented tri-state: `false` suppresses, `true` and `undefined` relay, and the fix-B text synthesis fires only on an explicit opt-out. The #12905 test that asserted suppression used a bare createState() (`undefined`) to mean "client did not request thinking"; it now passes `requestedThinking: false`, which is what that sentence resolves to in production. The whole thinking family — dsml, adapter, translator, non-stream parity, #13620, #5786, markdown boundary — is 77/77. #12864 added requestRejectedFailure.ts with a getProviderConnectionById read that seeds the refusal streak across restarts; inventoried as a connection state read next to the family-cooldown site it resembles. #13909 made machineToken.ts import ./dataPaths; the isolated webpack compile has no repo tree, so it joins the sibling externals. The free-tier budget card SVG was one wave behind again (482 -> 491 models). Refs #13866 * fix(sse): restore maxQueueDepth=0 as unbounded, sanitize refusals at the write, drain the rest Part 2 of the 09-18 base-red drain. Two of the remaining failures were not stale tests but production defects the tests had caught. #12911 taught accountSemaphore to read `maxQueueSize: 0` as "reject when the slot is busy", which is what its Codex WS lease wants. But chatCore forwards `resilienceSettings.requestQueue.maxQueueDepth` into that option, and that setting's documented default since #6593 is `0 = disabled`. Under default settings every request that found its account slot occupied was answered 429 "Semaphore queue full (0)" instead of waiting — the managed-lease routing test saw exactly that. `0` (and any non-positive value) is unbounded again; the lease gets an explicit `failFast` option and its four tests stay green, so the #12911 behaviour is preserved where it was meant to apply. A contract test pins the #6593 semantics on the semaphore itself. #12864 moved two providerFailure persistence branches out of chatCore into requestRejectedFailure.ts and the sanitization did not travel with them: three `lastError` writes stored the message as received. The only caller already hands in the projected persistentMessage, so nothing leaks today, but a persistence branch must be safe at its own write (docs/security/ ERROR_SANITIZATION.md) rather than trust whoever calls it. The module now sanitizes on entry, and the public-boundary guard — which caught this by counting sanitized writes in chatCore and coming up two short — covers the extracted module too, verified by mutating one write back to raw. The rest are tests that had fallen behind legitimate changes: - #12905 inserted `requestedThinking` as the 14th positional argument of createSSETransformStreamWithLogger; two tests passed customToolNames or the buffer budget at their old positions. Both production callers were already correct. - #12754 added a per-connection reset-card fetch after the quota fetch; the spacing test now marks a chunk at the quota request only. - #13910 renamed `error` to `errorMetadata` in the timeout classification; the probe matches the identifier with a backreference and still fails when BodyTimeoutError is removed from both sites. Refs #13866 * fix(test): pin the opt-out thinking cases to requestedThinking=false; keep acquireMany under the complexity ceiling The #12905 gate-restore suite encoded 'requestedThinking absent' as opt-out, the same undefined-means-false shape its non-streaming twin documents the other way and that the two-month-old #5786 suites contradict. The three opt-out cases now set the flag explicitly, which is what chatCore resolves for an opted-out client; the two opt-in cases already did. Both suites pass together (27/27). The failFast branch pushed acquireMany over the complexity ceiling it already sat on; the admission policy (fail-fast / bounded / unbounded queue) moves to findQueueRejection() and the new-code ratchet is back at its base. Refs #13866 * fix(test): suspend the #14110 redaction assertion inline; refresh the budget card The 57 commits merged since the previous validation moved two things. #13295 changed how an unknown-root path with an ambiguous tail is answered: where `Provider failed at /custom/internal secret directory` used to become `Provider failed at <path>` it now ships verbatim. The #12506 boundary guard caught it. Two candidate fixes were tried and each breaks one of the two live contracts — #12506's fail-closed swallow, or #13144's rule that a route in prose must survive — so the choice is the owner's (#14110). The one contested assertion is suspended inline with the exact line and the issue; the other nine stay active. The isolated-child harness requires tests == pass, which is why it is a comment and not a todo. The free-tier budget card was one wave behind again (491 -> 489 models). Refs #13866, #14110 * fix(providers): type the TinyCMS DOM stub global as a loose record #13957 typed the mock global as `typeof globalThis & Record<string, unknown>`. The api-route typecheck loads lib.dom, so that intersection carries the real Window / HTMLCanvasElement / document signatures — every stub assignment fails against a DOM constructor, and `delete g.window` narrows the object to `never` (13 diagnostics, the API Route Typecheck base-red on the tip). The function exists to overwrite those globals with stubs; it is now typed as the plain record it manipulates. 29/29 tinycms tests unchanged. Refs #13866 * fix(test): pin the last opt-out thinking sibling to requestedThinking=false translator-reasoning-gate-502-repro is the third #12905 test that encoded a bare state as opt-out; the previous sweep matched files by glob and missed it. The family is now enumerated by grep on requestedThinking (7 files) plus the two pre-#12905 suites: 83/83 together. Refs #13866
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| OmniRoute Documentation | 3.8.40 | 2026-06-28 |
OmniRoute Documentation
Navigable index of the OmniRoute documentation set. Topics are grouped by intent so you can find what you need quickly.
Looking for the project overview, install steps, or release notes? See the root README.md, ROADMAP.md, CHANGELOG.md, and CONTRIBUTING.md.
For Non-Tech Users
Simple guides for using OmniRoute — no technical background needed.
getting-started/
- QUICK-START.md — install and run OmniRoute in 3 minutes.
- AUTO-COMBO-GUIDE.md — let OmniRoute pick the best AI for you.
- PROVIDERS-GUIDE.md — how to connect AI providers.
- FREE-TIERS-GUIDE.md — get free AI with no credit card.
- WEB-COOKIE-GUIDE.md — web cookie providers (session-credential setup).
guides/
- SETUP_GUIDE.md — first-time setup of OmniRoute.
- USER_GUIDE.md — daily usage of the dashboard and API.
- THINKING_BUDGET.md — thinking/reasoning budget modes (passthrough vs auto-strip).
- FEATURES.md — dashboard feature gallery.
- CHAOS-MODE.md — multi-model parallel/collaborative execution (setup, permissions, API).
- TIERS.md — OmniRoute tiers explained (user guide).
- USAGE_QUOTA_GUIDE.md — usage, quota & spend tracking.
- COST_TRACKING.md — cost and spend tracking.
- FREE_PROVIDER_RANKINGS.md — free provider rankings (Arena ELO).
- DOCKER_GUIDE.md — running OmniRoute under Docker, including runtime RAM for coding agents.
- ELECTRON_GUIDE.md — desktop (Electron) builds.
- TERMUX_GUIDE.md — running on Android via Termux.
- PWA_GUIDE.md — installing the dashboard as a PWA.
- REMOTE-MODE.md — exposing OmniRoute remotely + scoped tokens.
- CLI-INTEGRATIONS.md — master table of
setup-*CLI integrations. - OPENCODE-V2-PLUGIN.md — installing and configuring the OpenCode v2 plugin.
- CLAUDE-CODE-CONFIGURATION.md — Claude Code CLI with OmniRoute.
- CODEX-CLI-CONFIGURATION.md — Codex CLI with OmniRoute.
- KIRO_SETUP.md — Kiro setup.
- ANTIGRAVITY-ONBOARDING.md — Antigravity (Google One AI) onboarding.
- MANAGEMENT-AUTH.md — management authentication.
- I18N.md — translation and locale workflow.
- TROUBLESHOOTING.md — detailed troubleshooting reference.
- UNINSTALL.md — clean removal steps.
For Tech Users
Technical documentation for developers and contributors.
architecture/
How the system is put together — read these to understand the runtime, code layout, and resilience model.
- ARCHITECTURE.md — high-level system architecture (request pipeline, layers, modules).
- CODEBASE_DOCUMENTATION.md — engineering reference for the codebase.
- REPOSITORY_MAP.md — directory-by-directory navigation guide.
- AUTHZ_GUIDE.md — authorization pipeline (route classifier + policy engine).
- RESILIENCE_GUIDE.md — provider circuit breaker, connection cooldown, and model lockout.
- QUALITY_GATES.md — quality-gate scripts and CI jobs inventory.
- MONITORING_SECTIONS.md — monitoring/costs dashboard navigation.
- cluster-decisions.md — optional sidecar/cluster profile decisions.
- DESIGN_SYSTEM.md — design system & visual identity.
- ROUTER_BACKENDS.md — router backends & embedded services architecture contract (ADR).
- admission-lanes.md — the two admission-lane systems and what gates each.
- persistence-backend-boundary.md — pluggable persistence boundary (ADR).
reference/
Lookup material — API surface, environment variables, CLI flags, provider catalog.
- API_REFERENCE.md — REST API endpoints and shapes.
- PROVIDER_REFERENCE.md — auto-generated provider catalog (do not edit by hand).
- REMOVED_PROVIDERS.md — providers removed at their operator's request; never reintroduce without written permission.
- PROVIDER_PLUGIN_MANIFEST.md — sidecar-safe provider plugin contract for Bifrost and CLIProxyAPI migration.
- openapi.yaml — OpenAPI spec for the public API.
- ENVIRONMENT.md — environment variables reference.
- FEATURE_FLAGS.md — feature flags and their defaults.
- CLI-TOOLS.md — bundled CLI commands.
- FREE_TIERS.md — free-tier LLM provider directory.
- FREE_PROXIES_API.md — free proxies API.
- RELAY_BACKEND_STRATEGY.md — relay backend strategy.
- RELAY_TROUBLESHOOTING.md — relay troubleshooting.
frameworks/
Pluggable subsystems exposed to clients, agents, and operators.
- MCP-SERVER.md — Model Context Protocol server.
- A2A-SERVER.md — Agent-to-Agent (A2A) JSON-RPC server.
- ACP.md — Agent Client Protocol.
- AGENT_PROTOCOLS_GUIDE.md — A2A / ACP / Cloud agent overview.
- AGENTBRIDGE.md — IDE agent bridge.
- AGENT-SKILLS.md — agent skills catalog.
- CLOUD_AGENT.md — cloud agent runtime and providers.
- SKILLS.md — Skills framework (sandboxed extension).
- MEMORY.md — persistent memory (FTS5 + Qdrant).
- WEBHOOKS.md — webhook events and dispatch.
- EVALS.md — eval suites.
- GAMIFICATION.md — gamification & leaderboard system.
- EMBEDDED-SERVICES.md — embedded sidecar services (9Router, CLIProxyAPI).
- NOTION_CONTEXT.md — Notion context source.
- OBSIDIAN_CONTEXT.md — Obsidian context source.
- LOCAL_CORPUS_CONTEXT.md — local corpus context source (approved directory exposed to MCP).
- OPENCODE.md — OpenCode integration.
- OPEN_SSE_ARCHITECTURE.md — open-sse streaming engine internals.
- PLAYGROUND_STUDIO.md — Playground Studio UI.
- SEARCH_TOOLS_STUDIO.md — Search Tools Studio UI.
- TRAFFIC_INSPECTOR.md — traffic inspector (MITM).
- PLUGINS.md — CLI plugin system overview.
- PLUGIN_SDK.md — plugin SDK reference.
- PLUGIN_MARKETPLACE.md — plugin marketplace.
- RADAR.md — Radar free-model catalog overlay (optional, off by default).
routing/
Combo routing, scoring, and replay.
- AUTO-COMBO.md — Auto-Combo (multi-factor scoring, 19 strategies).
- QUOTA_SHARE.md — quota sharing engine.
- REASONING_REPLAY.md — reasoning replay cache.
- REASONING_ROUTING.md — reasoning routing rules (effort/budget rule engine).
security/
Guardrails, compliance, stealth, and the mandatory patterns for handling public credentials and error messages.
- GUARDRAILS.md — PII, prompt injection, vision guardrails.
- COMPLIANCE.md — audit trails and compliance.
- STEALTH_GUIDE.md — TLS / fingerprint stealth.
- PUBLIC_CREDS.md — mandatory pattern for embedding public upstream OAuth client_id/secret + Firebase Web keys without tripping secret scanners.
- ERROR_SANITIZATION.md — mandatory pattern for routing every error response through
sanitizeErrorMessageto prevent stack-trace exposure. - ROUTE_GUARD_TIERS.md — route-guard classification tiers.
- CLI_TOKEN.md — CLI machine-ID token (HMAC + legacy SHA-256) auth.
- EGRESS_POLICY.md — egress IP family (IPv4/IPv6) policy.
- BAN_DETECTION.md — account-ban / banned-keyword detection.
- AGENTROUTER_WAF.md — agentrouter.org WAF.
- CORS.md — CORS configuration & security.
- MITM-TPROXY-DECRYPT.md — transparent MITM decrypt.
- SUPPLY_CHAIN.md — supply-chain gates (SLSA, SBOM, Trivy, osv-scanner, Scorecard).
- SOCKET_DEV_FINDINGS.md — supply-chain finding attestations.
compression/
Prompt compression engines, rules, and language packs.
- COMPRESSION_GUIDE.md — top-level compression overview.
- COMPRESSION_ENGINES.md — available compression engines.
- COMPRESSION_RULES_FORMAT.md — rule file format.
- COMPRESSION_LANGUAGE_PACKS.md — language packs.
- RTK_COMPRESSION.md — RTK engine deep dive.
- CONTEXT_EDITING.md — delegated context editing (Anthropic).
- EXTENDING_COMPRESSION.md — adding a custom compression engine.
providers/
Provider-specific integration guides.
- CLAUDE_WEB.md — Claude Web (cookie-auth) provider.
- CHATGPT_WEB.md — ChatGPT Web (Codex) provider and common-provider retirement note.
- COPILOT-M365.md — Microsoft 365 Copilot (BizChat) provider.
- ALIBABA-QWEN-PROVIDER-FAMILIES.md — Alibaba and Qwen provider families.
- AGENTROUTER.md — AgentRouter setup.
- ZED-DOCKER.md — Zed IDE integration under Docker.
- CURSOR-DOCKER.md — Cursor model listing under Docker.
comparison/
- OMNIROUTE_VS_ALTERNATIVES.md — how OmniRoute compares to alternatives.
ops/
Release, deployment, proxies, tunnels, coverage, database, monitoring.
- RELEASE_CHECKLIST.md — release flow checklist.
- RELEASE_GREEN.md — keeping the PR queue and release branch green.
- BRANCHING_MODEL.md — branching & release model.
- MERGE_TRAIN.md — merge queue & manual merge-train runbook.
- HOMOLOGATION.md — homologation suite (
npm run homolog). - QUALITY_GATE_PLAYBOOK.md — quality-gate playbook.
- RUNNER_BOX.md — self-hosted runner box operations.
- BRANCH_PROTECTION_MAIN.md —
mainbranch protection. - CONTRIBUTION_GOLDEN_PATH.md — contribution golden path (focused checks per change type).
- COVERAGE_PLAN.md — test coverage plan.
- DATABASE_GUIDE.md — DB schema and operations.
- SQLITE_RUNTIME.md — SQLite driver resolution chain.
- REDIS_PRODUCTION_CONFIG.md — Redis production configuration.
- MONITORING_GUIDE.md — monitoring & observability.
- FLY_IO_DEPLOYMENT_GUIDE.md — Fly.io deployment.
- VM_DEPLOYMENT_GUIDE.md — generic VM deployment.
- PROXY_GUIDE.md — upstream proxy configuration.
- TUNNELS_GUIDE.md — Cloudflare tunnel and friends.
diagrams/
Mermaid sources and exported SVG/PNG diagrams referenced from the docs above. See diagrams/README.md.
i18n/
Translated mirrors of the documentation in 65 locales (plus the English originals — 66 languages in total). See i18n/README.md for the supported language list.
screenshots/
Static screenshots used by the dashboard and the README. Not part of the doc body.
Auto-generated artifacts
- reference/PROVIDER_REFERENCE.md is generated by
scripts/docs/gen-provider-reference.tsfromsrc/shared/constants/providers.ts. Do not edit by hand. - The
/docsUI is backed by Fumadocs MDX source generation from the subfolders above.