Comparison

A · AGENTS.md · diegosouzapw/OmniRoute B · AGENTS.md · diegosouzapw/OmniRoute

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	53	6	0%
Commands	1	28	0	3%
Section tags	3	13	1	18%

What each file covers

Sections

0 shared · 53 only in A · 6 only in B

− omniroute — Agent Guidelines
− Project
− Doc Accuracy Discipline (read before writing any doc)
− Stack
− Build, Lint, and Test Commands
− Running Tests
− All tests (unit + vitest + ecosystem + e2e)
− Single test file (Node.js native test runner — most tests use this)
− Integration tests
− Vitest (MCP server, autoCombo)
− E2E with Playwright
− Protocol clients E2E (MCP transports, A2A)
− Ecosystem compatibility tests
− Coverage (see CONTRIBUTING.md)
− Code Style Guidelines
− Formatting (Prettier — enforced via lint-staged)
− TypeScript
− ESLint Rules
− Naming
− Imports
− Error Handling
− Security
− Architecture
− Data Layer (`src/lib/db/`)
− API Route Layer (`src/app/api/v1/`)
− Request Pipeline (`open-sse/`)
− Provider Categories
− Executors (`open-sse/executors/`)
− Translator (`open-sse/translator/`)
− Transformer (`open-sse/transformer/`)
− Services (`open-sse/services/`)
− Domain Layer (`src/domain/`)
− MCP Server (`open-sse/mcp-server/`)
− A2A Server (`src/lib/a2a/`)
− ACP Module (`src/lib/acp/`)
− Memory System (`src/lib/memory/`)
− Skills System (`src/lib/skills/`)
− Compliance (`src/lib/compliance/`)
− MITM Proxy (`src/mitm/`)
− Middleware (`src/middleware/`)
− Guardrails (`src/lib/guardrails/`)
− Cloud Agents (`src/lib/cloudAgent/`)
− Evals (`src/lib/evals/`)
− Webhooks (`src/lib/webhookDispatcher.ts`)
− Authorization Pipeline (`src/server/authz/`)
− Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)
− Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)
− Adding a New Provider
− Subdirectory AGENTS.md Files
− Reference Documentation (docs/)
− Fork / Upstream Workflow
− the default branch is the active release line, e.g. release/v3.8.49
− Review Focus
+ src/lib/db/ — SQLite Persistence Layer
+ Core Infrastructure
+ Key Domain Modules
+ Encryption & Security
+ Adding a New Domain Module
+ Anti-Patterns

Commands

1 shared · 28 only in A · 0 only in B

− npm run test:all
− node --import tsx/esm --test tests/unit/your-file.test.ts
− node --import tsx/esm --test tests/unit/plan3-p0.test.ts
− node --import tsx/esm --test tests/unit/fixes-p1.test.ts
− node --import tsx/esm --test tests/unit/security-fase01.test.ts
− node --import tsx/esm --test tests/integration/*.test.ts
− npm run test:vitest
− npm run test:e2e
− npm run test:protocols:e2e
− npm run test:ecosystem
− npm run test:coverage
− git fetch upstream
− git switch -c <branch-name> upstream/release/vX.Y.Z
− npm run check:docs-all
− npm run check:fabricated-docs
− npm run dev
− npm run build
− npm run build:release
− npm run start
− npm run build:cli
− npm run lint
− npm run typecheck:core
− npm run typecheck:noimplicit:core
− npm run check
− npm run check:cycles
− npm run electron:dev
− npm run electron:build
− prettier --write
npm run check:docs-counts

Section tags

3 shared · 13 only in A · 1 only in B

− build
− test
− lint-format
− types
− testing-strategy
− git-pr
− api
− performance
− deployment
− monorepo
− do-not
− agent-behaviour
− docs
+ architecture
code-style
security
database

Line diff

+55 added−585 removed16 unchanged2.7% identical

diegosouzapw/OmniRoute · AGENTS.md

@@ −1 @@

1# omniroute — Agent Guidelines

3## Project

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**.

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`.**

16## Doc Accuracy Discipline (read before writing any doc)

18> **If `grep -rn "name" src/ open-sse/ bin/` returns nothing, the name does not exist. Do not document it.**

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.

23**Rules (enforced by `npm run check:fabricated-docs`):**

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.

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`.

45## Stack

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

56---

58## Build, Lint, and Test Commands

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 |

75**Build output layout:**

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 |

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).

87### Running Tests

89```bash

90# All tests (unit + vitest + ecosystem + e2e)

91npm run test:all

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

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 <branch-name> 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

diegosouzapw/OmniRoute · src/lib/db/AGENTS.md

@@ +1 @@

1# src/lib/db/ — SQLite Persistence Layer

3**Purpose**: Domain-driven SQLite persistence. Each module owns a specific table set. Schema migrations are versioned and idempotent. No raw SQL in routes — all ops go through `src/lib/db/` modules.

5Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Migrations: `ls src/lib/db/migrations/*.sql | wc -l` (currently 110).

7---

9## Core Infrastructure

11- **`core.ts`** — `getDbInstance()` returns singleton `better-sqlite3` with WAL journaling. Exports `rowToCamel()` (snake_case → camelCase), `encryptConnectionFields()` for provider credentials at rest. `SCHEMA_SQL` defines **17 base tables** (verify: `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for `_omniroute_migrations`).

12- **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Each migration is idempotent.

13- **`db/migrations/`** — 110 SQL files (`001_initial_schema.sql` → `110_*.sql`). Each runs in a transaction, never fails partially.

14- **`localDb.ts`** — Re-export layer only. Never add logic here.

16## Key Domain Modules

18| Module | Tables / Scope | Responsibility |

19| ---------------------- | ------------------------- | --------------------------------------------------- |

20| `providers.ts` | `provider_connections` | OAuth/API key provider registration and credentials |

21| `models.ts` | `models` | Model definitions, capabilities, pricing |

22| `combos.ts` | `combos`, `combo_targets` | Combo routing configs, target ordering |

23| `apiKeys.ts` | `api_keys` | API key lifecycle, scopes, quota tracking |

24| `settings.ts` | `settings` | KV store for system configuration |

25| `secrets.ts` | `secrets` | Encrypted secret storage (API keys at rest) |

26| `quotaSnapshots.ts` | `quota_snapshots` | Historical quota usage for analytics |

27| `quotaPools.ts` | `quota_pools` | Quota-Share pool management |

28| `creditBalance.ts` | `credit_balance` | Per-provider credit tracking |

29| `compression.ts` | compression settings | Prompt compression pipeline config |

30| `compressionCombos.ts` | `compression_combos` | Per-combo compression pipeline assignments |

31| `evals.ts` | eval tables | Eval framework persistence |

32| `webhooks.ts` | `webhooks` | Event-driven webhook subscriptions and logs |

33| `reasoningCache.ts` | reasoning cache | Hybrid in-memory + SQLite reasoning replay |

34| `skills.ts` | `skills` | Skill registration and metadata |

35| `plugins.ts` | `plugins` | Plugin marketplace state |

36| `gamification.ts` | gamification tables | Levels, badges, leaderboard |

37| `notion.ts` | notion tables | Notion integration state |

38| `obsidian.ts` | obsidian tables | Obsidian vault integration state |

39| `files.ts` | file storage | Uploaded file management |

40| `batches.ts` | batch processing | Batch job tracking |

41| `featureFlags.ts` | feature flags | Runtime feature flag overrides |

42| `backup.ts` | backup ops | Serialize/deserialize entire DB state |

43| `cleanup.ts` | cleanup ops | Stale data purging |

44| `healthCheck.ts` | health ops | DB health monitoring |

45| `databaseSettings.ts` | database settings | DB-level configuration |

47Full list: `ls src/lib/db/*.ts | wc -l` (95 files). Drift detection: `npm run check:docs-counts`.

49## Encryption & Security

51- **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using AES-256-GCM

52- **`encryptConnectionFields()`** in `core.ts` — automatic encryption when storing provider credentials

53- **`secrets.ts`** — dedicated encrypted store for long-term secret handling

54- **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs

56## Adding a New Domain Module

581. Create `src/lib/db/[module].ts` with CRUD functions

592. Export from `src/lib/localDb.ts` (add re-export)

603. If new tables: create migration in `db/migrations/NNN_[description].sql`

614. Migration runs automatically at startup via `migrationRunner.ts`

625. Add unit tests in `tests/unit/db/`

64## Anti-Patterns

66- Raw SQL in routes — always use domain module functions

67- Direct `prepare()` statements outside `db/` — breaks modularity

68- Adding logic to `localDb.ts` — re-export layer only

69- Barrel-importing from `localDb.ts` — import specific modules instead

70- Skipping migrations for schema changes — all changes go through `db/migrations/`

@@ −1 +1 @@

1−# omniroute — Agent Guidelines

1+# src/lib/db/ — SQLite Persistence Layer

3−## Project

3+**Purpose**: Domain-driven SQLite persistence. Each module owns a specific table set. Schema migrations are versioned and idempotent. No raw SQL in routes — all ops go through `src/lib/db/` modules.

5−Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support

6−with **290 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,

7−Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,

8−SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)

9−with **MCP Server** (104 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.

5+Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Migrations: `ls src/lib/db/migrations/*.sql | wc -l` (currently 110).

106

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−

20−The recurring failure mode in AI-generated docs is _plausible-but-unverified specifics_.

21−Every claim in a `.md` file under `docs/` should be verifiable against the source.

22−

23−**Rules (enforced by `npm run check:fabricated-docs`):**

24−

25−1. **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− ```

30−2. **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− ```

35−3. **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.

37−4. **Prefer citing real source (`file.ts:line`) over paraphrasing behavior** — verifiable and self-correcting.

38−5. **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−

41−The script `scripts/check/check-fabricated-docs.mjs` extracts every route path, env var, hook

42−name, function name, and file reference from `docs/**/*.md` and verifies each one against the

43−codebase. 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−

567 ---

578

58−## Build, Lint, and Test Commands

9+## Core Infrastructure

5910

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 |

11+- **`core.ts`** — `getDbInstance()` returns singleton `better-sqlite3` with WAL journaling. Exports `rowToCamel()` (snake_case → camelCase), `encryptConnectionFields()` for provider credentials at rest. `SCHEMA_SQL` defines **17 base tables** (verify: `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for `_omniroute_migrations`).

12+- **`migrationRunner.ts`** — Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations`. Each migration is idempotent.

13+- **`db/migrations/`** — 110 SQL files (`001_initial_schema.sql` → `110_*.sql`). Each runs in a transaction, never fails partially.

14+- **`localDb.ts`** — Re-export layer only. Never add logic here.

7415

75−**Build output layout:**

16+## Key Domain Modules

7617

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 |

18+| Module | Tables / Scope | Responsibility |

19+| ---------------------- | ------------------------- | --------------------------------------------------- |

20+| `providers.ts` | `provider_connections` | OAuth/API key provider registration and credentials |

21+| `models.ts` | `models` | Model definitions, capabilities, pricing |

22+| `combos.ts` | `combos`, `combo_targets` | Combo routing configs, target ordering |

23+| `apiKeys.ts` | `api_keys` | API key lifecycle, scopes, quota tracking |

24+| `settings.ts` | `settings` | KV store for system configuration |

25+| `secrets.ts` | `secrets` | Encrypted secret storage (API keys at rest) |

26+| `quotaSnapshots.ts` | `quota_snapshots` | Historical quota usage for analytics |

27+| `quotaPools.ts` | `quota_pools` | Quota-Share pool management |

28+| `creditBalance.ts` | `credit_balance` | Per-provider credit tracking |

29+| `compression.ts` | compression settings | Prompt compression pipeline config |

30+| `compressionCombos.ts` | `compression_combos` | Per-combo compression pipeline assignments |

31+| `evals.ts` | eval tables | Eval framework persistence |

32+| `webhooks.ts` | `webhooks` | Event-driven webhook subscriptions and logs |

33+| `reasoningCache.ts` | reasoning cache | Hybrid in-memory + SQLite reasoning replay |

34+| `skills.ts` | `skills` | Skill registration and metadata |

35+| `plugins.ts` | `plugins` | Plugin marketplace state |

36+| `gamification.ts` | gamification tables | Levels, badges, leaderboard |

37+| `notion.ts` | notion tables | Notion integration state |

38+| `obsidian.ts` | obsidian tables | Obsidian vault integration state |

39+| `files.ts` | file storage | Uploaded file management |

40+| `batches.ts` | batch processing | Batch job tracking |

41+| `featureFlags.ts` | feature flags | Runtime feature flag overrides |

42+| `backup.ts` | backup ops | Serialize/deserialize entire DB state |

43+| `cleanup.ts` | cleanup ops | Stale data purging |

44+| `healthCheck.ts` | health ops | DB health monitoring |

45+| `databaseSettings.ts` | database settings | DB-level configuration |

8246

83−The pipeline is a single `next build` pass — intermediates land in `.build/next/`, the

84−assembled bundle in `dist/`. VPS deploys rsync `dist/` into the remote

85−`/usr/lib/node_modules/omniroute/app/` directory (VPS image path is unchanged).

47+Full list: `ls src/lib/db/*.ts | wc -l` (95 files). Drift detection: `npm run check:docs-counts`.

8648

87−### Running Tests

49+## Encryption & Security

8850

89−```bash

90−# All tests (unit + vitest + ecosystem + e2e)

91−npm run test:all

51+- **Sensitive fields** (API keys, OAuth tokens, connection strings) encrypted at rest using AES-256-GCM

52+- **`encryptConnectionFields()`** in `core.ts` — automatic encryption when storing provider credentials

53+- **`secrets.ts`** — dedicated encrypted store for long-term secret handling

54+- **Never log** SQLite encryption keys or raw secrets; always use redacted values in logs

9255

93−# Single test file (Node.js native test runner — most tests use this)

94−node --import tsx/esm --test tests/unit/your-file.test.ts

95−node --import tsx/esm --test tests/unit/plan3-p0.test.ts

96−node --import tsx/esm --test tests/unit/fixes-p1.test.ts

97−node --import tsx/esm --test tests/unit/security-fase01.test.ts

56+## Adding a New Domain Module

9857

99−# Integration tests

100−node --import tsx/esm --test tests/integration/*.test.ts

58+1. Create `src/lib/db/[module].ts` with CRUD functions

59+2. Export from `src/lib/localDb.ts` (add re-export)

60+3. If new tables: create migration in `db/migrations/NNN_[description].sql`

61+4. Migration runs automatically at startup via `migrationRunner.ts`

62+5. Add unit tests in `tests/unit/db/`

10163

102−# Vitest (MCP server, autoCombo)

103−npm run test:vitest

64+## Anti-Patterns

10465

105−# E2E with Playwright

106−npm run test:e2e

107−

108−# Protocol clients E2E (MCP transports, A2A)

109−npm run test:protocols:e2e

110−

111−# Ecosystem compatibility tests

112−npm run test:ecosystem

113−

114−# Coverage (see CONTRIBUTING.md)

115−npm 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−

126−2 spaces · semicolons required · double quotes (`"`) · 100 char width · es5 trailing commas.

127−Always 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−

181−All 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−

191−Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Drift detection: `npm run check:docs-counts`.

192−Schema 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−

210−Next.js App Router routes — each follows a consistent pattern:

211−

212−```

213−Route → 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−

236−The `open-sse/` workspace is the core streaming engine. Full request flow:

237−

238−```

239−Client 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.

265−Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,

266−Zod 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−

289−Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.

290−

291−### Executors (`open-sse/executors/`)

292−

293−Provider-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−

311−Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).

312−Includes 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−

339−134 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

346−compression pipeline), and more.

347−

348−#### Prompt Compression Pipeline (`compression/`)

349−

350−Modular 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−

388−Policy 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,

397−route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,

398−set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,

399−best_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,

404−list_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,

423−handler: 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−

435−JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.

436−Agent Card at `/.well-known/agent.json`.

437−Skills (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 →

442−completed | 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−

453−Agent Communication Protocol registry and manager.

454−

455−### Memory System (`src/lib/memory/`)

456−

457−Extraction, injection, retrieval, summarization, and store modules for persistent

458−conversational memory across sessions.

459−

460−### Skills System (`src/lib/skills/`)

461−

462−Extensible skill framework: registry, executor, sandbox, built-in skills,

463−custom 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−

480−Policy index for compliance enforcement.

481−

482−### MITM Proxy (`src/mitm/`)

483−

484−MITM proxy capability with certificate management, DNS handling, and target routing.

485−

486−### Middleware (`src/middleware/`)

487−

488−Request middleware including `promptInjectionGuard.ts`.

489−

490−### Guardrails (`src/lib/guardrails/`)

491−

492−Hot-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−

500−Generic 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−

504−HMAC-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−

512−Hybrid 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−

516−Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md).

517−

518−### Adding a New Provider

519−

520−1. Register in `src/shared/constants/providers.ts`

521−2. Add executor in `open-sse/executors/` (if custom logic needed)

522−3. Add translator in `open-sse/translator/` (if non-OpenAI format)

523−4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)

524−5. 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−

535−For 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−

569−This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operational

570−changes (for example GHCR image publishing, personal deployment workflows, or local

571−automation) out of upstream contribution PRs.

572−

573−When 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`).

575−Never branch from `main`: `main` only receives release squash-merges, so a branch

576−cut there is weeks behind and produces conflict-heavy PRs

577−(see `CONTRIBUTING.md` and `docs/ops/BRANCHING_MODEL.md`):

578−

579−```bash

580−git fetch upstream

581−# the default branch is the active release line, e.g. release/v3.8.49

582−git switch -c <branch-name> upstream/release/vX.Y.Z

583−```

584−

585−Only 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.

66+- Raw SQL in routes — always use domain module functions

67+- Direct `prepare()` statements outside `db/` — breaks modularity

68+- Adding logic to `localDb.ts` — re-export layer only

69+- Barrel-importing from `localDb.ts` — import specific modules instead

70+- Skipping migrations for schema changes — all changes go through `db/migrations/`

60171