OmniRoute/AGENTS.md

# omniroute — Agent Guidelines

## Project

Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.)
with **MCP Server** (16 tools for agent control) and **A2A v0.3 Protocol** (Agent-to-Agent orchestration).

## Stack

- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules
- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`)
- **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
- **Streaming**: SSE via `open-sse` internal package
- **Styling**: Tailwind CSS v4
- **Docker**: Multi-stage Dockerfile, 3 profiles (base / cli / host)
- **i18n**: next-intl with 30 languages (`src/i18n/messages/`)

## Architecture

### Data Layer (`src/lib/db/`)

All persistence uses SQLite through domain-specific modules:

| Module         | Responsibility                             |
| -------------- | ------------------------------------------ |
| `core.ts`      | SQLite engine, migrations, WAL, encryption |
| `providers.ts` | Provider connections & nodes               |
| `models.ts`    | Model aliases, MITM aliases, custom models |
| `combos.ts`    | Combo configurations                       |
| `apiKeys.ts`   | API key management & validation            |
| `settings.ts`  | Settings, pricing, proxy config            |
| `backup.ts`    | Backup / restore operations                |

`src/lib/localDb.ts` is a **re-export layer only** — all 27+ consumers import from it,
but the real logic lives in `src/lib/db/`.

### Request Pipeline (`open-sse/`)

| Handler                 | Role                                        |
| ----------------------- | ------------------------------------------- |
| `chatCore.js`           | Main chat completions proxy (SSE / non-SSE) |
| `responsesHandler.js`   | OpenAI Responses API compat                 |
| `responseTranslator.js` | Format translation for Responses API        |
| `embeddings.js`         | Embedding proxy                             |
| `imageGeneration.js`    | Image generation proxy                      |
| `sseParser.js`          | SSE stream parser                           |
| `usageExtractor.js`     | Token usage extraction from responses       |

Translation between provider formats: `open-sse/translator/`

**Upstream model extra headers** (`compatByProtocol` / custom models): merged in executors after default auth; **same header name replaces** the executor value (e.g. custom `Authorization` overrides Bearer). In `open-sse/handlers/chatCore.ts`, the primary request merges headers for **both** the client model id and `resolveModelAlias(clientModel)` (resolved id wins on key conflicts). **T5 intra-family fallback** recomputes headers using only the fallback model id and `resolveModelAlias(fallback)` so sibling models do not inherit another model’s headers. Forbidden header names live in `src/shared/constants/upstreamHeaders.ts` — keep sanitize (`models.ts`), Zod (`schemas.ts`), and unit tests aligned when editing that list.

### MCP Server (`open-sse/mcp-server/`)

16 tools for AI agent control via **3 transport modes**:

- **stdio** — Local IDE integration (Claude Desktop, Cursor, VS Code)
- **SSE** — Remote Server-Sent Events at `/api/mcp/sse`
- **Streamable HTTP** — Modern bidirectional HTTP at `/api/mcp/stream`

HTTP transports run in-process via `httpTransport.ts` singleton using `WebStandardStreamableHTTPServerTransport`.

| Category  | Tools                                                                                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Essential | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`                               |
| Advanced  | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` |

- Scoped authorization (9 scopes), audit logging, Zod schemas
- IDE configs for Claude Desktop, Cursor, VS Code Copilot

### A2A Server (`src/lib/a2a/`)

Agent-to-Agent v0.3 protocol:

- JSON-RPC 2.0: `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`
- Agent Card at `/.well-known/agent.json`
- Skills: `smart-routing`, `quota-management`
- SSE streaming with 15s heartbeat
- Task Manager with state machine and TTL-based cleanup

### Auto-Combo Engine (`open-sse/services/autoCombo/`)

Self-healing routing optimization:

- 6-factor scoring, 4 mode packs, bandit exploration
- Progressive cooldown, probe-based re-admission

### Dashboard (`src/app/(dashboard)/`)

| Page                     | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `/dashboard`             | Home with quick start, provider overview                        |
| `/dashboard/endpoint`    | **Endpoints** (tabbed): Endpoint Proxy, MCP, A2A, API Endpoints |
| `/dashboard/providers`   | Provider management and connections                             |
| `/dashboard/combos`      | Combo configurations with routing strategies                    |
| `/dashboard/logs`        | Request, Proxy, Audit, Console logs (tabbed)                    |
| `/dashboard/analytics`   | Usage analytics and evaluations                                 |
| `/dashboard/costs`       | Cost tracking and breakdown                                     |
| `/dashboard/health`      | Uptime, circuit breakers, latency                               |
| `/dashboard/cli-tools`   | CLI tool integrations (Claude, Codex, Antigravity, etc.)        |
| `/dashboard/media`       | Image, Video, Music generation playground                       |
| `/dashboard/settings`    | System settings with multiple tabs                              |
| `/dashboard/api-manager` | API key management with model permissions                       |

### OAuth & Tokens (`src/lib/oauth/`)

18 modules handling OAuth flows, token refresh, and provider credentials.
Default credentials are hardcoded in `src/lib/oauth/constants/oauth.ts`,
overridable via env vars or `data/provider-credentials.json`.

### Supporting Systems

| System                     | Location                                          |
| -------------------------- | ------------------------------------------------- |
| Usage tracking & analytics | `src/lib/usageDb.ts`, `src/lib/usageAnalytics.ts` |
| Token health checks        | `src/lib/tokenHealthCheck.ts`                     |
| Cloud sync                 | `src/lib/cloudSync.ts`                            |
| Proxy logging              | `src/lib/proxyLogger.ts`                          |
| Data paths resolution      | `src/lib/dataPaths.ts`                            |

### Adding a New Provider

1. Register in `src/shared/constants/providers.ts`
2. Add executor in `open-sse/executors/`
3. Add translator rules in `open-sse/translator/` (if non-OpenAI format)
4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)

## Review Focus

### Security

- No hardcoded API keys or secrets in commits
- Auth middleware on all API routes
- Input validation on user-facing endpoints (Zod schemas)
- SQLite encryption key must not be logged

### Architecture

- DB operations go through `src/lib/db/` modules, never raw SQL in routes
- Provider requests flow through `open-sse/handlers/`
- Translations use `open-sse/translator/` modules
- `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module
- MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`, not standalone routes

### Code Quality

- Consistent error handling with try/catch
- Proper HTTP status codes
- No memory leaks in SSE streams (abort signals, cleanup)
- Rate limit headers must be parsed correctly
- All API inputs validated with Zod schemas

### Docker

- Dockerfile has two targets: `runner-base` and `runner-cli`
- `docker-compose.yml` — development (3 profiles)
- `docker-compose.prod.yml` — isolated production instance (port 20130)
- Data persists in named volumes (`omniroute-data` / `omniroute-prod-data`)

### Review Mode

- Provide analysis and suggestions only
- Focus on bugs, security, performance, and best practices