-
- {/* Priority arrows */}
- ...
-```
-
-#### Header Row (above connections list)
-
-```tsx
-
-
-
- {selectedIds.size > 0 ? `${selectedIds.size} selected` : `${connections.length} accounts`}
-
-
-
- {selectedIds.size > 0 && (
-
- {t("batchDeleteSelected", { count: selectedIds.size })}
-
- )}
-
-```
-
-### 4. i18n Keys (to add to all locale files)
-
-```json
-{
- "batchDeleteSelected": "Delete Selected ({count})",
- "batchDeleteConfirm": "Delete {count} connection(s)? This action cannot be undone.",
- "batchDeleteSuccess": "Deleted {count} connection(s)"
-}
-```
-
-### 5. Testing
-
-#### Unit Test (`tests/unit/db-providers-crud.test.ts`)
-
-```typescript
-test("deleteProviderConnections deletes multiple connections", async () => {
- const ids = [
- (await createProviderConnection({ provider: "openai", name: "test-1", authType: "apikey" }))
- .id!,
- (await createProviderConnection({ provider: "openai", name: "test-2", authType: "apikey" }))
- .id!,
- ];
-
- const deleted = await deleteProviderConnections(ids);
- expect(deleted).toBe(2);
-
- for (const id of ids) {
- const conn = await getProviderConnectionById(id);
- expect(conn).toBeNull();
- }
-});
-
-test("deleteProviderConnections with empty array returns 0", async () => {
- const deleted = await deleteProviderConnections([]);
- expect(deleted).toBe(0);
-});
-```
-
-#### Integration Test (`tests/integration/api-routes-critical.test.ts`)
-
-```typescript
-test("DELETE /api/providers — batch delete", async () => {
- const ids = [conn1.id, conn2.id];
- const res = await fetch("http://localhost:20128/api/providers", {
- method: "DELETE",
- headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
- body: JSON.stringify({ ids }),
- });
-
- expect(res.status).toBe(200);
- const data = await res.json();
- expect(data.deleted).toBe(2);
-});
-```
-
-### UX Details
-
-1. **Indeterminate select-all**: When some (but not all) rows are selected, the select-all checkbox shows as indeterminate (dash)
-2. **Confirmation**: Shows `confirm()` with count ("Delete 3 connections?")
-3. **Optimistic update**: Immediately clears selected IDs and removes deleted connections from list on success
-4. **Error handling**: Shows error notification; connections remain in list if delete fails
-5. **Loading state**: Button shows spinner during delete; row checkboxes disabled
-6. **Empty state**: No "Delete Selected" button when nothing selected
-7. **Audit logging**: Each batch delete logged as `provider.credentials.batch_revoked`
-
-### Non-Goals
-
-- Bulk enable/disable (separate feature)
-- Moving selected accounts (separate feature)
-- Batch rename/edit (separate feature)
-- Deleting across different providers (each provider page operates independently)
-
-### Risks & Mitigations
-
-| Risk | Mitigation |
-| ---------------------------------------- | ------------------------------------------------------- |
-| User accidentally deletes wrong accounts | Require confirmation dialog with count |
-| Too many connections selected | Cap at 100 per batch; show error if exceeded |
-| Partial failure on batch delete | DB runs in transaction; all-or-nothing semantics |
-| Performance with large selections | Batch SQL with `IN (...)` clause is efficient up to 100 |
-
-### Coverage
-
-Per repository rules, this change affects production code in `src/` → automated tests required:
-
-- Unit test for `deleteProviderConnections()` in `tests/unit/db-providers-crud.test.ts`
-- Integration test for `DELETE /api/providers` batch endpoint in `tests/integration/api-routes-critical.test.ts`
-- Run `npm run test:coverage` — all 4 metrics must meet 60% minimum
-
----
-
-## Related Issues
-
-- Closes this issue on merge
diff --git a/AGENTS.md b/AGENTS.md
index aadaf98b2e..5b429a8e1f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,13 +127,18 @@ Always run `prettier --write` on changed files.
### Data Layer (`src/lib/db/`)
-All persistence uses SQLite through domain-specific modules:
-`core.ts`, `providers.ts`, `models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`,
-`backup.ts`, `proxies.ts`, `prompts.ts`, `webhooks.ts`, `detailedLogs.ts`,
-`domainState.ts`, `registeredKeys.ts`, `quotaSnapshots.ts`, `modelComboMappings.ts`,
-`cliToolState.ts`, `encryption.ts`, `readCache.ts`, `secrets.ts`, `stateReset.ts`,
-`contextHandoffs.ts`, `compression.ts`.
-Schema migrations live in `db/migrations/` and run via `migrationRunner.ts`.
+All persistence uses SQLite through **45+ domain-specific modules** in `src/lib/db/`. Top modules:
+
+- Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
+- Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
+- Routing: `combos.ts`, `modelComboMappings.ts`, `domainState.ts`, `commandCodeAuth.ts`
+- Auth: `apiKeys.ts`, `secrets.ts`, `registeredKeys.ts`, `sessionAccountAffinity.ts`
+- Usage / billing: `quotaSnapshots.ts`, `creditBalance.ts`, `usage*.ts`, `compressionCacheStats.ts`
+- Storage: `backup.ts`, `cleanup.ts`, `jsonMigration.ts`, `healthCheck.ts`, `databaseSettings.ts`
+- 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`
+
+Live count: `ls src/lib/db/*.ts | wc -l` (currently 45).
+Schema migrations live in `db/migrations/` (55 files) and run via `migrationRunner.ts`.
`src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
#### DB Internals
@@ -142,8 +147,8 @@ Schema migrations live in `db/migrations/` and run via `migrationRunner.ts`.
journaling. `SCHEMA_SQL` defines 15 base tables. Helpers: `rowToCamel`, `encryptConnectionFields`.
- **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
Tracks applied migrations in `_omniroute_migrations` table.
-- **Migrations**: 22 files (`001_initial_schema.sql` → `022_compression_settings.sql`).
- Each migration is idempotent and runs in a transaction.
+- **Migrations**: 55 files (`001_initial_schema.sql` → `055_command_code_auth_sessions.sql`).
+ Each migration is idempotent and runs in a transaction. Live count: `ls src/lib/db/migrations/*.sql | wc -l`.
- **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
`combos.ts` → `combos`). Encryption helpers protect sensitive fields at rest.
@@ -212,7 +217,7 @@ Zod schemas, and unit tests aligned when editing.
### Provider Categories
- **Free** (4): Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
-- **OAuth** (8): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline
+- **OAuth** (14): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline, Qwen (⚠️ free tier discontinued 2026-04-15), Kiro, Qoder, Gemini, Windsurf (v3.8), GitLab Duo (v3.8)
- **API Key** (120+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
@@ -321,7 +326,7 @@ Modular prompt compression that runs proactively before the existing reactive co
and iterates through targets in order until one succeeds or all fail.
- **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
`ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
-- **Strategies** (13): priority, weighted, fill-first, round-robin, P2C, random, least-used,
+- **Strategies** (14): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay.
- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
per-target error handling and circuit breaker checks.
@@ -334,7 +339,7 @@ Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
### MCP Server (`open-sse/mcp-server/`)
-37 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas.
+37 tools (30 base + 3 memory + 4 skills), 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (~13 scopes), Zod schemas. See [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md).
**Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,
@@ -369,7 +374,7 @@ handler: async (args) => {...} }`. Zod validates inputs before the handler fires
JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
Agent Card at `/.well-known/agent.json`.
-Skills: `quotaManagement.ts`, `smartRouting.ts`.
+Skills (5): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`.
#### A2A Internals
@@ -422,6 +427,34 @@ MITM proxy capability with certificate management, DNS handling, and target rout
Request middleware including `promptInjectionGuard.ts`.
+### Guardrails (`src/lib/guardrails/`)
+
+Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open; per-request opt-out via header. See [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md).
+
+### Cloud Agents (`src/lib/cloudAgent/`)
+
+`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md).
+
+### Evals (`src/lib/evals/`)
+
+Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/EVALS.md`](docs/EVALS.md).
+
+### Webhooks (`src/lib/webhookDispatcher.ts`)
+
+HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md).
+
+### Authorization Pipeline (`src/server/authz/`)
+
+`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md).
+
+### Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)
+
+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/REASONING_REPLAY.md`](docs/REASONING_REPLAY.md).
+
+### Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)
+
+Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md).
+
### Adding a New Provider
1. Register in `src/shared/constants/providers.ts`
@@ -438,6 +471,36 @@ Request middleware including `promptInjectionGuard.ts`.
- **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
- **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
+## Reference Documentation (docs/)
+
+For any non-trivial change, read the matching deep-dive first:
+
+| Area | Doc |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Repo navigation | [`docs/REPOSITORY_MAP.md`](docs/REPOSITORY_MAP.md) |
+| Architecture | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
+| Engineering reference | [`docs/CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md) |
+| Auto-Combo (9-factor, 14 strategies) | [`docs/AUTO-COMBO.md`](docs/AUTO-COMBO.md) |
+| Resilience (3 layers) | [`docs/RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) |
+| Skills | [`docs/SKILLS.md`](docs/SKILLS.md) |
+| Memory | [`docs/MEMORY.md`](docs/MEMORY.md) |
+| Cloud agents | [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) |
+| Guardrails | [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) |
+| Evals | [`docs/EVALS.md`](docs/EVALS.md) |
+| Compliance | [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) |
+| Webhooks | [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md) |
+| Authz | [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) |
+| Stealth | [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) |
+| Reasoning replay | [`docs/REASONING_REPLAY.md`](docs/REASONING_REPLAY.md) |
+| Agent protocols (A2A / ACP / Cloud) | [`docs/AGENT_PROTOCOLS_GUIDE.md`](docs/AGENT_PROTOCOLS_GUIDE.md) |
+| MCP server | [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md) |
+| A2A server | [`docs/A2A-SERVER.md`](docs/A2A-SERVER.md) |
+| API reference | [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |
+| Provider catalog (auto-generated) | [`docs/PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) |
+| Tunnels | [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md) |
+| Electron desktop | [`docs/ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md) |
+| Release flow | [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) |
+
---
## Review Focus
diff --git a/CLAUDE.md b/CLAUDE.md
index 3859b9c779..3c96cb643f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,7 +11,7 @@ npm run build # Production build (Next.js 16 standalone)
npm run lint # ESLint (0 errors expected; warnings are pre-existing)
npm run typecheck:core # TypeScript check (should be clean)
npm run typecheck:noimplicit:core # Strict check (no implicit any)
-npm run test:coverage # Unit tests + coverage gate (60% min)
+npm run test:coverage # Unit tests + coverage gate (75/75/75/70 — statements/lines/functions/branches)
npm run check # lint + test combined
npm run check:cycles # Detect circular dependencies
```
@@ -37,20 +37,20 @@ For full test matrix, see `CONTRIBUTING.md` → "Running Tests". For deep archit
**OmniRoute** — unified AI proxy/router. One endpoint, 160+ LLM providers, auto-fallback.
-| Layer | Location | Purpose |
-| ------------- | ----------------------- | ------------------------------------------ |
-| API Routes | `src/app/api/v1/` | Next.js App Router — entry points |
-| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) |
-| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch |
-| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) |
-| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions |
-| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc |
-| Database | `src/lib/db/` | SQLite domain modules (22 files) |
-| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic |
-| MCP Server | `open-sse/mcp-server/` | 29 tools, 3 transports, 10 scopes |
-| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol |
-| Skills | `src/lib/skills/` | Extensible skill framework |
-| Memory | `src/lib/memory/` | Persistent conversational memory |
+| Layer | Location | Purpose |
+| ------------- | ----------------------- | ------------------------------------------------------------------ |
+| API Routes | `src/app/api/v1/` | Next.js App Router — entry points |
+| Handlers | `open-sse/handlers/` | Request processing (chat, embeddings, etc) |
+| Executors | `open-sse/executors/` | Provider-specific HTTP dispatch |
+| Translators | `open-sse/translator/` | Format conversion (OpenAI↔Claude↔Gemini) |
+| Transformer | `open-sse/transformer/` | Responses API ↔ Chat Completions |
+| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc |
+| Database | `src/lib/db/` | SQLite domain modules (45+ files, 55 migrations) |
+| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic |
+| MCP Server | `open-sse/mcp-server/` | 37 tools (30 base + 3 memory + 4 skills), 3 transports, ~13 scopes |
+| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol |
+| Skills | `src/lib/skills/` | Extensible skill framework |
+| Memory | `src/lib/memory/` | Persistent conversational memory |
Monorepo: `src/` (Next.js 16 app), `open-sse/` (streaming engine workspace), `electron/` (desktop app), `tests/`, `bin/` (CLI entry point).
@@ -72,7 +72,7 @@ Client → /v1/chat/completions (Next.js route)
API routes follow a consistent pattern: `Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse)`. No global Next.js middleware — interception is route-specific.
-**Combo routing** (`open-sse/services/combo.ts`): 13 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks.
+**Combo routing** (`open-sse/services/combo.ts`): 14 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, strict-random, auto, lkgp, context-optimized, context-relay). Each target calls `handleSingleModel()` which wraps `handleChatCore()` with per-target error handling and circuit breaker checks. See `docs/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/RESILIENCE_GUIDE.md` for the 3 resilience layers.
---
@@ -280,31 +280,78 @@ connection continue serving other models.
### Adding a New A2A Skill
-1. Create skill in `src/lib/a2a/skills/`
+1. Create skill in `src/lib/a2a/skills/` (5 already exist: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Skill receives task context (messages, metadata) → returns structured result
-3. Register in the DB-backed skill registry
-4. Write tests
+3. Register in `A2A_SKILL_HANDLERS` in `src/lib/a2a/taskExecution.ts`
+4. Expose in `src/app/.well-known/agent.json/route.ts` (Agent Card)
+5. Write tests in `tests/unit/`
+6. Document in `docs/A2A-SERVER.md` skill table
+
+### Adding a New Cloud Agent
+
+1. Create agent class in `src/lib/cloudAgent/agents/` extending `CloudAgentBase` (3 already exist: codex-cloud, devin, jules)
+2. Implement `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
+3. Register in `src/lib/cloudAgent/registry.ts`
+4. Add OAuth/credentials handling if needed (`src/lib/oauth/providers/`)
+5. Tests + document in `docs/CLOUD_AGENT.md`
+
+### Adding a New Guardrail / Eval / Skill / Webhook event
+
+- Guardrail: `src/lib/guardrails/` → docs: `docs/GUARDRAILS.md`
+- Eval suite: `src/lib/evals/` → docs: `docs/EVALS.md`
+- Skill (sandbox): `src/lib/skills/` → docs: `docs/SKILLS.md`
+- Webhook event: `src/lib/webhookDispatcher.ts` → docs: `docs/WEBHOOKS.md`
+
+---
+
+## Reference Documentation
+
+For any non-trivial change, read the matching deep-dive first:
+
+| Area | Doc |
+| -------------------------------------------- | --------------------------------------------- |
+| Repo navigation | `docs/REPOSITORY_MAP.md` |
+| Architecture | `docs/ARCHITECTURE.md` |
+| Engineering reference | `docs/CODEBASE_DOCUMENTATION.md` |
+| Auto-Combo (9-factor scoring, 14 strategies) | `docs/AUTO-COMBO.md` |
+| Resilience (3 mechanisms) | `docs/RESILIENCE_GUIDE.md` |
+| Reasoning replay | `docs/REASONING_REPLAY.md` |
+| Skills framework | `docs/SKILLS.md` |
+| Memory system (FTS5 + Qdrant) | `docs/MEMORY.md` |
+| Cloud agents | `docs/CLOUD_AGENT.md` |
+| Guardrails (PII / injection / vision) | `docs/GUARDRAILS.md` |
+| Evals | `docs/EVALS.md` |
+| Compliance / audit | `docs/COMPLIANCE.md` |
+| Webhooks | `docs/WEBHOOKS.md` |
+| Authorization pipeline | `docs/AUTHZ_GUIDE.md` |
+| Stealth (TLS / fingerprint) | `docs/STEALTH_GUIDE.md` |
+| Agent protocols (A2A / ACP / Cloud) | `docs/AGENT_PROTOCOLS_GUIDE.md` |
+| MCP server | `docs/MCP-SERVER.md` |
+| A2A server | `docs/A2A-SERVER.md` |
+| API reference + OpenAPI | `docs/API_REFERENCE.md` + `docs/openapi.yaml` |
+| Provider catalog (auto-generated) | `docs/PROVIDER_REFERENCE.md` |
+| Release flow | `docs/RELEASE_CHECKLIST.md` |
---
## Testing
-| What | Command |
-| ----------------------- | ------------------------------------------------------ |
-| Unit tests | `npm run test:unit` |
-| Single file | `node --import tsx/esm --test tests/unit/file.test.ts` |
-| Vitest (MCP, autoCombo) | `npm run test:vitest` |
-| E2E (Playwright) | `npm run test:e2e` |
-| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` |
-| Ecosystem | `npm run test:ecosystem` |
-| Coverage gate | `npm run test:coverage` (60% min all metrics) |
-| Coverage report | `npm run coverage:report` |
+| What | Command |
+| ----------------------- | --------------------------------------------------------------------------- |
+| Unit tests | `npm run test:unit` |
+| Single file | `node --import tsx/esm --test tests/unit/file.test.ts` |
+| Vitest (MCP, autoCombo) | `npm run test:vitest` |
+| E2E (Playwright) | `npm run test:e2e` |
+| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` |
+| Ecosystem | `npm run test:ecosystem` |
+| Coverage gate | `npm run test:coverage` (75/75/75/70 — statements/lines/functions/branches) |
+| Coverage report | `npm run coverage:report` |
**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`, you must include or update tests in the same PR.
**Test layer preference**: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
-**Copilot coverage policy**: When a PR changes production code and coverage is below 60%, do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.
+**Copilot coverage policy**: When a PR changes production code and coverage is below 75% (statements/lines/functions) or 70% (branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.
---
@@ -350,4 +397,5 @@ git push -u origin feat/your-feature
6. Never silently swallow errors in SSE streams
7. Always validate inputs with Zod schemas
8. Always include tests when changing production code
-9. Coverage must stay ≥60% (statements, lines, functions, branches)
+9. Coverage must stay ≥75% (statements, lines, functions) / ≥70% (branches). Current measured: ~82%.
+10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 18c9147181..cd05342036 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our
community include:
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
@@ -59,8 +59,11 @@ representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-.
+reported to the community leaders responsible for enforcement by opening a
+private security advisory at
+
+or by emailing the maintainer at diegosouza.pw@outlook.com.
+For security-sensitive incidents, see [`SECURITY.md`](SECURITY.md).
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
@@ -106,7 +109,7 @@ Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
+standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
@@ -115,8 +118,8 @@ the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 345a73bbb3..1d40b49dc7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -108,7 +108,7 @@ test: add observability unit tests
refactor(db): consolidate rate limit tables
```
-Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`.
+Scopes (v3.8): `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`.
---
@@ -208,7 +208,7 @@ src/ # TypeScript (.ts / .tsx)
├── mitm/ # MITM proxy (cert, DNS, target routing)
├── shared/
│ ├── components/ # React components (.tsx)
-│ ├── constants/ # Provider definitions (60+), MCP scopes, routing strategies
+│ ├── constants/ # Provider definitions (177), MCP scopes, 14 routing strategies
│ ├── utils/ # Circuit breaker, sanitizer, auth helpers
│ └── validation/ # Zod v4 schemas
└── sse/ # SSE proxy pipeline
diff --git a/GEMINI.md b/GEMINI.md
index 9679e126ad..c927102d37 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1,5 +1,7 @@
# Security and Cleanliness Rules for AI Assistants
+> **Scope:** rules for Gemini-based agents. For Claude Code, see `CLAUDE.md`. For other AI assistants, see `AGENTS.md`.
+
## 1. File Placement & Organization
- **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 (`/`).
@@ -7,15 +9,42 @@
**The Project Root MUST ONLY CONTAIN:**
-- Configuration files (`vitest.config.ts`, `next.config.mjs`, `eslint.config.mjs`, etc.)
+- 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`)
- Dependency files (`package.json`, `package-lock.json`)
-- Documentation files (`README.md`, `CHANGELOG.md`, `AGENTS.md`)
-- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`)
+- 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`)
+- CI/CD files and ignore definitions (`.gitignore`, `.dockerignore`, `.npmignore`, `.npmrc`, `.node-version`, `.nvmrc`, `.env.example`)
When creating _any_ validation tests or one-off logic scripts, default to using `scripts/scratch/` or the `tests/unit/` directories according to your goals. Do not pollute the `/` root context.
-## 2. VPS Dashboard Credentials
+## 2. Hard Rules (mirror of `CLAUDE.md`)
-| Environment | URL | Password |
-| ----------- | ------------------------- | -------- |
-| Local VPS | http://192.168.0.15:20128 | 123456 |
+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.
+2. **Never add logic to `src/lib/localDb.ts`.** It is a re-export barrel only.
+3. **Never use `eval()`, `new Function()`, or any implied eval.** ESLint enforces this.
+4. **Never commit directly to `main`.** Use `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, or `chore/` branches.
+5. **Never write raw SQL in routes** — always go through `src/lib/db/` domain modules.
+6. **Never silently swallow errors in SSE streams** — propagate them or abort the stream cleanly.
+7. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
+8. **Always validate inputs with Zod schemas** from `src/shared/validation/schemas.ts`.
+9. **Always include tests when changing production code** (`src/`, `open-sse/`, `electron/`, `bin/`).
+10. **Coverage must stay** ≥ 75 % statements / 75 % lines / 75 % functions / 70 % branches (real measured: ~82 %).
+
+## 3. Codebase navigation
+
+| Task | Read this first |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Understand the codebase | `docs/REPOSITORY_MAP.md` |
+| Architecture overview | `docs/ARCHITECTURE.md` |
+| Engineering reference | `docs/CODEBASE_DOCUMENTATION.md` |
+| Add a feature | `CONTRIBUTING.md` + the matching `docs/" | "model:", "tier": "quick" | "standard" | "deep" }
- Response: { "run_id": "...", "status": "started" }
-
-# Get assessment results
-GET /api/assess/results
- Query: ?status=working|broken|rate_limited&provider=kiro&category=coding
- Response: { "models": [...] }
-
-# Get combo health dashboard
-GET /api/assess/combo-health
- Response: { "combos": [{ "id": "...", "name": "...", "healthy_models": 5, "dead_models": 2, "health_score": 0.71 }] }
-
-# Auto-fix all combos
-POST /api/assess/auto-fix
- Response: { "fixed_combos": 3, "removed_models": ["ollamacloud/glm-5.1", "..."], "added_models": [...] }
-
-# Auto-generate combos from assessments
-POST /api/assess/auto-generate
- Response: { "generated_combos": ["auto/best-coding", "..."], "models_per_combo": { "auto/best-coding": 5 } }
-
-# Get assessment run history
-GET /api/assess/runs
- Response: { "runs": [...] }
-```
-
-### 6. Integration with Existing comboResolver
-
-The existing `comboResolver.ts` already handles `priority`, `weighted`, `round-robin`, `random`, and `least-used` strategies. The enhancement:
-
-```typescript
-// In comboResolver.ts — add health-aware filtering
-export function resolveComboModel(combo, context = {}) {
- const models = combo.models || [];
- if (models.length === 0) {
- throw new Error(`Combo "${combo.name}" has no models configured`);
- }
-
- const normalized = models
- .map((entry) => ({
- model: getComboStepTarget(entry) || "",
- weight: getComboStepWeight(entry) || 1,
- }))
- .filter((entry) => entry.model);
-
- // NEW: Filter out models known to be broken/rate_limited
- const healthy = normalized.filter((entry) => {
- const assessment = getAssessment(entry.model);
- if (!assessment) return true; // Unknown → allow (haven't tested yet)
- return assessment.status === "working" || assessment.status === "unknown";
- });
-
- // If all models are unhealthy, fall back to full list (better to try than to fail)
- const pool = healthy.length > 0 ? healthy : normalized;
-
- const strategy = combo.strategy || "priority";
- // ... existing resolution logic using `pool` instead of `normalized`
-}
-```
-
-### 7. Integration with Existing Auto-Combo Scoring (`open-sse/services/autoCombo/scoring.ts`)
-
-The existing scoring function already uses 6 factors + tier. The assessment engine enriches these:
-
-| Existing Factor | Current Source | Enhanced Source |
-| ------------------- | ------------------------ | ----------------------------------------- |
-| Quota (0.20) | Provider connection data | Same + assessment success_rate |
-| Health (0.25) | Circuit breaker state | Same + assessment status (working/broken) |
-| CostInv (0.20) | Static cost data | Same + live cost measurement |
-| LatencyInv (0.15) | P95 latency from logs | Same + assessment probe latency |
-| TaskFit (0.10) | Static fitness table | **NEW: from assessment categories** |
-| Stability (0.05) | Latency stddev | Same + assessment consecutive_fails |
-| TierPriority (0.05) | Account tier | Same |
-
-The key enhancement: `taskFit` currently uses a **static** fitness lookup (`taskFitness.ts`). With assessments, we derive fitness from **live probe results** — a model that actually passes coding probes gets a high `coding` fitness, not just because its name contains "coder".
-
-### 8. Dashboard UI (Future PR)
-
-The assessment state should be visible in the omniroute dashboard:
-
-- **Model Health Grid**: table showing each provider/model with colored status indicators
-- **Combo Health Summary**: per-combo health score with expandable model details
-- **Assessment History**: timeline of assessment runs with pass/fail counts
-- **Auto-Fix Log**: history of automatic combo modifications
-
----
-
-## Migration Path
-
-### Phase 1: Assessment Engine (This PR)
-
-- New `model_assessments`, `assessment_runs`, `combo_health` tables
-- Assessor service with quick/standard/deep probes
-- Categorizer with fitness scoring
-- Self-healer with auto-fix rules
-- REST API endpoints
-- Integration with comboResolver to skip broken models
-
-### Phase 2: Auto-Generation (Follow-up PR)
-
-- Auto-generate combos from assessed models
-- Smart combo naming and categorization
-- Cross-provider fallback chains
-- Dashboard UI for assessment results
-
-### Phase 3: Continuous Learning (Follow-up PR)
-
-- Feeds assessment results back into auto-combo scoring weights
-- Adapts fitness scores based on real request outcomes
-- A/B testing across providers to find optimal routing
-- Automatic mode pack switching (ship-fast during peak, cost-saver off-peak)
-
----
-
-## Implementation Files
-
-| File | Purpose | New/Modified |
-| ---------------------------------------- | ---------------------------------------- | ------------ |
-| `src/domain/assessor.ts` | Probe engine (quick/standard/deep) | **NEW** |
-| `src/domain/categorizer.ts` | Model categorization & fitness | **NEW** |
-| `src/domain/selfHealer.ts` | Auto-fix combos, remove dead models | **NEW** |
-| `src/domain/comboResolver.ts` | Add health-aware filtering | **MODIFIED** |
-| `src/domain/types.ts` | Add ModelAssessment, ModelCategory types | **MODIFIED** |
-| `src/lib/db/assessments.ts` | DB access for assessment tables | **NEW** |
-| `open-sse/services/autoCombo/scoring.ts` | Use assessment data for taskFit | **MODIFIED** |
-| `src/app/api/assess/route.ts` | REST API routes | **NEW** |
-| `scripts/assess-models.mjs` | CLI script for on-demand assessment | **NEW** |
-| `scripts/migrate-assessments.mjs` | DB migration script | **NEW** |
-
----
-
-## Testing Plan
-
-### Unit Tests
-
-- Assessor probe logic (mock provider responses)
-- Categorizer fitness score calculations
-- Self-healer rules (remove, reduce, restore, emergency add)
-- comboResolver integration (skip broken models)
-
-### Integration Tests
-
-- Full assessment cycle: add provider → probe models → categorize → auto-fix combos
-- Health-aware routing: broken model skipped, restored model re-included
-- Assessment run persistence and recovery
-
-### Manual Testing (our experience as reference)
-
-```bash
-# Our actual test sequence that should be automated:
-# 1. Start omniroute with 406 provider connections (51 providers)
-# 2. Discover only 8 models actually work from 2 providers (kiro, ollamacloud)
-# 3. Manually update 44 combos with working models only
-# 4. Verify all 15 key combos pass end-to-end
-# 5. Set up auto-sync cron for model list updates
-
-# With auto-assessment, this entire process should be:
-# 1. Start omniroute
-# 2. Run: curl -X POST http://localhost:20128/api/assess/models -d '{"scope":"all"}'
-# 3. Wait for assessment to complete
-# 4. Run: curl -X POST http://localhost:20128/api/assess/auto-fix
-# 5. All combos are now healthy
-```
-
----
-
-## Success Metrics
-
-| Metric | Current (Manual) | Target (Auto-Assessment) |
-| -------------------------------- | --------------------------------- | ------------------------------- |
-| Time to configure working combos | 2-4 hours | < 5 minutes |
-| Dead model detection | Manual curl testing | Automatic, continuous |
-| Combo health visibility | None | Dashboard + API |
-| Provider failure recovery | Manual DB updates | Auto-heal within 5 minutes |
-| New provider onboarding | Manual combo editing | Auto-discover + auto-categorize |
-| Model deprecation handling | Manual detection (users complain) | Proactive removal + alerting |
-
----
-
-## Backwards Compatibility
-
-- All new tables are additive — no schema changes to existing tables
-- comboResolver filtering is opt-in via config flag (default: enabled)
-- Existing combo configurations are preserved — self-healer only modifies them, doesn't replace
-- Assessment can be disabled with `OMNIRoute_DISABLE_ASSESSMENT=1` env var
-- All API endpoints are new — no existing endpoints changed
-
----
-
-## Open Questions
-
-1. **Probe cost**: Who pays for assessment probes? Should we limit to free-tier models or use a separate assessment budget?
-2. **Assessment frequency**: How often should deep probes run? Current proposal: 6h, but some users may want more/less frequent.
-3. **Auto-fix aggression**: Should self-healer remove models immediately on first failure, or wait for N consecutive failures?
-4. **Cross-provider model equivalence**: Should `kiro/claude-sonnet-4.5` and `gh/claude-sonnet-4.5` be treated as the same model for combo purposes?
-5. **Assessment during startup**: Should assessment block startup or run in background?
diff --git a/docs/i18n/ar/llm.txt b/docs/i18n/ar/llm.txt
index 1821dc6b05..f632acf7a0 100644
--- a/docs/i18n/ar/llm.txt
+++ b/docs/i18n/ar/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/bg/llm.txt b/docs/i18n/bg/llm.txt
index b8d82e19d9..a3cf0bc811 100644
--- a/docs/i18n/bg/llm.txt
+++ b/docs/i18n/bg/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/bn/llm.txt b/docs/i18n/bn/llm.txt
index c6c2ed17f2..3e3a618682 100644
--- a/docs/i18n/bn/llm.txt
+++ b/docs/i18n/bn/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/cs/llm.txt b/docs/i18n/cs/llm.txt
index 5706410a70..d75cfb0f73 100644
--- a/docs/i18n/cs/llm.txt
+++ b/docs/i18n/cs/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/da/llm.txt b/docs/i18n/da/llm.txt
index 51dd797797..ac343ef264 100644
--- a/docs/i18n/da/llm.txt
+++ b/docs/i18n/da/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/de/llm.txt b/docs/i18n/de/llm.txt
index dc75ee0ef2..55c98f2226 100644
--- a/docs/i18n/de/llm.txt
+++ b/docs/i18n/de/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/es/llm.txt b/docs/i18n/es/llm.txt
index cd810711d3..2dbf99212d 100644
--- a/docs/i18n/es/llm.txt
+++ b/docs/i18n/es/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/fa/llm.txt b/docs/i18n/fa/llm.txt
index 9ee7d22c20..43d14c5164 100644
--- a/docs/i18n/fa/llm.txt
+++ b/docs/i18n/fa/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/fi/llm.txt b/docs/i18n/fi/llm.txt
index c720e29c48..3b8fd6ceb2 100644
--- a/docs/i18n/fi/llm.txt
+++ b/docs/i18n/fi/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/fr/llm.txt b/docs/i18n/fr/llm.txt
index 91c42a60a4..3805843928 100644
--- a/docs/i18n/fr/llm.txt
+++ b/docs/i18n/fr/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/gu/llm.txt b/docs/i18n/gu/llm.txt
index 93ba32e2f9..efdebba7db 100644
--- a/docs/i18n/gu/llm.txt
+++ b/docs/i18n/gu/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/he/llm.txt b/docs/i18n/he/llm.txt
index 47ade9e353..ea3add4736 100644
--- a/docs/i18n/he/llm.txt
+++ b/docs/i18n/he/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/hi/llm.txt b/docs/i18n/hi/llm.txt
index 1cb382da90..4c1fd0e7b5 100644
--- a/docs/i18n/hi/llm.txt
+++ b/docs/i18n/hi/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/hu/llm.txt b/docs/i18n/hu/llm.txt
index 0b6577ac44..962b33e890 100644
--- a/docs/i18n/hu/llm.txt
+++ b/docs/i18n/hu/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/id/llm.txt b/docs/i18n/id/llm.txt
index 05336cecdb..dc159223f9 100644
--- a/docs/i18n/id/llm.txt
+++ b/docs/i18n/id/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/in/llm.txt b/docs/i18n/in/llm.txt
index dfe52e8d89..dfc141a97c 100644
--- a/docs/i18n/in/llm.txt
+++ b/docs/i18n/in/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/it/llm.txt b/docs/i18n/it/llm.txt
index e24e2ecf5b..c9bb401e7b 100644
--- a/docs/i18n/it/llm.txt
+++ b/docs/i18n/it/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ja/llm.txt b/docs/i18n/ja/llm.txt
index b8ecfda395..16f03cfc0f 100644
--- a/docs/i18n/ja/llm.txt
+++ b/docs/i18n/ja/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ko/llm.txt b/docs/i18n/ko/llm.txt
index 1ce6383a65..f0315b1d54 100644
--- a/docs/i18n/ko/llm.txt
+++ b/docs/i18n/ko/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/mr/llm.txt b/docs/i18n/mr/llm.txt
index 2959f516b5..2d4b0c2b8f 100644
--- a/docs/i18n/mr/llm.txt
+++ b/docs/i18n/mr/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ms/llm.txt b/docs/i18n/ms/llm.txt
index 0f64418b09..1832e506f9 100644
--- a/docs/i18n/ms/llm.txt
+++ b/docs/i18n/ms/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/nl/llm.txt b/docs/i18n/nl/llm.txt
index 3ebeb0d797..dca3cd438e 100644
--- a/docs/i18n/nl/llm.txt
+++ b/docs/i18n/nl/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/no/llm.txt b/docs/i18n/no/llm.txt
index ee38a5e616..0471d80fed 100644
--- a/docs/i18n/no/llm.txt
+++ b/docs/i18n/no/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/phi/llm.txt b/docs/i18n/phi/llm.txt
index 970bc2b780..920c658f14 100644
--- a/docs/i18n/phi/llm.txt
+++ b/docs/i18n/phi/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/pl/llm.txt b/docs/i18n/pl/llm.txt
index a2347fabd4..bc6d82e0c3 100644
--- a/docs/i18n/pl/llm.txt
+++ b/docs/i18n/pl/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/pt-BR/llm.txt b/docs/i18n/pt-BR/llm.txt
index 6d9c9391d3..d2de5e8572 100644
--- a/docs/i18n/pt-BR/llm.txt
+++ b/docs/i18n/pt-BR/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/pt/llm.txt b/docs/i18n/pt/llm.txt
index 8ec2bd2dd5..5a996733a1 100644
--- a/docs/i18n/pt/llm.txt
+++ b/docs/i18n/pt/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ro/llm.txt b/docs/i18n/ro/llm.txt
index f888e73889..820e67516a 100644
--- a/docs/i18n/ro/llm.txt
+++ b/docs/i18n/ro/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ru/llm.txt b/docs/i18n/ru/llm.txt
index 5ad11109be..05de9ed5e8 100644
--- a/docs/i18n/ru/llm.txt
+++ b/docs/i18n/ru/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/sk/llm.txt b/docs/i18n/sk/llm.txt
index a3415fcd06..a52e4424f0 100644
--- a/docs/i18n/sk/llm.txt
+++ b/docs/i18n/sk/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/sv/llm.txt b/docs/i18n/sv/llm.txt
index b5f4d93299..9763509bf5 100644
--- a/docs/i18n/sv/llm.txt
+++ b/docs/i18n/sv/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/sw/llm.txt b/docs/i18n/sw/llm.txt
index 95bdcb6513..5bc44125ea 100644
--- a/docs/i18n/sw/llm.txt
+++ b/docs/i18n/sw/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ta/llm.txt b/docs/i18n/ta/llm.txt
index f7a4ed71ce..a6c818cf92 100644
--- a/docs/i18n/ta/llm.txt
+++ b/docs/i18n/ta/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/te/llm.txt b/docs/i18n/te/llm.txt
index 7a2bdfbcf2..ed29612aad 100644
--- a/docs/i18n/te/llm.txt
+++ b/docs/i18n/te/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/th/llm.txt b/docs/i18n/th/llm.txt
index fd8a43b8c9..2c76b7e3aa 100644
--- a/docs/i18n/th/llm.txt
+++ b/docs/i18n/th/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/tr/llm.txt b/docs/i18n/tr/llm.txt
index b0d0c12d59..94e60c1ba6 100644
--- a/docs/i18n/tr/llm.txt
+++ b/docs/i18n/tr/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/uk-UA/llm.txt b/docs/i18n/uk-UA/llm.txt
index 424f53a820..7547505898 100644
--- a/docs/i18n/uk-UA/llm.txt
+++ b/docs/i18n/uk-UA/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/ur/llm.txt b/docs/i18n/ur/llm.txt
index f85a35aa5c..5a161021e2 100644
--- a/docs/i18n/ur/llm.txt
+++ b/docs/i18n/ur/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/vi/llm.txt b/docs/i18n/vi/llm.txt
index 2c7dcbd683..1d81a277ab 100644
--- a/docs/i18n/vi/llm.txt
+++ b/docs/i18n/vi/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/docs/i18n/zh-CN/llm.txt b/docs/i18n/zh-CN/llm.txt
index 3eab3bd1b7..8dd20af3fc 100644
--- a/docs/i18n/zh-CN/llm.txt
+++ b/docs/i18n/zh-CN/llm.txt
@@ -4,7 +4,7 @@
---
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -16,9 +16,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -186,7 +186,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -286,24 +286,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -349,25 +350,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -440,15 +440,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -468,6 +468,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -475,3 +502,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`
diff --git a/llm.txt b/llm.txt
index 5435818193..4425d70668 100644
--- a/llm.txt
+++ b/llm.txt
@@ -1,6 +1,6 @@
# OmniRoute
-> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 160+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (29 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app.
+> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 177 AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (37 tools), A2A v0.3 protocol, Memory/Skills systems, Cloud Agents (codex-cloud, devin, jules), Guardrails framework, and an Electron desktop app.
## Overview
@@ -12,9 +12,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Tech Stack
-- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`)
+- **Runtime:** Node.js `>=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
- **Framework:** Next.js 16 (App Router) with TypeScript 5.9
-- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations)
+- **Database:** SQLite via better-sqlite3 (local, zero-config, 55 migrations)
- **State management:** Zustand (client), SQLite (server persistence)
- **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons
- **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth
@@ -182,7 +182,7 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
├── open-sse/ # Standalone SSE server (npm workspace)
│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video,
│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models)
-│ ├── executors/ # Provider-specific request executors (14 executors)
+│ ├── executors/ # Provider-specific request executors (31 executors)
│ │ ├── base.ts # Base executor with shared logic
│ │ ├── default.ts # Default OpenAI-compatible executor
│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum)
@@ -282,24 +282,25 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
## Key Features (v3.8.0)
### Core Proxy
-- **160+ AI providers** with automatic format translation
-- **4 provider categories**: Free (4), OAuth (8), API Key (120+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
-- **13 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay
+- **177 AI providers** with automatic format translation
+- **4 provider categories**: Free (5), OAuth (14), API Key (123+), Self-Hosted (8+), Custom (OpenAI/Anthropic-compatible)
+- **14 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, **reset-aware** (v3.8)
- **4-tier fallback**: Subscription → API Key → Cheap → Free
- **Context Relay strategy**: Session handoff summaries on account rotation for continuity
-- **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown
+- **Auto-combo engine**: Self-healing routing optimization with **9-factor scoring** (health/quota/costInv/latencyInv/taskFit/specificityMatch/stability/tierPriority/tierAffinity), bandit exploration, progressive cooldown
- **Semantic caching** with cache hit/miss headers
- **Idempotency** with configurable dedup window
-- **Circuit breaker** per provider with configurable thresholds
+- **3-layer resilience**: Provider Circuit Breaker / Connection Cooldown / Model Lockout
- **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback
- **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers
- **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement
- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization
- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills
-- **Prompt Injection Guard**: Middleware-level prompt injection detection
+- **Cloud Agents**: Codex Cloud, Devin, Jules — autonomous coding agents with task lifecycle management
+- **Guardrails Framework**: Hot-reloadable registry with vision-bridge, pii-masker, prompt-injection (priority-ordered)
- **MITM Proxy**: Certificate management, DNS handling, and target routing
- **Cloudflare Tunnels**: Managed tunnel creation for remote access
-- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches)
+- **Coverage gate**: 75% statements/lines/functions, 70% branches (measured ~82%)
### Security
- **Data Loss Prevention**: SQLite migration safety bounds abort startup on dangerous massive schema overrides. Pre-migration `VACUUM INTO` backups isolate rollback snapshots.
@@ -345,25 +346,24 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}`
- **Ollama** — `/v1/api/chat`, `/api/tags`
- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily)
-- **MCP** — 29-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
-- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills)
+- **MCP** — 37-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP)
+- **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, 5 skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
- **ACP** — Agent Communication Protocol registry and manager
-### MCP Server (29 Tools)
-| Category | Tools |
-|-----------|-------|
-| Core (20) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing` |
-| Cache (2) | `cache_stats`, `cache_flush` |
+### MCP Server (37 Tools)
+| Category | Tools |
+|------------|-------|
+| Core (30) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `web_search`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `db_health_check`, `sync_pricing`, `cache_stats`, `cache_flush`, and advanced routing/diagnostics tools (see `docs/MCP-SERVER.md` for full inventory) |
| Memory (3) | `memory_search`, `memory_add`, `memory_clear` |
| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` |
-**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`
+**MCP Auth Scopes (~13):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience`, plus memory/skills scopes — full list in `docs/MCP-SERVER.md`.
### Provider Categories
-**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI
+**Free Providers (5):** Qoder AI, Qwen Code (deprecated), Gemini CLI, Kiro AI, Windsurf
-**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline
+**OAuth Providers (14):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan
@@ -436,15 +436,15 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`.
-5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
+5. **Database layer:** Operations go through `src/lib/db/` modules (45+ domain-specific files, 55 migrations). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module.
-6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`).
+6. **Tests** use Node.js built-in test runner + Vitest. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). Coverage gate: 75% statements/lines/functions, 70% branches.
7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes.
8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB.
-9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown.
+9. **Auto-combo engine** in `open-sse/services/autoCombo/` — **9-factor scoring** (health 0.22, quota 0.17, costInv 0.17, latencyInv 0.13, taskFit 0.08, specificityMatch 0.08, stability 0.05, tierPriority 0.05, tierAffinity 0.05), 4 mode packs, bandit exploration, progressive cooldown.
10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130).
@@ -464,6 +464,33 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
18. **Node.js 24+ compatibility**: The login page (`/api/settings/require-login`) detects the Node.js version and sends `nodeVersion`/`nodeCompatible` fields. The login UI renders a warning banner when `nodeCompatible` is false.
+19. **Cloud Agents** in `src/lib/cloudAgent/` — three external autonomous coding agents (Codex Cloud, Devin, Jules) with task lifecycle endpoints under `/api/v1/agents/tasks/`. Require management auth, not client auth.
+
+20. **Guardrails framework** in `src/lib/guardrails/` — hot-reloadable registry. Built-ins (priority-ordered): `vision-bridge` (5) → `pii-masker` (10) → `prompt-injection` (20). Fail-open model: exceptions never block traffic. Per-request opt-out via `x-omniroute-disabled-guardrails` header.
+
+21. **Authz pipeline** (`src/server/authz/`): every request is classified as `PUBLIC`, `CLIENT_API`, or `MANAGEMENT`, then run through policy + enforce stages. See `docs/AUTHZ_GUIDE.md`.
+
+22. **Three resilience layers** are distinct (do not conflate them):
+ - **Provider Circuit Breaker** (`src/shared/utils/circuitBreaker.ts`) — whole-provider scope.
+ - **Connection Cooldown** (`src/sse/services/auth.ts::markAccountUnavailable`) — one key/account scope.
+ - **Model Lockout** (`open-sse/services/accountFallback.ts`) — provider + connection + model scope.
+
+## v3.8.0 Highlights
+
+- **Cloud Agents** (Codex Cloud, Devin, Jules) with task lifecycle management and management-auth enforcement
+- **Guardrails framework**: hot-reloadable registry with vision-bridge, pii-masker, prompt-injection
+- **9-factor Auto-Combo scoring** (was 6-factor in earlier versions)
+- **`reset-aware` routing strategy** (14th strategy) — picks the account whose quota will reset soonest
+- **A2A protocol expanded to 5 skills**: smart-routing, quota-management, provider-discovery, cost-analysis, health-report
+- **MCP server expanded to 37 tools** (30 base + 3 memory + 4 skills) across ~13 scopes
+- **OAuth providers expanded to 14**: added Qwen, Kiro, Qoder, Gemini, Windsurf, GitLab Duo
+- **Coverage gate raised to 75/75/75/70** (was 60% across the board) — measured ~82%
+- **Reasoning replay** (`docs/REASONING_REPLAY.md`) — capture and inspect provider reasoning streams
+- **Compliance + Evals + Webhooks** documentation introduced
+- **Stealth guide** (`docs/STEALTH_GUIDE.md`) — TLS / CLI fingerprint configuration
+- **Tunnels guide** (`docs/TUNNELS_GUIDE.md`) — Cloudflare tunnel management
+- **Electron guide** (`docs/ELECTRON_GUIDE.md`) — desktop app build + signing
+
## Links
- Repository: https://github.com/diegosouzapw/OmniRoute
@@ -471,3 +498,14 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo
- npm: https://www.npmjs.com/package/omniroute
- Docker Hub: https://hub.docker.com/r/diegosouzapw/omniroute
- Documentation: See `/docs/` directory
+
+### Documentation Index
+
+- **Architecture & Reference**: `docs/ARCHITECTURE.md`, `docs/CODEBASE_DOCUMENTATION.md`, `docs/REPOSITORY_MAP.md`, `docs/API_REFERENCE.md`, `docs/PROVIDER_REFERENCE.md`, `docs/openapi.yaml`
+- **Operator guides**: `docs/USER_GUIDE.md`, `docs/CLI-TOOLS.md`, `docs/TROUBLESHOOTING.md`, `docs/COVERAGE_PLAN.md`
+- **Protocols**: `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AGENT_PROTOCOLS_GUIDE.md`, `docs/CLOUD_AGENT.md`
+- **Routing & resilience**: `docs/AUTO-COMBO.md`, `docs/RESILIENCE_GUIDE.md`
+- **Security**: `docs/AUTHZ_GUIDE.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/STEALTH_GUIDE.md`
+- **Extensibility**: `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`
+- **Platform**: `docs/ELECTRON_GUIDE.md`, `docs/TUNNELS_GUIDE.md`
+- **AI agents**: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`