AGENTS.md

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