Comparison

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

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	11	5	0%
Commands	0	6	0%
Section tags	3	6	0%

What each file covers

Sections

0 shared · 11 only in A · 5 only in B

− open-sse/services/ — Routing Engine & Cross-Cutting Services
− Combo Routing Engine
− Key Services
− Quota & Rate Limiting
− Account & Token Management
− Request Routing & Intelligence
− Model Lifecycle & Fallback
− State & Detection
− Prompt Compression Pipeline (`compression/`)
− Adding a New Service
− Anti-Patterns
+ Security and Cleanliness Rules for AI Assistants
+ 1. File Placement & Organization
+ 2. Hard Rules (mirror of `CLAUDE.md`)
+ 3. Codebase navigation
+ 4. Local development access

Commands

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

+ vitest.config.ts
+ eslint.config.mjs
+ playwright.config.ts
+ prettier.config.mjs
+ docker-compose*.yml
+ npm run test:coverage

Section tags

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

− code-style
− performance
− deployment
+ test
+ lint-format
+ architecture
+ security
+ do-not
+ agent-behaviour

Line diff

+36 added−65 removed15 unchanged18.8% identical

diegosouzapw/OmniRoute · open-sse/services/AGENTS.md

@@ −1 @@

1# open-sse/services/ — Routing Engine & Cross-Cutting Services

3**Purpose**: 134 service modules (top-level) powering request routing, rate limiting, quota management, token refresh, fallback strategies, and runtime state. The combo routing engine (`combo.ts`) is the core; supporting services handle resilience, accounting, and decision-making.

5Live count: `ls open-sse/services/*.ts | wc -l` (currently 134). More including sub-dirs like `autoCombo/` and `compression/`.

7---

9## Combo Routing Engine

11- **`combo.ts`** — Entry point for multi-model routing. **`handleComboChat()`** iterates through targets in order until success or all fail. **`resolveComboTargets()`** expands combo config into ordered `ResolvedComboTarget[]` (provider + model + account + credentials).

12- **Strategies** (17): `priority`, `weighted`, `fill-first`, `round-robin`, `P2C`, `random`, `least-used`, `reset-aware`, `reset-window`, `cost-optimized`, `strict-random`, `auto`, `lkgp`, `context-optimized`, `context-relay`, `headroom`, `fusion`. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.

13- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with per-target error handling and circuit breaker checks.

15## Key Services

17### Quota & Rate Limiting

19- **`rateLimitManager.ts`** — Token bucket per API key + provider combo. Rejects before dispatch.

20- **`usage.ts`** — Per-request token/cost consumption tracking.

21- **`quotaCache.ts`** — In-memory quota snapshots, pre-loaded at startup.

23### Account & Token Management

25- **`tokenRefresh.ts`** — OAuth token expiration detection and refresh.

26- **`accountFallback.ts`** — Account switching on quota/rate-limit. Also houses model lockout.

27- **`sessionManager.ts`** — Request session state across retries.

29### Request Routing & Intelligence

31- **`wildcardRouter.ts`** — Wildcard route matching in combo configs.

32- **`intentClassifier.ts`** — Request intent classification for intelligent routing.

33- **`taskAwareRouter.ts`** — Task-type-based routing (reasoning → o1, code-gen → Cursor).

34- **`targetRequestSanitizer.ts`** — Final provider/model-aware parameter sanitation after routing resolution and before executor dispatch.

35- **`thinkingBudget.ts`** — Thinking token allocation for o1/o3 models.

36- **`contextManager.ts`** — Routing context injection (system prompts, memory).

38### Model Lifecycle & Fallback

40- **`modelDeprecation.ts`** — Deprecated model detection and successor routing.

41- **`modelFamilyFallback.ts`** — T5 intra-family fallback chains.

42- **`emergencyFallback.ts`** — Last-resort fallback to stable free providers.

44### State & Detection

46- **`workflowFSM.ts`** — Multi-turn workflow state machine.

47- **`backgroundTaskDetector.ts`** — Long-running task detection for batch routing.

48- **`ipFilter.ts`** — IP-based routing rules.

49- **`signatureCache.ts`** — Request signature caching for deduplication.

50- **`volumeDetector.ts`** — Volume spike detection for rate-limit escalation.

51- **`contextHandoff.ts`** — Session context serialization for A2A handoff.

53### Prompt Compression Pipeline (`compression/`)

55- **`strategySelector.ts`** — Compression mode selection (off/lite/standard/aggressive/ultra/rtk/stacked).

56- **`lite.ts`** — 5 lite techniques (whitespace, dedup, tool results, redundant removal, image URLs).

57- **`caveman.ts` / `cavemanRules.ts`** — Caveman-style semantic condensation with rule packs.

58- **`engines/rtk/`** — RTK tool-output compression (command detection, JSON filters, dedup, truncation).

59- **`engines/registry.ts`** — Engine registry for standalone and stacked pipelines.

60- **`stats.ts`** — Per-request compression stats.

61- **`types.ts`** — Shared types (`CompressionMode`, `CompressionConfig`, `CompressionStats`).

63---

65## Adding a New Service

671. Create `open-sse/services/[serviceName].ts`

682. Export main handler function

693. Add unit tests in `tests/unit/services/`

704. Integrate into `handlers/chatCore.ts` (if routing-related) or `combo.ts`

715. Document in this file

73## Anti-Patterns

75- Synchronous DB calls in `combo.ts` hot path — pre-compute and cache

76- Retry logic in handlers — use `retry()` from resilience service

77- Direct provider config access — use `providerRegistry` getter functions

78- Hardcoded fallback chains — define in `modelFamilyFallback.ts`

79- State mutations across concurrent requests — use request-scoped context only

diegosouzapw/OmniRoute · GEMINI.md

@@ +1 @@

1# Security and Cleanliness Rules for AI Assistants

3> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`.

5## 1. File Placement & Organization

7- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).

8- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder.

10**The Project Root MUST ONLY CONTAIN:**

12- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`)

13- Dependency files (`package.json`, `package-lock.json`)

14- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`)

15- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`)

17When creating _any_ validation tests or one-off logic scripts, default to using `scripts/ad-hoc/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.

19## 2. Hard Rules (mirror of `CLAUDE.md`)

211. **Never commit secrets or credentials.** Use `.env` (auto-generated from `.env.example`) or a vault. Passwords, OAuth secrets, API keys, and Cookie values must never appear in committed files.

222. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only.

233. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this.

244. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches.

255. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules.

266. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly.

277. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.

288. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`.

299. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`).

3010. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it.

32## 3. Codebase navigation

34| Task | Read this first |

35| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

36| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` |

37| Architecture overview | `docs/architecture/ARCHITECTURE.md` |

38| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |

39| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |

40| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` |

41| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |

43## 4. Local development access

45The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific:

47- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login).

48- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo.

50> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.

@@ −1 +1 @@

1−# open-sse/services/ — Routing Engine & Cross-Cutting Services

1+# Security and Cleanliness Rules for AI Assistants

3−**Purpose**: 134 service modules (top-level) powering request routing, rate limiting, quota management, token refresh, fallback strategies, and runtime state. The combo routing engine (`combo.ts`) is the core; supporting services handle resilience, accounting, and decision-making.

3+> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`.

5−Live count: `ls open-sse/services/*.ts | wc -l` (currently 134). More including sub-dirs like `autoCombo/` and `compression/`.

5+## 1. File Placement & Organization

7−---

7+- **Test Files**: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the `tests/` directory (e.g., `tests/unit/`, `tests/integration/`). NEVER create test files in the project root (`/`).

8+- **Scripts and Utilities**: ALL maintenance, debugging, generation, or experimental scripts (`.cjs`, `.mjs`, `.js`, `.ts`) MUST be placed strictly inside one of the `scripts/` subfolders (`build/`, `dev/`, `check/`, `docs/`, `i18n/`, `ad-hoc/`). One-shot or experimental code goes under `scripts/ad-hoc/`. NEVER dump loose scripts in the project root (`/`) or the top-level `scripts/` folder.

9−## Combo Routing Engine

10+**The Project Root MUST ONLY CONTAIN:**

1011

11−- **`combo.ts`** — Entry point for multi-model routing. **`handleComboChat()`** iterates through targets in order until success or all fail. **`resolveComboTargets()`** expands combo config into ordered `ResolvedComboTarget[]` (provider + model + account + credentials).

12−- **Strategies** (17): `priority`, `weighted`, `fill-first`, `round-robin`, `P2C`, `random`, `least-used`, `reset-aware`, `reset-window`, `cost-optimized`, `strict-random`, `auto`, `lkgp`, `context-optimized`, `context-relay`, `headroom`, `fusion`. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.

13−- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with per-target error handling and circuit breaker checks.

12+- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, `tsconfig*.json`, `playwright.config.ts`, `prettier.config.mjs`, `postcss.config.mjs`, `sonar-project.properties`, `fly.toml`, `docker-compose*.yml`, `Dockerfile`)

13+- Dependency files (`package.json`, `package-lock.json`)

14+- Documentation files (`README.md`, `CHANGELOG.md`, `LICENSE`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `llm.txt`, `Tuto_Qdrant.md`)

15+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`)

1416

15−## Key Services

17+When creating _any_ validation tests or one-off logic scripts, default to using `scripts/ad-hoc/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.

1618

17−### Quota & Rate Limiting

19+## 2. Hard Rules (mirror of `CLAUDE.md`)

1820

19−- **`rateLimitManager.ts`** — Token bucket per API key + provider combo. Rejects before dispatch.

20−- **`usage.ts`** — Per-request token/cost consumption tracking.

21−- **`quotaCache.ts`** — In-memory quota snapshots, pre-loaded at startup.

21+1. **Never commit secrets or credentials.** Use `.env` (auto-generated from `.env.example`) or a vault. Passwords, OAuth secrets, API keys, and Cookie values must never appear in committed files.

22+2. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only.

23+3. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this.

24+4. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches.

25+5. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules.

26+6. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly.

27+7. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.

28+8. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`.

29+9. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`).

30+10. **Coverage must stay** ≥ 60 % statements / lines / functions / branches — the official CI gate (`npm run test:coverage`). The ratchet baseline in `quality-baseline.json` may freeze a higher floor; never regress it.

2231

23−### Account & Token Management

32+## 3. Codebase navigation

2433

25−- **`tokenRefresh.ts`** — OAuth token expiration detection and refresh.

26−- **`accountFallback.ts`** — Account switching on quota/rate-limit. Also houses model lockout.

27−- **`sessionManager.ts`** — Request session state across retries.

34+| Task | Read this first |

35+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

36+| Understand the codebase | `docs/architecture/REPOSITORY_MAP.md` |

37+| Architecture overview | `docs/architecture/ARCHITECTURE.md` |

38+| Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` |

39+| Add a feature | `CONTRIBUTING.md` + the matching `docs/<area>.md` |

40+| Per-area deep dives | `docs/frameworks/SKILLS.md`, `docs/frameworks/MEMORY.md`, `docs/frameworks/EVALS.md`, `docs/security/GUARDRAILS.md`, `docs/security/COMPLIANCE.md`, `docs/frameworks/CLOUD_AGENT.md`, `docs/frameworks/MCP-SERVER.md`, `docs/frameworks/A2A-SERVER.md`, `docs/architecture/AUTHZ_GUIDE.md`, `docs/architecture/RESILIENCE_GUIDE.md`, `docs/routing/AUTO-COMBO.md`, `docs/frameworks/WEBHOOKS.md`, `docs/routing/REASONING_REPLAY.md`, `docs/security/STEALTH_GUIDE.md`, `docs/ops/TUNNELS_GUIDE.md`, `docs/guides/ELECTRON_GUIDE.md`, `docs/reference/PROVIDER_REFERENCE.md` |

41+| Release flow | `docs/ops/RELEASE_CHECKLIST.md` |

2842

29−### Request Routing & Intelligence

43+## 4. Local development access

3044

31−- **`wildcardRouter.ts`** — Wildcard route matching in combo configs.

32−- **`intentClassifier.ts`** — Request intent classification for intelligent routing.

33−- **`taskAwareRouter.ts`** — Task-type-based routing (reasoning → o1, code-gen → Cursor).

34−- **`targetRequestSanitizer.ts`** — Final provider/model-aware parameter sanitation after routing resolution and before executor dispatch.

35−- **`thinkingBudget.ts`** — Thinking token allocation for o1/o3 models.

36−- **`contextManager.ts`** — Routing context injection (system prompts, memory).

45+The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific:

3746

38−### Model Lifecycle & Fallback

47+- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login).

48+- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo.

3949

40−- **`modelDeprecation.ts`** — Deprecated model detection and successor routing.

41−- **`modelFamilyFallback.ts`** — T5 intra-family fallback chains.

42−- **`emergencyFallback.ts`** — Last-resort fallback to stable free providers.

43−

44−### State & Detection

45−

46−- **`workflowFSM.ts`** — Multi-turn workflow state machine.

47−- **`backgroundTaskDetector.ts`** — Long-running task detection for batch routing.

48−- **`ipFilter.ts`** — IP-based routing rules.

49−- **`signatureCache.ts`** — Request signature caching for deduplication.

50−- **`volumeDetector.ts`** — Volume spike detection for rate-limit escalation.

51−- **`contextHandoff.ts`** — Session context serialization for A2A handoff.

52−

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

54−

55−- **`strategySelector.ts`** — Compression mode selection (off/lite/standard/aggressive/ultra/rtk/stacked).

56−- **`lite.ts`** — 5 lite techniques (whitespace, dedup, tool results, redundant removal, image URLs).

57−- **`caveman.ts` / `cavemanRules.ts`** — Caveman-style semantic condensation with rule packs.

58−- **`engines/rtk/`** — RTK tool-output compression (command detection, JSON filters, dedup, truncation).

59−- **`engines/registry.ts`** — Engine registry for standalone and stacked pipelines.

60−- **`stats.ts`** — Per-request compression stats.

61−- **`types.ts`** — Shared types (`CompressionMode`, `CompressionConfig`, `CompressionStats`).

62−

63−---

64−

65−## Adding a New Service

66−

67−1. Create `open-sse/services/[serviceName].ts`

68−2. Export main handler function

69−3. Add unit tests in `tests/unit/services/`

70−4. Integrate into `handlers/chatCore.ts` (if routing-related) or `combo.ts`

71−5. Document in this file

72−

73−## Anti-Patterns

74−

75−- Synchronous DB calls in `combo.ts` hot path — pre-compute and cache

76−- Retry logic in handlers — use `retry()` from resilience service

77−- Direct provider config access — use `providerRegistry` getter functions

78−- Hardcoded fallback chains — define in `modelFamilyFallback.ts`

79−- State mutations across concurrent requests — use request-scoped context only

50+> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.

8051