| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 11 | 0% |
| Commands | 0 | 1 | 0 | 0% |
| Section tags | 1 | 4 | 2 | 14% |
What each file covers
Sections
0 shared · 1 only in A · 11 only in B- − OmniRoute PR and Coverage Instructions
- + 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
Commands
0 shared · 1 only in A · 0 only in B- − npm run test:coverage
Section tags
1 shared · 4 only in A · 2 only in B- − test
- − testing-strategy
- − git-pr
- − agent-behaviour
- + performance
- + deployment
- code-style
Line diff
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
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
@@ −1 +1 @@
1−# OmniRoute PR and Coverage Instructions
1+# open-sse/services/ — Routing Engine & Cross-Cutting Services
22
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
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
1680
