AGENTS.md

1# omniroute — Agent Guidelines
2 
3## Project
4 
5Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
6with **290 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
7Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
8SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
9with **MCP Server** (104 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
10 
11> **Live counts (v3.8.49)**: providers 290 · MCP tools 104 · MCP scopes 30 · A2A skills 6 ·
12> open-sse services 134 · routing strategies 17 · auto-combo scoring factors 12 ·
13> DB modules 95 · DB migrations 110 · base tables 17 · search providers 11 ·
14> i18n locales 42. **Refresh with `npm run check:docs-all`.**
15 
16## Doc Accuracy Discipline (read before writing any doc)
17 
18> **If `grep -rn "name" src/ open-sse/ bin/` returns nothing, the name does not exist. Do not document it.**
19 
20The recurring failure mode in AI-generated docs is _plausible-but-unverified specifics_.
21Every claim in a `.md` file under `docs/` should be verifiable against the source.
22 
23**Rules (enforced by `npm run check:fabricated-docs`):**
24 
251. **Never state an API name, endpoint, path, CLI command, or env var without grepping for it first.**
26```bash
27   grep -rn "theName" src/ open-sse/ bin/
28   # 0 hits → do not document
29```
302. **Never write a line count, file size, migration count, provider count, or strategy count from memory.**
31```bash
32   wc -l <file>           # exact line count
33   ls <dir>/*.ts | wc -l  # file count
34```
353. **Every code example should be copy-pasted from real usage or actually run** — not synthesized.
36   Link to a real call site (`path:line`) instead of inventing a signature.
374. **Prefer citing real source (`file.ts:line`) over paraphrasing behavior** — verifiable and self-correcting.
385. **A shorter doc that is 100% accurate beats a comprehensive one with fabrications.**
39   Wrong docs cost more than missing docs, because people trust and act on them.
40 
41The script `scripts/check/check-fabricated-docs.mjs` extracts every route path, env var, hook
42name, function name, and file reference from `docs/**/*.md` and verifies each one against the
43codebase. Run it locally before pushing docs; it runs in CI via `npm run check:docs-all`.
44 
45## Stack
46 
47- **Runtime**: Next.js 16 (App Router), Node.js `>=22.0.0 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
48- **Language**: TypeScript 6.0 (`src/`) + JavaScript (`open-sse/`, `electron/`)
49- **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
50- **Streaming**: SSE via `open-sse` internal workspace package
51- **Styling**: Tailwind CSS v4
52- **i18n**: next-intl with 42 locales (`src/i18n/messages/`) — refresh with `ls src/i18n/messages/*.json | wc -l`
53- **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
54- **Schemas**: Zod v4 for all API / MCP input validation
55 
56---
57 
58## Build, Lint, and Test Commands
59 
60| Command                             | Description                                                        |
61| ----------------------------------- | ------------------------------------------------------------------ |
62| `npm run dev`                       | Start Next.js dev server                                           |
63| `npm run build`                     | Production build: `next build` → `.build/next/` + assemble `dist/` |
64| `npm run build:release`             | Clean rebuild + HEAD sentinel (`dist/BUILD_SHA`) — use for deploy  |
65| `npm run start`                     | Run production build                                               |
66| `npm run build:cli`                 | Build CLI package                                                  |
67| `npm run lint`                      | ESLint on all source files                                         |
68| `npm run typecheck:core`            | TypeScript core type checking                                      |
69| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any)                                  |
70| `npm run check`                     | Run lint + test                                                    |
71| `npm run check:cycles`              | Check for circular dependencies                                    |
72| `npm run electron:dev`              | Run Electron app in dev mode                                       |
73| `npm run electron:build`            | Build Electron app for current OS                                  |
74 
75**Build output layout:**
76 
77| Directory | Purpose                                            | Gitignored |
78| --------- | -------------------------------------------------- | ---------- |
79| `src/`    | Application source (TypeScript / TSX)              | No         |
80| `.build/` | Build intermediates (`distDir = .build/next`)      | Yes        |
81| `dist/`   | Shippable bundle assembled by `assembleStandalone` | Yes        |
82 
83The pipeline is a single `next build` pass — intermediates land in `.build/next/`, the
84assembled bundle in `dist/`. VPS deploys rsync `dist/` into the remote
85`/usr/lib/node_modules/omniroute/app/` directory (VPS image path is unchanged).
86 
87### Running Tests
88 
89```bash
90# All tests (unit + vitest + ecosystem + e2e)
91npm run test:all
92 
93# Single test file (Node.js native test runner — most tests use this)
94node --import tsx/esm --test tests/unit/your-file.test.ts
95node --import tsx/esm --test tests/unit/plan3-p0.test.ts
96node --import tsx/esm --test tests/unit/fixes-p1.test.ts
97node --import tsx/esm --test tests/unit/security-fase01.test.ts
98 
99# Integration tests
100node --import tsx/esm --test tests/integration/*.test.ts
101 
102# Vitest (MCP server, autoCombo)
103npm run test:vitest
104 
105# E2E with Playwright
106npm run test:e2e
107 
108# Protocol clients E2E (MCP transports, A2A)
109npm run test:protocols:e2e
110 
111# Ecosystem compatibility tests
112npm run test:ecosystem
113 
114# Coverage (see CONTRIBUTING.md)
115npm run test:coverage
116```
117 
118**For authoritative coverage requirements, test execution, and PR gates, see [`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests).**
119 
120---
121 
122## Code Style Guidelines
123 
124### Formatting (Prettier — enforced via lint-staged)
125 
1262 spaces · semicolons required · double quotes (`"`) · 100 char width · es5 trailing commas.
127Always run `prettier --write` on changed files.
128 
129### TypeScript
130 
131- **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler`
132- `strict: false` — prefer explicit types, don't rely on inference
133- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
134 
135### ESLint Rules
136 
137- **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func`
138- **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn
139- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/`
140 
141### Naming
142 
143| Element             | Convention                       | Example                              |
144| ------------------- | -------------------------------- | ------------------------------------ |
145| Files               | camelCase / kebab-case           | `chatCore.ts`, `tokenHealthCheck.ts` |
146| React components    | PascalCase                       | `Dashboard.tsx`, `ProviderCard.tsx`  |
147| Functions/variables | camelCase                        | `getHealth()`, `switchCombo()`       |
148| Constants           | UPPER_SNAKE                      | `MAX_RETRIES`, `DEFAULT_TIMEOUT`     |
149| Interfaces          | PascalCase (`I` prefix optional) | `ProviderConfig`                     |
150| Enums               | PascalCase (members too)         | `LogLevel.Error`                     |
151 
152### Imports
153 
154- **Order**: external → internal (`@/`, `@omniroute/open-sse`) → relative (`./`, `../`)
155- **No barrel imports** from `localDb.ts` — import from the specific `db/` module instead
156 
157### Error Handling
158 
159- try/catch with specific error types; always log with context (pino logger)
160- Never silently swallow errors in SSE streams — use abort signals for cleanup
161- Return proper HTTP status codes (4xx client, 5xx server)
162 
163### Security
164 
165- **NEVER** commit API keys, secrets, or credentials
166- Validate all user inputs with Zod schemas
167- Auth middleware required on all API routes
168- Never log SQLite encryption keys
169- Sanitize user content (dompurify for HTML)
170- **Public upstream OAuth identifiers** (Gemini / Antigravity / Windsurf-style client_id/secret + Firebase Web keys extracted from public CLIs): use `resolvePublicCred()` from `open-sse/utils/publicCreds.ts`, **never** as string literals. Full pattern in `docs/security/PUBLIC_CREDS.md`.
171- **Error responses** (HTTP / SSE / executor / MCP): use `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts`, **never** put raw `err.stack` / `err.message` in a Response body. Full pattern in `docs/security/ERROR_SANITIZATION.md`.
172- **`exec()` / `spawn()` with runtime values**: pass via the `env` option, **never** string-interpolate paths/values into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
173- Prefer secure-by-default libraries when available — see [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) for the curated list (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink, etc.).
174 
175---
176 
177## Architecture
178 
179### Data Layer (`src/lib/db/`)
180 
181All persistence uses SQLite through **95 domain-specific modules** in `src/lib/db/`. Top modules:
182 
183- Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
184- Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
185- Routing: `combos.ts`, `modelComboMappings.ts`, `domainState.ts`, `commandCodeAuth.ts`
186- Auth: `apiKeys.ts`, `secrets.ts`, `registeredKeys.ts`, `sessionAccountAffinity.ts`
187- Usage / billing: `quotaSnapshots.ts`, `creditBalance.ts`, `usage*.ts`, `compressionCacheStats.ts`
188- Storage: `backup.ts`, `cleanup.ts`, `jsonMigration.ts`, `healthCheck.ts`, `databaseSettings.ts`
189- Extension modules: `evals.ts`, `webhooks.ts`, `reasoningCache.ts`, `readCache.ts`, `tierConfig.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `batches.ts`, `files.ts`, `syncTokens.ts`, `proxies.ts`, `oneproxy.ts`, `upstreamProxy.ts`, `versionManager.ts`, `cliToolState.ts`, `prompts.ts`, `detailedLogs.ts`, `contextHandoffs.ts`, `compression.ts`, `stats.ts`
190 
191Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Drift detection: `npm run check:docs-counts`.
192Schema migrations live in `db/migrations/` (**110 files** as of v3.8.43) and run via `migrationRunner.ts`.
193`src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
194 
195#### DB Internals
196 
197- **`core.ts`**: `getDbInstance()` returns a singleton `better-sqlite3` instance with WAL
198  journaling. `SCHEMA_SQL` defines **17 base tables** (verify with `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for the bookkeeping `_omniroute_migrations` table). Helpers: `rowToCamel`, `encryptConnectionFields`.
199- **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
200  Tracks applied migrations in `_omniroute_migrations` table.
201- **Migrations**: 110 files (`001_initial_schema.sql` → `110_*.sql`).
202  Each migration is idempotent and runs in a transaction. Live count: `ls src/lib/db/migrations/*.sql | wc -l`.
203- **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
204  Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
205  `combos.ts` → `combos`). Encryption helpers protect sensitive fields at rest.
206- **`localDb.ts`** re-exports all domain modules — consumers import from here for convenience.
207 
208### API Route Layer (`src/app/api/v1/`)
209 
210Next.js App Router routes — each follows a consistent pattern:
211 
212```
213Route → CORS preflight → Body validation (Zod) → Optional auth (extractApiKey/isValidApiKey)
214  → API key policy enforcement (enforceApiKeyPolicy) → Handler delegation (open-sse)
215```
216 
217| Route                           | Handler                   | Notes                                                         |
218| ------------------------------- | ------------------------- | ------------------------------------------------------------- |
219| `chat/completions/route.ts`     | `handleChat()`            | + prompt injection guard (clones request)                     |
220| `responses/route.ts`            | `handleChat()` (unified)  | Responses API format                                          |
221| `embeddings/route.ts`           | `handleEmbedding()`       | Model listing + creation                                      |
222| `images/generations/route.ts`   | `handleImageGeneration()` | Model listing + creation                                      |
223| `audio/transcriptions/route.ts` | audio handler             | Multipart form data                                           |
224| `audio/speech/route.ts`         | TTS handler               | Binary audio response                                         |
225| `videos/generations/route.ts`   | video handler             | ComfyUI/SD WebUI                                              |
226| `music/generations/route.ts`    | music handler             | ComfyUI workflows                                             |
227| `moderations/route.ts`          | moderation handler        | Content safety                                                |
228| `rerank/route.ts`               | rerank handler            | Document relevance                                            |
229| `search/route.ts`               | search handler            | Web search (12 providers per `open-sse/handlers/search.ts:6`) |
230 
231**No global Next.js middleware file** — interception is route-specific. Auth is optional
232(controlled by `REQUIRE_API_KEY` env). Prompt injection guard is unique to chat completions.
233 
234### Request Pipeline (`open-sse/`)
235 
236The `open-sse/` workspace is the core streaming engine. Full request flow:
237 
238```
239Client Request
240  → src/app/api/v1/.../route.ts (Next.js route)
241    → open-sse/handlers/chatCore.ts::handleChatCore()
242      → Semantic/signature cache check
243      → Rate limit check (rateLimitManager)
244      → Combo routing? → open-sse/services/combo.ts::handleComboChat()
245        → resolveComboTargets() → ordered ResolvedComboTarget[]
246        → For each target: handleSingleModel() (wraps chatCore)
247      → translateRequest() (open-sse/translator/)
248        → Convert source format (e.g., OpenAI) → target format (e.g., Claude)
249      → getExecutor() → provider-specific executor instance
250        → executor.execute() (BaseExecutor → DefaultExecutor or provider-specific)
251          → buildUrl() + buildHeaders() + transformRequest()
252          → fetch() to upstream provider
253          → Retry logic with exponential backoff
254      → Response translation back to client format
255      → If Responses API: responsesTransformer.ts TransformStream
256  → SSE stream or JSON response to client
257```
258 
259**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
260`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
261`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`.
262 
263**Upstream headers**: merged after default auth; same header name replaces executor value.
264**T5 intra-family fallback** recomputes headers using only the fallback model id.
265Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,
266Zod schemas, and unit tests aligned when editing.
267 
268### Provider Categories
269 
270- **Free** (2): Qoder AI, Kiro AI
271- **OAuth** (13): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline, Kiro, Qoder, Gemini, Windsurf (v3.8), GitLab Duo (v3.8)
272- **API Key** (120+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
273  Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
274  HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
275  Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway,
276  Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld,
277  NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa,
278  Tavily, OpenCode Zen/Go, Bailian Coding Plan, DeepInfra, Vercel AI Gateway,
279  Lambda AI, SambaNova, nScale, OVHcloud AI, Baseten, PublicAI, Moonshot AI,
280  Meta Llama API, v0 (Vercel), Morph, Featherless AI, FriendliAI, LlamaGate,
281  Galadriel, Weights & Biases Inference, Volcengine, AI21 Labs, Venice.ai,
282  Codestral, Upstage, Maritalk, Xiaomi MiMo, Inference.net, NanoGPT, Predibase,
283  Bytez, Heroku AI, Databricks, Snowflake Cortex, GigaChat (Sber), CrofAI,
284  AgentRouter, ChatGPT Web, Baidu Qianfan, AWS Polly, RunwayML, GitLab Duo,
285  Amazon Q, Empower, Poe, and many more.
286- **Self-Hosted** (8+): LM Studio, vLLM, Lemonade, Llamafile, Triton, Docker Model Runner, Xinference, Oobabooga
287- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
288 
289Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
290 
291### Executors (`open-sse/executors/`)
292 
293Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
294`antigravity.ts`, `github.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
295`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
296 
297#### Executor Internals
298 
299- **`base.ts`** (`BaseExecutor`): Abstract base with `buildUrl()`, `buildHeaders()`,
300  `transformRequest()`, retry logic (exponential backoff), and `execute()`. Subclasses
301  override URL/header/transform methods for provider-specific behavior.
302- **`default.ts`** (`DefaultExecutor extends BaseExecutor`): Handles most OpenAI-compatible
303  providers. Reads provider config from `providerRegistry.ts` to resolve base URL, auth
304  header format, and request transformations.
305- **`getExecutor()`** (`executors/index.ts`): Factory that returns the correct executor
306  instance based on provider ID. Provider-specific executors (Cursor, Codex, Vertex, etc.)
307  override only what differs from the default.
308 
309### Translator (`open-sse/translator/`)
310 
311Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
312Includes request/response translators with helpers for image handling.
313 
314#### Translator Internals
315 
316- **`translator/index.ts`**: Exports `translateRequest()` and format constants. Called by
317  `chatCore.ts` before executor dispatch.
318- **Flow**: `translateRequest(body, sourceFormat, targetFormat)` → detects source format
319  (OpenAI, Anthropic, Gemini) → applies the matching translator module → returns
320  transformed body ready for the target provider.
321- **Response translation** runs in reverse after upstream response, converting back to
322  the client's expected format.
323 
324### Transformer (`open-sse/transformer/`)
325 
326`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
327 
328#### Transformer Internals
329 
330- **`createResponsesApiTransformStream()`**: Returns a `TransformStream` that converts
331  Chat Completions SSE chunks (`data: {"choices":[...]}`) into Responses API SSE events
332  (`response.output_item.added`, `response.output_text.delta`, etc.).
333- Used when the client sends a Responses API request: the request is internally converted
334  to Chat Completions format, dispatched normally, and the response is piped through this
335  transform stream before reaching the client.
336 
337### Services (`open-sse/services/`)
338 
339134 service modules in `open-sse/services/` (top-level only; more including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules:
340`combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
341`rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
342`autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
343`contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`,
344`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`,
345`signatureCache.ts`, `volumeDetector.ts`, `contextHandoff.ts`, `compression/` (prompt
346compression pipeline), and more.
347 
348#### Prompt Compression Pipeline (`compression/`)
349 
350Modular prompt compression that runs proactively before the existing reactive context manager.
351 
352- **`strategySelector.ts`**: Selects compression mode based on config, compression combo assignments,
353  combo overrides, auto-trigger thresholds, and defaults. Priority: assigned compression combo >
354  combo override > auto-trigger > default mode > off.
355- **`lite.ts`**: 5 lite-mode techniques: `collapseWhitespace`, `dedupSystemPrompt`,
356  `compressToolResults`, `removeRedundantContent`, `replaceImageUrls`. Target: 10-15% savings at
357  <1ms latency.
358- **`caveman.ts` / `cavemanRules.ts`**: Caveman-style semantic condensation backed by built-in
359  rules plus file-loaded language packs under `compression/rules/`.
360- **`engines/rtk/`**: Rule-based terminal/tool-output compression inspired by RTK patterns. Detects
361  command output classes, applies JSON filter packs, deduplicates repeated lines, strips ANSI/code
362  noise, and preserves errors/actionable context. The RTK JSON DSL supports replace,
363  match-output short-circuit, strip/keep, per-line truncation, head/tail/max-line truncation,
364  inline tests, trust-gated project/global custom filters, and optional redacted raw-output
365  retention for authenticated recovery.
366- **`engines/registry.ts`**: Registers engines (`caveman`, `rtk`) and powers stacked pipelines.
367- **`stats.ts`**: Per-request compression stats tracking (original tokens, compressed tokens,
368  savings %, techniques used, engine breakdown, compression combo id).
369- **`types.ts`**: `CompressionMode` (off/lite/standard/aggressive/ultra/rtk/stacked),
370  `CompressionConfig`, `CompressionStats`, `CompressionResult`.
371- DB settings in `src/lib/db/compression.ts`, compression combos in
372  `src/lib/db/compressionCombos.ts`, API routes under `src/app/api/settings/compression/`,
373  `src/app/api/context/*`, and preview/language-pack routes under `src/app/api/compression/*`.
374 
375#### Combo Routing Engine (`combo.ts`)
376 
377- **`handleComboChat()`**: Entry point for combo-routed requests. Receives the combo config
378  and iterates through targets in order until one succeeds or all fail.
379- **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
380  `ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
381- **Strategies** (17): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
382  reset-window, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, headroom, fusion. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
383- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
384  per-target error handling and circuit breaker checks.
385 
386### Domain Layer (`src/domain/`)
387 
388Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
389`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`,
390`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`.
391 
392### MCP Server (`open-sse/mcp-server/`)
393 
394**104 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 42-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), pool (6), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (31 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
395 
396**Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
397route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,
398set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,
399best_combo_for_task, explain_route, get_session_snapshot, db_health_check, sync_pricing.
400 
401**Cache tools** (2): cache_stats, cache_flush.
402 
403**Compression tools** (5): compression_status, compression_configure, set_compression_engine,
404list_compression_combos, compression_combo_stats.
405 
406**1proxy tools** (3): oneproxy_fetch, oneproxy_rotate, oneproxy_stats.
407 
408**Memory tools** (3): memory_search, memory_add, memory_clear.
409 
410**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
411 
412**Agent-skill tools** (3): A2A skill discovery / invocation bridges.
413 
414**Gamification tools** (8): levels, badges, leaderboard, and community-federation queries.
415 
416**Plugin tools** (8): plugin marketplace listing, install/enable/disable, and runtime inspection.
417 
418**Notion tools** (6) + **Obsidian tools** (22): knowledge-base read/write integrations (the largest tool family — vault search, note CRUD, WebDAV-backed file ops).
419 
420#### MCP Internals
421 
422- **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema,
423handler: async (args) => {...} }`. Zod validates inputs before the handler fires.
424- **`createMcpServer()`** and **`startMcpStdio()`** exported from `mcp-server/index.ts`.
425  `createMcpServer()` wires all tool sets; `startMcpStdio()` launches the stdio transport.
426- **Transports**: stdio (CLI `omniroute --mcp`), SSE (`/api/mcp/sse`), Streamable HTTP
427  (`/api/mcp/stream`). All share the same tool/scope engine.
428- **Scopes** (30): Control which tool categories an API key can access. Enforcement happens
429  before handler dispatch.
430- **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name,
431  args, success/failure, API key attribution, and timestamp.
432 
433### A2A Server (`src/lib/a2a/`)
434 
435JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
436Agent Card at `/.well-known/agent.json`.
437Skills (6): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`, `listCapabilities.ts`.
438 
439#### A2A Internals
440 
441- **`taskManager.ts`**: State machine lifecycle for tasks: `submitted → working →
442completed | failed | canceled`. Tasks have TTL and are cleaned up automatically.
443- **JSON-RPC methods**: `message/send` (sync), `message/stream` (SSE), `tasks/get`,
444  `tasks/cancel`. Dispatched via `POST /a2a`.
445- **Skills**: Registered in a DB-backed registry. Each skill receives task context
446  (messages, metadata) and returns structured results. `quotaManagement.ts` summarizes
447  quota; `smartRouting.ts` recommends routing decisions.
448- **Agent Card**: `/.well-known/agent.json` exposes capabilities, skills, and metadata
449  for client auto-discovery.
450 
451### ACP Module (`src/lib/acp/`)
452 
453Agent Communication Protocol registry and manager.
454 
455### Memory System (`src/lib/memory/`)
456 
457Extraction, injection, retrieval, summarization, and store modules for persistent
458conversational memory across sessions.
459 
460### Skills System (`src/lib/skills/`)
461 
462Extensible skill framework: registry, executor, sandbox, built-in skills,
463custom skill support, interception, and injection.
464 
465#### Skills Internals
466 
467- **`registry.ts`**: DB-backed skill registration and discovery. Skills have metadata
468  (name, description, version, enabled status) stored in SQLite.
469- **`executor.ts`**: Execution engine with configurable timeout and retry logic.
470  Receives skill name + input, looks up the skill, runs it in the sandbox.
471- **`sandbox.ts`**: Isolation layer for custom (user-provided) skills. Limits resource
472  access and execution time.
473- **Built-in skills**: Ship with OmniRoute (e.g., quota management, routing). Located
474  alongside the registry.
475- **Interception/Injection**: Skills can intercept requests in the pipeline (pre/post
476  processing) or inject context into prompts.
477 
478### Compliance (`src/lib/compliance/`)
479 
480Policy index for compliance enforcement.
481 
482### MITM Proxy (`src/mitm/`)
483 
484MITM proxy capability with certificate management, DNS handling, and target routing.
485 
486### Middleware (`src/middleware/`)
487 
488Request middleware including `promptInjectionGuard.ts`.
489 
490### Guardrails (`src/lib/guardrails/`)
491 
492Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open. The `pii-masker` guardrail is registered and runs on every request, but its data-mutating logic is **opt-in** and OFF by default — it only redacts when `PII_REDACTION_ENABLED` (request) / `PII_RESPONSE_SANITIZATION` (response + streaming) are enabled (both `defaultValue: "false"`); with them off, payloads pass through untouched. A request can additionally opt OUT of any guardrail via header (`x-omniroute-disabled-guardrails`). Never make PII default-on (Hard Rule #20). See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).
493 
494### Cloud Agents (`src/lib/cloudAgent/`)
495 
496`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md).
497 
498### Evals (`src/lib/evals/`)
499 
500Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md).
501 
502### Webhooks (`src/lib/webhookDispatcher.ts`)
503 
504HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md).
505 
506### Authorization Pipeline (`src/server/authz/`)
507 
508`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md).
509 
510### Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)
511 
512Hybrid in-memory + SQLite cache for `reasoning_content`. Re-injects on multi-turn for strict providers (DeepSeek V4, Kimi K2, Qwen-Thinking, GLM, xiaomi-mimo). See [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md).
513 
514### Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)
515 
516Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md).
517 
518### Adding a New Provider
519 
5201. Register in `src/shared/constants/providers.ts`
5212. Add executor in `open-sse/executors/` (if custom logic needed)
5223. Add translator in `open-sse/translator/` (if non-OpenAI format)
5234. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
5245. Add models in `open-sse/config/providerRegistry.ts`
525 
526---
527 
528## Subdirectory AGENTS.md Files
529 
530- **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
531- **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
532 
533## Reference Documentation (docs/)
534 
535For any non-trivial change, read the matching deep-dive first:
536 
537| Area                                       | Doc                                                                                                             |
538| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
539| Repo navigation                            | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md)                                    |
540| Architecture                               | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                        |
541| Engineering reference                      | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)                    |
542| Auto-Combo (12-factor, 18 strategies)      | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                                                      |
543| Resilience (3 layers)                      | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md)                                |
544| Skills                                     | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md)                                                        |
545| Memory                                     | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md)                                                        |
546| Cloud agents                               | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md)                                              |
547| Guardrails                                 | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)                                                    |
548| Evals                                      | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md)                                                          |
549| Compliance                                 | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md)                                                    |
550| Webhooks                                   | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md)                                                    |
551| Authz                                      | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)                                          |
552| Stealth                                    | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                              |
553| Reasoning replay                           | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                          |
554| Agent protocols (A2A / ACP / Cloud)        | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)                          |
555| MCP server                                 | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)                                                |
556| A2A server                                 | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)                                                |
557| API reference                              | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |
558| Provider catalog (auto-generated)          | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)                                  |
559| Tunnels                                    | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)                                                        |
560| Electron desktop                           | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                                                |
561| Release flow                               | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md)                                                |
562| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                      |
563| Cluster opt-in profiles (memory, bifrost)  | [`docs/architecture/cluster-decisions.md`](docs/architecture/cluster-decisions.md)                              |
564 
565---
566 
567## Fork / Upstream Workflow
568 
569This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operational
570changes (for example GHCR image publishing, personal deployment workflows, or local
571automation) out of upstream contribution PRs.
572 
573When preparing a PR for upstream, always start the work branch from the upstream
574**default branch** — the active `release/vX.Y.Z` line (today `release/v3.8.49`).
575Never branch from `main`: `main` only receives release squash-merges, so a branch
576cut there is weeks behind and produces conflict-heavy PRs
577(see `CONTRIBUTING.md` and `docs/ops/BRANCHING_MODEL.md`):
578 
579```bash
580git fetch upstream
581# the default branch is the active release line, e.g. release/v3.8.49
582git switch -c &lt;branch-name&gt; upstream/release/vX.Y.Z
583```
584 
585Only cherry-pick or reapply the changes intended for the upstream PR.
586 
587---
588 
589## Review Focus
590 
591- **DB ops** go through `src/lib/db/` modules, never raw SQL in routes
592- **Provider requests** flow through `open-sse/handlers/`
593- **MCP/A2A pages** are tabs inside `/dashboard/endpoint`, not standalone routes
594- **No memory leaks** in SSE streams (abort signals, cleanup)
595- **Rate limit headers** must be parsed correctly
596- All API inputs validated with **Zod schemas**
597- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
598- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`
599- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills
600- **⛔ NEVER close a contributor's PR** after using their code — always merge via GitHub so they get credit. See `.agents/workflows/review-prs.md` for full policy.
601