| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 11 | 1 | 0% |
| Commands | 0 | 0 | 1 | 0% |
| Section tags | 1 | 2 | 4 | 14% |
What each file covers
Sections
0 shared · 11 only in A · 1 only in B- − open-sse/services/ — Routing Engine & Cross-Cutting Services
- − Combo Routing Engine
- − Key Services
- − Quota & Rate Limiting
- − Account & Token Management
- − Request Routing & Intelligence
- − Model Lifecycle & Fallback
- − State & Detection
- − Prompt Compression Pipeline (`compression/`)
- − Adding a New Service
- − Anti-Patterns
- + OmniRoute PR and Coverage Instructions
Commands
0 shared · 0 only in A · 1 only in B- + npm run test:coverage
Section tags
1 shared · 2 only in A · 4 only in B- − performance
- − deployment
- + test
- + testing-strategy
- + git-pr
- + agent-behaviour
- code-style
Line diff
diegosouzapw/OmniRoute · open-sse/services/AGENTS.md
@@ −1 @@
1# open-sse/services/ — Routing Engine & Cross-Cutting Services
2
3**Purpose**: 134 service modules (top-level) powering request routing, rate limiting, quota management, token refresh, fallback strategies, and runtime state. The combo routing engine (`combo.ts`) is the core; supporting services handle resilience, accounting, and decision-making.
4
5Live count: `ls open-sse/services/*.ts | wc -l` (currently 134). More including sub-dirs like `autoCombo/` and `compression/`.
6
7---
8
9## Combo Routing Engine
10
11- **`combo.ts`** — Entry point for multi-model routing. **`handleComboChat()`** iterates through targets in order until success or all fail. **`resolveComboTargets()`** expands combo config into ordered `ResolvedComboTarget[]` (provider + model + account + credentials).
12- **Strategies** (17): `priority`, `weighted`, `fill-first`, `round-robin`, `P2C`, `random`, `least-used`, `reset-aware`, `reset-window`, `cost-optimized`, `strict-random`, `auto`, `lkgp`, `context-optimized`, `context-relay`, `headroom`, `fusion`. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
13- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with per-target error handling and circuit breaker checks.
14
15## Key Services
16
17### Quota & Rate Limiting
18
19- **`rateLimitManager.ts`** — Token bucket per API key + provider combo. Rejects before dispatch.
20- **`usage.ts`** — Per-request token/cost consumption tracking.
21- **`quotaCache.ts`** — In-memory quota snapshots, pre-loaded at startup.
22
23### Account & Token Management
24
25- **`tokenRefresh.ts`** — OAuth token expiration detection and refresh.
26- **`accountFallback.ts`** — Account switching on quota/rate-limit. Also houses model lockout.
27- **`sessionManager.ts`** — Request session state across retries.
28
29### Request Routing & Intelligence
30
31- **`wildcardRouter.ts`** — Wildcard route matching in combo configs.
32- **`intentClassifier.ts`** — Request intent classification for intelligent routing.
33- **`taskAwareRouter.ts`** — Task-type-based routing (reasoning → o1, code-gen → Cursor).
34- **`targetRequestSanitizer.ts`** — Final provider/model-aware parameter sanitation after routing resolution and before executor dispatch.
35- **`thinkingBudget.ts`** — Thinking token allocation for o1/o3 models.
36- **`contextManager.ts`** — Routing context injection (system prompts, memory).
37
38### Model Lifecycle & Fallback
39
40- **`modelDeprecation.ts`** — Deprecated model detection and successor routing.
41- **`modelFamilyFallback.ts`** — T5 intra-family fallback chains.
42- **`emergencyFallback.ts`** — Last-resort fallback to stable free providers.
43
44### State & Detection
45
46- **`workflowFSM.ts`** — Multi-turn workflow state machine.
47- **`backgroundTaskDetector.ts`** — Long-running task detection for batch routing.
48- **`ipFilter.ts`** — IP-based routing rules.
49- **`signatureCache.ts`** — Request signature caching for deduplication.
50- **`volumeDetector.ts`** — Volume spike detection for rate-limit escalation.
51- **`contextHandoff.ts`** — Session context serialization for A2A handoff.
52
53### Prompt Compression Pipeline (`compression/`)
54
55- **`strategySelector.ts`** — Compression mode selection (off/lite/standard/aggressive/ultra/rtk/stacked).
56- **`lite.ts`** — 5 lite techniques (whitespace, dedup, tool results, redundant removal, image URLs).
57- **`caveman.ts` / `cavemanRules.ts`** — Caveman-style semantic condensation with rule packs.
58- **`engines/rtk/`** — RTK tool-output compression (command detection, JSON filters, dedup, truncation).
59- **`engines/registry.ts`** — Engine registry for standalone and stacked pipelines.
60- **`stats.ts`** — Per-request compression stats.
61- **`types.ts`** — Shared types (`CompressionMode`, `CompressionConfig`, `CompressionStats`).
62
63---
64
65## Adding a New Service
66
671. Create `open-sse/services/[serviceName].ts`
682. Export main handler function
693. Add unit tests in `tests/unit/services/`
704. Integrate into `handlers/chatCore.ts` (if routing-related) or `combo.ts`
715. Document in this file
72
73## Anti-Patterns
74
75- Synchronous DB calls in `combo.ts` hot path — pre-compute and cache
76- Retry logic in handlers — use `retry()` from resilience service
77- Direct provider config access — use `providerRegistry` getter functions
78- Hardcoded fallback chains — define in `modelFamilyFallback.ts`
79- State mutations across concurrent requests — use request-scoped context only
80
diegosouzapw/OmniRoute · .github/copilot-instructions.md
@@ +1 @@
1# OmniRoute PR and Coverage Instructions
2
3- Treat `npm run test:coverage` as a required gate for PR work.
4- The repository minimum is `60%` for statements, lines, functions, and branches.
5- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.
6- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.
7- Prefer the smallest test layer that proves the behavior:
8 - unit tests first
9 - integration tests when multiple modules or DB state are involved
10 - e2e only when the behavior is truly UI or workflow-dependent
11- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.
12- In the final PR report, include:
13 - the commands you ran
14 - the changed test files
15 - the final coverage result
16
@@ −1 +1 @@
1−# open-sse/services/ — Routing Engine & Cross-Cutting Services
1+# OmniRoute PR and Coverage Instructions
22
3−**Purpose**: 134 service modules (top-level) powering request routing, rate limiting, quota management, token refresh, fallback strategies, and runtime state. The combo routing engine (`combo.ts`) is the core; supporting services handle resilience, accounting, and decision-making.
4−
5−Live count: `ls open-sse/services/*.ts | wc -l` (currently 134). More including sub-dirs like `autoCombo/` and `compression/`.
6−
7−---
8−
9−## Combo Routing Engine
10−
11−- **`combo.ts`** — Entry point for multi-model routing. **`handleComboChat()`** iterates through targets in order until success or all fail. **`resolveComboTargets()`** expands combo config into ordered `ResolvedComboTarget[]` (provider + model + account + credentials).
12−- **Strategies** (17): `priority`, `weighted`, `fill-first`, `round-robin`, `P2C`, `random`, `least-used`, `reset-aware`, `reset-window`, `cost-optimized`, `strict-random`, `auto`, `lkgp`, `context-optimized`, `context-relay`, `headroom`, `fusion`. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
13−- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with per-target error handling and circuit breaker checks.
14−
15−## Key Services
16−
17−### Quota & Rate Limiting
18−
19−- **`rateLimitManager.ts`** — Token bucket per API key + provider combo. Rejects before dispatch.
20−- **`usage.ts`** — Per-request token/cost consumption tracking.
21−- **`quotaCache.ts`** — In-memory quota snapshots, pre-loaded at startup.
22−
23−### Account & Token Management
24−
25−- **`tokenRefresh.ts`** — OAuth token expiration detection and refresh.
26−- **`accountFallback.ts`** — Account switching on quota/rate-limit. Also houses model lockout.
27−- **`sessionManager.ts`** — Request session state across retries.
28−
29−### Request Routing & Intelligence
30−
31−- **`wildcardRouter.ts`** — Wildcard route matching in combo configs.
32−- **`intentClassifier.ts`** — Request intent classification for intelligent routing.
33−- **`taskAwareRouter.ts`** — Task-type-based routing (reasoning → o1, code-gen → Cursor).
34−- **`targetRequestSanitizer.ts`** — Final provider/model-aware parameter sanitation after routing resolution and before executor dispatch.
35−- **`thinkingBudget.ts`** — Thinking token allocation for o1/o3 models.
36−- **`contextManager.ts`** — Routing context injection (system prompts, memory).
37−
38−### Model Lifecycle & Fallback
39−
40−- **`modelDeprecation.ts`** — Deprecated model detection and successor routing.
41−- **`modelFamilyFallback.ts`** — T5 intra-family fallback chains.
42−- **`emergencyFallback.ts`** — Last-resort fallback to stable free providers.
43−
44−### State & Detection
45−
46−- **`workflowFSM.ts`** — Multi-turn workflow state machine.
47−- **`backgroundTaskDetector.ts`** — Long-running task detection for batch routing.
48−- **`ipFilter.ts`** — IP-based routing rules.
49−- **`signatureCache.ts`** — Request signature caching for deduplication.
50−- **`volumeDetector.ts`** — Volume spike detection for rate-limit escalation.
51−- **`contextHandoff.ts`** — Session context serialization for A2A handoff.
52−
53−### Prompt Compression Pipeline (`compression/`)
54−
55−- **`strategySelector.ts`** — Compression mode selection (off/lite/standard/aggressive/ultra/rtk/stacked).
56−- **`lite.ts`** — 5 lite techniques (whitespace, dedup, tool results, redundant removal, image URLs).
57−- **`caveman.ts` / `cavemanRules.ts`** — Caveman-style semantic condensation with rule packs.
58−- **`engines/rtk/`** — RTK tool-output compression (command detection, JSON filters, dedup, truncation).
59−- **`engines/registry.ts`** — Engine registry for standalone and stacked pipelines.
60−- **`stats.ts`** — Per-request compression stats.
61−- **`types.ts`** — Shared types (`CompressionMode`, `CompressionConfig`, `CompressionStats`).
62−
63−---
64−
65−## Adding a New Service
66−
67−1. Create `open-sse/services/[serviceName].ts`
68−2. Export main handler function
69−3. Add unit tests in `tests/unit/services/`
70−4. Integrate into `handlers/chatCore.ts` (if routing-related) or `combo.ts`
71−5. Document in this file
72−
73−## Anti-Patterns
74−
75−- Synchronous DB calls in `combo.ts` hot path — pre-compute and cache
76−- Retry logic in handlers — use `retry()` from resilience service
77−- Direct provider config access — use `providerRegistry` getter functions
78−- Hardcoded fallback chains — define in `modelFamilyFallback.ts`
79−- State mutations across concurrent requests — use request-scoped context only
3+- Treat `npm run test:coverage` as a required gate for PR work.
4+- The repository minimum is `60%` for statements, lines, functions, and branches.
5+- If a PR changes production code in `src/`, `open-sse/`, `electron/`, or `bin/`, it must include automated tests in the same PR.
6+- When reviewing or updating a PR, if the report shows missing tests or coverage below `60%`, do not stop after reporting the problem. Add or update tests in the PR first, rerun the coverage gate, and only then ask for confirmation.
7+- Prefer the smallest test layer that proves the behavior:
8+ - unit tests first
9+ - integration tests when multiple modules or DB state are involved
10+ - e2e only when the behavior is truly UI or workflow-dependent
11+- For bug issues, try to encode the reproduction as an automated test before or alongside the fix.
12+- In the final PR report, include:
13+ - the commands you ran
14+ - the changed test files
15+ - the final coverage result
8016
