diff --git a/README.md b/README.md index 01906f841d..edc6796b6a 100644 --- a/README.md +++ b/README.md @@ -295,7 +295,7 @@ Result: 4 layers of fallback = zero downtime - **⚖️ Quota-Share routing** — a dedicated combo strategy that spreads load across accounts by _available quota_: Deficit-Round-Robin scheduling, per-connection `max_concurrent` with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key,model) caps, session stickiness for prompt-cache integrity, and proactive saturation from upstream token-usage headers. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) - **🤖 One-command CLI/agent setup** — a dedicated `setup-*` command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode, Gemini CLI); `omniroute launch` / `omniroute launch-codex` are zero-config launchers. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md) - **🛰️ Remote mode** — drive a remote OmniRoute from any machine with scoped access tokens (`omniroute connect` / `omniroute contexts` / `omniroute tokens`). → [Remote Mode](docs/guides/REMOTE-MODE.md) -- **🧭 Smarter auto-routing** — OpenRouter-style `auto/:` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (16th — fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing. → [Auto-Combo](docs/routing/AUTO-COMBO.md) +- **🧭 Smarter auto-routing** — OpenRouter-style `auto/:` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing. → [Auto-Combo](docs/routing/AUTO-COMBO.md) - **🗜️ Pluggable compression** — an async pipeline of **9 composable engines** with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier **Ultra**, RTK, delegated Anthropic Context Editing, **Output Styles** (output-axis steering: terse-prose / less-code / terse-CJK), an **adaptive context-budget dial** (escalate only as far as needed to fit the context window), per-request `x-omniroute-compression` control, an opt-in offline eval harness, one-click **Headroom** proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic **compression playground** (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in **per-step fidelity gate** that rejects a lossy engine before it degrades the prompt, and a unified panel with named profiles + an active-profile selector. → [Compression](docs/compression/COMPRESSION_ENGINES.md) - **🕵️ Transparent MITM decrypt (TPROXY)** — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md) - **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT `X-OmniRoute-Cost-Saved` header, and per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md) diff --git a/docs/routing/AUTO-COMBO.md b/docs/routing/AUTO-COMBO.md index 5006fe4516..6c6d4b312d 100644 --- a/docs/routing/AUTO-COMBO.md +++ b/docs/routing/AUTO-COMBO.md @@ -569,6 +569,36 @@ To strongly favor Tier 1 (subscription), increase `tierPriority` weight: See `docs/marketing/TIERS.md` for tier definitions and provider classification. +## Testing & Coverage + +### Deterministic routing-decision matrix (`npm run test:combo:matrix`) + +`tests/integration/combo-matrix/*.test.ts` proves the routing **decision** of all 17 +public strategies end-to-end through the real combo pipeline with a mocked upstream. +Coverage includes: + +- All 17 `ROUTING_STRATEGY_VALUES` strategies (ordered, weighted, cost, context, fusion, …). +- `quota-share` (internal) end-to-end: DRR fairness + saturation deprioritization via the + real `selectQuotaShareTarget` seam (`registerQuotaFetcher` / `setLKGP` / + `__setHeadroomSaturationFetcherForTests`). +- `context-relay` universal-handoff coverage across every target count. + +This suite runs in CI (`test:integration` job) with `--test-concurrency=1` and +`--test-force-exit` so it is deterministic and does not require live credentials. + +### Gated live smoke (NOT in CI — real providers) + +| Command | What it does | +| :--- | :--- | +| `npm run test:combo:live` | In-process real routing with `RUN_COMBO_LIVE=1`; snapshots a live OmniRoute DB | +| `npm run test:combo:live:vps` | HTTP calls against a live OmniRoute server (set `COMBO_LIVE_BASE_URL`) | +| `npm run test:combo:live:vps:failover` | Same, with deliberate failover scenarios | + +These smoke tests exercise the real wire path (combo → provider → completion). They are +intentionally excluded from CI because they require live credentials and VPS access. + +--- + ## Files | File | Purpose | diff --git a/docs/routing/QUOTA_SHARE.md b/docs/routing/QUOTA_SHARE.md index 286c4a4552..97901db569 100644 --- a/docs/routing/QUOTA_SHARE.md +++ b/docs/routing/QUOTA_SHARE.md @@ -334,6 +334,29 @@ re-migration. --- +## Internal Strategy Classification + +`quota-share` is an **internal-only** routing strategy (`INTERNAL_ROUTING_STRATEGY_VALUES` in +`src/shared/constants/routingStrategies.ts`). It is used exclusively by system-minted +`qtSd/` pool combos and is deliberately excluded from `ROUTING_STRATEGY_VALUES` so it never +appears as a user-selectable option in the UI or API. + +--- + +## Test Coverage + +Two layers of automated coverage ship with the quota-share engine: + +| Suite | Command | What it covers | +| :--- | :--- | :--- | +| Unit (29 tests) | `node --import tsx/esm --test tests/unit/quota-share-strategy.test.ts` | DRR scheduler, saturation gating, concurrency caps, fairShare math, backlog queueing | +| Integration matrix | `npm run test:combo:matrix` | End-to-end routing decision through the real combo pipeline; DRR fairness + saturation deprioritization via live seams (`registerQuotaFetcher`, `setLKGP`, `__setHeadroomSaturationFetcherForTests`) | + +The integration matrix runs in CI alongside the other 17 public strategies. The unit suite +can be run standalone. + +--- + ## DB Schema Summary Three tables added by migrations `073–075`: