diff --git a/AGENTS.md b/AGENTS.md index 8023ca4c03..9dec913a17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,14 +3,14 @@ ## Project Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support -with **229 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, +with **232 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra, SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more) -with **MCP Server** (69 tools), **A2A v0.3 Protocol**, and **Electron desktop app**. +with **MCP Server** (87 tools), **A2A v0.3 Protocol**, and **Electron desktop app**. -> **Live counts (v3.8.16)**: providers 229 · MCP tools 69 · MCP scopes 13 · A2A skills 6 · -> open-sse services 111 · routing strategies 15 · auto-combo scoring factors 12 · -> DB modules 76 · DB migrations 94 · base tables 17 · search providers 12 · +> **Live counts (v3.8.24)**: providers 232 · MCP tools 87 · MCP scopes 30 · A2A skills 6 · +> open-sse services 115 · routing strategies 15 · auto-combo scoring factors 12 · +> DB modules 83 · DB migrations 97 · base tables 17 · search providers 11 · > i18n locales 42. **Refresh with `npm run check:docs-all`.** ## Doc Accuracy Discipline (read before writing any doc) @@ -44,8 +44,8 @@ codebase. Run it locally before pushing docs; it runs in CI via `npm run check:d ## Stack -- **Runtime**: Next.js 16 (App Router), Node.js `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`, ES Modules (`"type": "module"`) -- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`, `electron/`) +- **Runtime**: Next.js 16 (App Router), Node.js `>=22.0.0 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`) +- **Language**: TypeScript 6.0 (`src/`) + JavaScript (`open-sse/`, `electron/`) - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/` - **Streaming**: SSE via `open-sse` internal workspace package - **Styling**: Tailwind CSS v4 @@ -178,7 +178,7 @@ Always run `prettier --write` on changed files. ### Data Layer (`src/lib/db/`) -All persistence uses SQLite through **76 domain-specific modules** in `src/lib/db/`. Top modules: +All persistence uses SQLite through **83 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` @@ -188,8 +188,8 @@ All persistence uses SQLite through **76 domain-specific modules** in `src/lib/d - 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 76). Drift detection: `npm run check:docs-counts`. -Schema migrations live in `db/migrations/` (**94 files** as of v3.8.16) and run via `migrationRunner.ts`. +Live count: `ls src/lib/db/*.ts | wc -l` (currently 83). Drift detection: `npm run check:docs-counts`. +Schema migrations live in `db/migrations/` (**97 files** as of v3.8.24) and run via `migrationRunner.ts`. `src/lib/localDb.ts` is a **re-export layer only** — never add logic there. #### DB Internals @@ -198,7 +198,7 @@ Schema migrations live in `db/migrations/` (**94 files** as of v3.8.16) and run journaling. `SCHEMA_SQL` defines **17 base tables** (verify with `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for the bookkeeping `_omniroute_migrations` table). Helpers: `rowToCamel`, `encryptConnectionFields`. - **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions. Tracks applied migrations in `_omniroute_migrations` table. -- **Migrations**: 94 files (`001_initial_schema.sql` → `094_*.sql`). +- **Migrations**: 97 files (`001_initial_schema.sql` → `099_*.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`, @@ -336,7 +336,7 @@ Includes request/response translators with helpers for image handling. ### Services (`open-sse/services/`) -111 service modules in `open-sse/services/` (top-level only; 171 including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules: +115 service modules in `open-sse/services/` (top-level only; 184 including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`, `rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`, `autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`, @@ -391,7 +391,7 @@ Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`, ### MCP Server (`open-sse/mcp-server/`) -69 tools across 10 tool files (advancedTools: 5, agentSkillTools: 3, compressionTools: 5, gamificationTools: 8, memoryTools: 3, notionTools: 6, obsidianTools: 22, pluginTools: 8, poolTools: 5, skillTools: 4), 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (13 scopes — see `OMNIROUTE_MCP_SCOPES` in `open-sse/mcp-server/README.md:51`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md). +**87 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 33-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (30 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/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, @@ -409,6 +409,14 @@ list_compression_combos, compression_combo_stats. **Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions. +**Agent-skill tools** (3): A2A skill discovery / invocation bridges. + +**Gamification tools** (8): levels, badges, leaderboard, and community-federation queries. + +**Plugin tools** (8): plugin marketplace listing, install/enable/disable, and runtime inspection. + +**Notion tools** (6) + **Obsidian tools** (22): knowledge-base read/write integrations (the largest tool family — vault search, note CRUD, WebDAV-backed file ops). + #### MCP Internals - **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema, @@ -417,7 +425,7 @@ handler: async (args) => {...} }`. Zod validates inputs before the handler fires `createMcpServer()` wires all tool sets; `startMcpStdio()` launches the stdio transport. - **Transports**: stdio (CLI `omniroute --mcp`), SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). All share the same tool/scope engine. -- **Scopes** (13): Control which tool categories an API key can access. Enforcement happens +- **Scopes** (30): Control which tool categories an API key can access. Enforcement happens before handler dispatch. - **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name, args, success/failure, API key attribution, and timestamp. @@ -519,7 +527,6 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md ## Subdirectory AGENTS.md Files -- **[`open-sse/AGENTS.md`](open-sse/AGENTS.md)** — Streaming engine, request pipeline, handlers, and executors - **[`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 @@ -527,32 +534,32 @@ Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md For any non-trivial change, read the matching deep-dive first: -| Area | Doc | -| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Repo navigation | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md) | -| Architecture | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) | -| Engineering reference | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md) | -| Auto-Combo (12-factor, 15 strategies) | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md) | -| Resilience (3 layers) | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) | -| Skills | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) | -| Memory | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) | -| Cloud agents | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) | -| Guardrails | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) | -| Evals | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md) | -| Compliance | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) | -| Webhooks | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) | -| Authz | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) | -| Stealth | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) | -| Reasoning replay | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) | -| Agent protocols (A2A / ACP / Cloud) | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) | -| MCP server | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) | -| A2A server | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) | -| API reference | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/reference/openapi.yaml`](docs/reference/openapi.yaml) | -| Provider catalog (auto-generated) | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) | -| Tunnels | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md) | -| Electron desktop | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) | -| Release flow | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md) | -| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md) | +| Area | Doc | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| Repo navigation | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md) | +| Architecture | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) | +| Engineering reference | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md) | +| Auto-Combo (12-factor, 15 strategies) | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md) | +| Resilience (3 layers) | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) | +| Skills | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) | +| Memory | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) | +| Cloud agents | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) | +| Guardrails | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) | +| Evals | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md) | +| Compliance | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) | +| Webhooks | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) | +| Authz | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) | +| Stealth | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) | +| Reasoning replay | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) | +| Agent protocols (A2A / ACP / Cloud) | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) | +| MCP server | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) | +| A2A server | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) | +| API reference | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/reference/openapi.yaml`](docs/reference/openapi.yaml) | +| Provider catalog (auto-generated) | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) | +| Tunnels | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md) | +| Electron desktop | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) | +| Release flow | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md) | +| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md) | --- diff --git a/CLAUDE.md b/CLAUDE.md index 3e4b24567a..9ee18e58c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 (45+ files, 55 migrations) | -| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic | -| MCP Server | `open-sse/mcp-server/` | 43 tools (30 base + 3 memory + 4 skills + 6 notion), 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 | +| 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 (83 files, 97 migrations) | +| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic | +| MCP Server | `open-sse/mcp-server/` | 87 tools (33 base + memory/skill/notion/obsidian/gamification/plugin modules), 3 transports (stdio / SSE / Streamable HTTP), 30 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`): 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/routing/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers. +**Combo routing** (`open-sse/services/combo.ts`): 15 strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, reset-aware, reset-window, 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/routing/AUTO-COMBO.md` for the 9-factor Auto-Combo scoring and `docs/architecture/RESILIENCE_GUIDE.md` for the 3 resilience layers. --- @@ -332,7 +332,7 @@ For any non-trivial change, read the matching deep-dive first: | Repo navigation | `docs/architecture/REPOSITORY_MAP.md` | | Architecture | `docs/architecture/ARCHITECTURE.md` | | Engineering reference | `docs/architecture/CODEBASE_DOCUMENTATION.md` | -| Auto-Combo (9-factor scoring, 14 strategies) | `docs/routing/AUTO-COMBO.md` | +| Auto-Combo (9-factor scoring, 15 strategies) | `docs/routing/AUTO-COMBO.md` | | Resilience (3 mechanisms) | `docs/architecture/RESILIENCE_GUIDE.md` | | Reasoning replay | `docs/routing/REASONING_REPLAY.md` | | Skills framework | `docs/frameworks/SKILLS.md` | @@ -377,6 +377,7 @@ For any non-trivial change, read the matching deep-dive first: **Both test runners must pass**: `npm run test:unit` (Node native — most tests) AND `npm run test:vitest` (MCP server, autoCombo, cache) cover **non-overlapping files**. Both are wired in CI (jobs `test-unit` and `test-vitest`) and must be green before merging. A PR where only one suite passes may silently ship broken MCP tools or routing regressions. **Bug fix / issue triage protocol (Hard Rule #18)**: Every fix for a reported issue must be validated by one of the following — no exceptions: + 1. **TDD (preferred)** — write a failing test reproducing the bug → fix it → confirm the test passes. The test becomes the permanent regression guard. Touch only the files the test proves need changing; nothing more. 2. **Real-environment test (when TDD is not possible)** — deploy to the production VPS (`root@192.168.0.15`) and run a documented live test. Record the exact command + result in the PR description. Applies to: OAuth upstream flows, Cloudflare/WS upstream behavior, UI-only regressions, hardware-dependent behavior. 3. "It worked locally without a test" does not count. A fix without a test or a VPS validation record is not a fix — it is a guess. @@ -403,14 +404,14 @@ git push -u origin feat/your-feature **Husky hooks**: - **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11` -- **pre-push**: currently disabled (hook is commented out — CI covers test:unit via the `test-unit` job) +- **pre-push**: fast deterministic gates (`check:any-budget:t11` + `check:tracked-artifacts`); intentionally excludes `test:unit` (slow — covered by the CI `test-unit` job). Activated 2026-06-13 (Quality Gates Fase 6A.12). --- ## Environment -- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules -- **TypeScript**: 5.9+, target ES2022, module esnext, resolution bundler +- **Runtime**: Node.js ≥22.0.0 <23 || ≥24.0.0 <27, ES Modules +- **TypeScript**: 6.0+, target ES2022, module esnext, resolution bundler - **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` - **Default port**: 20128 (API + dashboard on same port) - **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/` @@ -468,10 +469,13 @@ the stale-enforcement added in Fase 6A.3. ## PII & Stream Sanitization Learnings ### 1. Regex Security (ReDoS) + All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges `{1,7}`) to prevent catastrophic backtracking when processing untrusted inputs. ### 2. SSE Snapshot Handling + When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (`done` or `completed` events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream. ### 3. Database Handles in Tests + Ensure that any unit tests that trigger database migrations or establish SQLite connections call `resetDbInstance()` and properly clean up/close all DB handles in a `test.after(...)` hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely. diff --git a/README.md b/README.md index 467e920a1e..14594deddf 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ [![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-177-ai-providers--50-free) [![1.9B+ Free Tokens/mo](https://img.shields.io/badge/1.9B%2B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/reference/FREE_TIERS.md) [![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically) -[![14 Strategies](https://img.shields.io/badge/14-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship) +[![15 Strategies](https://img.shields.io/badge/15-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship) [![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
@@ -43,7 +43,7 @@ [![npm](https://img.shields.io/npm/v/omniroute?logo=npm&style=flat-square)](https://www.npmjs.com/package/omniroute) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) -[![Node](https://img.shields.io/badge/node-%E2%89%A522.22.2-brightgreen?style=flat-square)](package.json) +[![Node](https://img.shields.io/badge/node-%E2%89%A522.0.0-brightgreen?style=flat-square)](package.json) [![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)
@@ -147,7 +147,7 @@ 🔌 Every tool works
16+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config. 🧩 One endpoint
OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at /v1 and it just works. - 🛡️ Production-grade
Circuit breakers, TLS stealth, MCP (37 tools), A2A, memory, guardrails, evals. 4,690+ tests. + 🛡️ Production-grade
Circuit breakers, TLS stealth, MCP (87 tools), A2A, memory, guardrails, evals. 4,690+ tests. @@ -181,7 +181,7 @@ ▼ ┌──────────────────────────────────────────────────────────┐ │ OmniRoute — Smart Router │ -│ RTK + Caveman compression · 14 routing strategies │ +│ RTK + Caveman compression · 15 routing strategies │ │ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │ └─────────────────────────┬──────────────────────────────────┘ ┌─────────────┬────┴────────┬─────────────┐ @@ -219,7 +219,7 @@ No combo to create. Set your model to `auto` (or a variant) and OmniRoute builds ## -### 🔀 Or build your own — 14 routing strategies +### 🔀 Or build your own — 15 routing strategies | Goal | Strategy / combo | | --------------------------------------- | -------------------------------------------------- | @@ -265,10 +265,10 @@ Result: 4 layers of fallback = zero downtime | -------------------------------------- | ----------------------------------------------------------- | ------------- | | 🌐 Providers | **177** | 20–100 | | 🆓 Free providers | **50+ (11 free forever)** | 1–5 | -| 🔀 Routing strategies | **14** (priority, weighted, cost-optimized, context-relay…) | 1–3 | +| 🔀 Routing strategies | **15** (priority, weighted, cost-optimized, context-relay…) | 1–3 | | 🗜️ Token compression | **RTK + Caveman stacked (15–95%)** | None / 20–40% | -| 🧰 Built-in MCP server | **37 tools, 3 transports, 13 scopes** | Rare | -| 🤝 A2A agent protocol | **5 skills, JSON-RPC 2.0** | None | +| 🧰 Built-in MCP server | **87 tools, 3 transports, 30 scopes** | Rare | +| 🤝 A2A agent protocol | **6 skills, JSON-RPC 2.0** | None | | 🧠 Memory (FTS5 + vector) | **Yes** | Rare | | 🛡️ Guardrails (PII, injection, vision) | **Yes** | Rare | | ☁️ Cloud agents | **Codex, Devin, Jules** | None | @@ -420,9 +420,9 @@ Expose OmniRoute over **MCP** or **A2A** and any capable agent gets the keys to | Protocol | Endpoint | Use it for | | ------------------ | ----------------------------------------------- | ------------------------------------------------------ | | 🧰 **MCP (stdio)** | `omniroute --mcp` | Plug into Claude Desktop, Cursor, any MCP client | -| 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | Remote MCP — **37 tools**, 13 scopes, full audit trail | +| 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | Remote MCP — **87 tools**, 30 scopes, full audit trail | | 📡 **MCP (SSE)** | `http://localhost:20128/api/mcp/sse` | Streaming MCP transport | -| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 5 skills | +| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills | ```bash # Give Claude Code the full OmniRoute toolset over MCP: @@ -468,7 +468,7 @@ claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp
-### 📖 How it works — pipeline, architecture & savings math +### 📖 How it works — pipeline, architecture & savings math ``` Client (10,000 tok) ──▶ OmniRoute Compression (7 options) ──▶ Provider (~1,080 tok, up to 95% saved) @@ -538,7 +538,7 @@ Use these only for clients that cannot attach `Authorization: Bearer ...`. Heade
-## 📦 More install methods — Docker, source, pnpm, Arch +## 📦 More install methods — Docker, source, pnpm, Arch **🐳 Docker** @@ -595,8 +595,6 @@ podman compose --profile base up -d 📖 [Podman Guide](contrib/podman/README.md) — Quadlet setup, podman-compose, Quadlet. - -
@@ -709,11 +707,13 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
-**Routing:** 14 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection. +**Routing:** 15 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection. **Compatibility:** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0. -**Protocols:** MCP (37 tools, 3 transports, 13 scopes) · A2A (JSON-RPC 2.0, SSE, skills) · ACP · cloud agents (Codex, Devin, Jules). +**Protocols:** MCP (87 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Devin, Jules). +**Plugins:** custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD). +**Embedded services:** one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter). **Quality & Ops:** built-in **Evals** (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit. -**AI Agent Skills:** drop-in markdown manifests — point any agent at `skills/omniroute/SKILL.md`. 10 skills available. +**AI Agent Skills:** drop-in markdown manifests — point any agent at a `skills/*/SKILL.md` manifest. 43 skills available. 📖 [MCP Server](open-sse/mcp-server/README.md) · [A2A Server](src/lib/a2a/README.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) · [Features Gallery](docs/guides/FEATURES.md) @@ -751,7 +751,7 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo | OAuth token expired | Auto-refreshed; if stuck, delete + re-auth in Providers | | `unsupported_country_region_territory` | Configure proxy in Settings → Proxy | | Docker SQLite locks | Use `--stop-timeout 40` for clean WAL checkpoint | -| Node runtime errors | Use Node `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24 <25` | +| Node runtime errors | Use Node `>=22.0.0 <23` or `>=24.0.0 <27` | 🐛 **Reporting a bug?** Run `npm run system-info` and attach `system-info.txt`. 📖 [`docs/guides/TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md) @@ -795,8 +795,8 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
-- **Runtime**: Node.js 20.20.2+, 22.22.2+, or 24.x LTS (24 LTS recommended) -- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0) +- **Runtime**: Node.js 22.x or 24.x LTS (24 LTS recommended) — `>=22.0.0 <23 || >=24.0.0 <27` +- **Language**: TypeScript 6.0 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0) - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 - **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills - **Schemas**: Zod (MCP tool I/O validation, API contracts) @@ -821,61 +821,62 @@ Compression: aggressive (~50%) → double your free quota · Cost: $0/mo ### 📘 Getting Started -| Document | Description | -| ------------------------------------- | ----------------------------------------------------------------------------- | -| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | -| [Setup Guide](docs/guides/SETUP_GUIDE.md) | Full install methods, CLI tool configs, protocol setup, timeout tuning | +| Document | Description | +| ---------------------------------------------- | ----------------------------------------------------------------------------- | +| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | +| [Setup Guide](docs/guides/SETUP_GUIDE.md) | Full install methods, CLI tool configs, protocol setup, timeout tuning | | [CLI Tools Guide](docs/reference/CLI-TOOLS.md) | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot | -| [Quick Start](README.md#-quick-start) | 3-step install → connect → configure | +| [Quick Start](README.md#-quick-start) | 3-step install → connect → configure | ### 🔧 Operations & Deployment -| Document | Description | -| ---------------------------------------------------- | -------------------------------------------------------------- | -| [Docker Guide](docs/guides/DOCKER_GUIDE.md) | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags | -| [Podman Guide](contrib/podman/README.md) | Quadlet systemd integration, podman-compose, SELinux | +| Document | Description | +| -------------------------------------------------------- | -------------------------------------------------------------- | +| [Docker Guide](docs/guides/DOCKER_GUIDE.md) | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags | +| [Podman Guide](contrib/podman/README.md) | Quadlet systemd integration, podman-compose, SELinux | | [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup | | [Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage | -| [Termux Guide](docs/guides/TERMUX_GUIDE.md) | Run OmniRoute on Android via Termux | -| [PWA Guide](docs/guides/PWA_GUIDE.md) | Progressive Web App install, caching, architecture | -| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods | -| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references | +| [Termux Guide](docs/guides/TERMUX_GUIDE.md) | Run OmniRoute on Android via Termux | +| [PWA Guide](docs/guides/PWA_GUIDE.md) | Progressive Web App install, caching, architecture | +| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods | +| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references | ### 🧠 Features & Architecture -| Document | Description | -| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture, data flow, and internals | -| [Compression Guide](docs/compression/COMPRESSION_GUIDE.md) | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked | -| [RTK Compression](docs/compression/RTK_COMPRESSION.md) | Command-output compression, filters, trust, verify, raw-output recovery | -| [Compression Engines](docs/compression/COMPRESSION_ENGINES.md) | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces | -| [Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md) | JSON rule-pack schemas for Caveman and RTK filters | -| [Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring | -| [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing | -| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing | -| [Proxy Guide](docs/ops/PROXY_GUIDE.md) | 3-level proxy system, 1proxy marketplace, registry CRUD | -| [Free Tiers](docs/reference/FREE_TIERS.md) | 25+ free API providers consolidated directory | -| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots | -| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough | +| Document | Description | +| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture, data flow, and internals | +| [Compression Guide](docs/compression/COMPRESSION_GUIDE.md) | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked | +| [RTK Compression](docs/compression/RTK_COMPRESSION.md) | Command-output compression, filters, trust, verify, raw-output recovery | +| [Compression Engines](docs/compression/COMPRESSION_ENGINES.md) | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces | +| [Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md) | JSON rule-pack schemas for Caveman and RTK filters | +| [Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring | +| [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing | +| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 9-factor scoring, mode packs, self-healing | +| [Proxy Guide](docs/ops/PROXY_GUIDE.md) | 3-level proxy system, 1proxy marketplace, registry CRUD | +| [Free Tiers](docs/reference/FREE_TIERS.md) | 25+ free API providers consolidated directory | +| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots | +| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough | ### 🤖 Protocols & APIs -| Document | Description | -| ------------------------------------------- | --------------------------------------------------- | -| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples | -| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification | -| [MCP Server](open-sse/mcp-server/README.md) | 29 MCP tools, IDE configs, Python/TS/Go clients | -| [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP installation, transports, and tool reference | -| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt | -| [A2A Server Guide](docs/frameworks/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming | +| Document | Description | +| ------------------------------------------------- | --------------------------------------------------- | +| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples | +| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification | +| [MCP Server](open-sse/mcp-server/README.md) | 87 MCP tools, IDE configs, Python/TS/Go clients | +| [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP installation, transports, and tool reference | +| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt | +| [A2A Server Guide](docs/frameworks/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming | ### 📋 Project & Quality -| Document | Description | -| ---------------------------------------------- | ----------------------------------------------- | -| [Contributing](CONTRIBUTING.md) | Development setup and guidelines | -| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | -| [i18n Guide](docs/guides/I18N.md) | 40+ language support, translation workflow, RTL | +| Document | Description | +| -------------------------------------------------- | ----------------------------------------------- | +| [Contributing](CONTRIBUTING.md) | Development setup and guidelines | +| [Changelog](CHANGELOG.md) | Full per-version release history | +| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | +| [i18n Guide](docs/guides/I18N.md) | 40+ language support, translation workflow, RTL | | [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps | | [Coverage Plan](docs/ops/COVERAGE_PLAN.md) | Test coverage strategy and 4,690+ test suite | @@ -1031,7 +1032,7 @@ MIT License - see [LICENSE](LICENSE) for details. **[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community. -OmniRoute v3.8.6 · Node ≥22.22.2 · MIT License · omniroute.online +OmniRoute v3.8.24 · Node ≥22.0.0 · MIT License · omniroute.online
diff --git a/docs/AGENTROUTER.md b/docs/AGENTROUTER.md index 715e19385e..21a08589a1 100644 --- a/docs/AGENTROUTER.md +++ b/docs/AGENTROUTER.md @@ -121,15 +121,15 @@ provider. For reference, the cc-compatible bridge sends the following on each upstream request (see `open-sse/services/claudeCodeCompatible.ts`): -| Header | Value | -| ------------------------------------------- | ------------------------------------------------------------------------ | -| `Authorization` | `Bearer ` | -| `User-Agent` | `claude-cli/2.1.137 (external, sdk-cli)` | -| `anthropic-version` | `2023-06-01` | -| `anthropic-beta` | `claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24` | -| `anthropic-dangerous-direct-browser-access` | `true` | -| `x-app` | `cli` | -| `X-Stainless-*` | Various Stainless SDK headers (lang, package version, OS, arch, etc.) | +| Header | Value | +| ------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| `Authorization` | `Bearer ` | +| `User-Agent` | `claude-cli/2.1.158 (external, sdk-cli)` | +| `anthropic-version` | `2023-06-01` | +| `anthropic-beta` | `claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24,redact-thinking-2026-02-12` | +| `anthropic-dangerous-direct-browser-access` | `true` | +| `x-app` | `cli` | +| `X-Stainless-*` | Various Stainless SDK headers (lang, package version, OS, arch, etc.) | This is what allows requests to pass the upstream WAF / client whitelist. diff --git a/docs/README.md b/docs/README.md index b69e0ac9a6..4c85a157a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ --- title: "OmniRoute Documentation" -version: 3.8.2 -lastUpdated: 2026-05-13 +version: 3.8.24 +lastUpdated: 2026-06-13 --- # OmniRoute Documentation @@ -50,7 +50,7 @@ Simple guides for using OmniRoute — no technical background needed. Technical documentation for developers and contributors. -## architecture/ +## reference/ Lookup material — API surface, environment variables, CLI flags, provider catalog. diff --git a/docs/SUBMIT_PR.md b/docs/SUBMIT_PR.md index fbda682bb6..73c1aa88c3 100644 --- a/docs/SUBMIT_PR.md +++ b/docs/SUBMIT_PR.md @@ -22,18 +22,18 @@ npm install ## 2 — Sync with the current release branch -PRs go to **`release/v3.8.3`**, not `main`. +PRs go to the **current release branch** — `release/v3.8.24` at the time of writing. Always target the latest `release/v*` branch (the repository's active development branch), never `main`. Check the repo's branch list or `CONTRIBUTING.md` if a newer release cycle has opened. ```bash git fetch upstream -git checkout -b fix/your-description upstream/release/v3.8.3 +git checkout -b fix/your-description upstream/release/v3.8.24 ``` If you already made your changes on another branch, rebase on top of it: ```bash git fetch upstream -git rebase upstream/release/v3.8.3 +git rebase upstream/release/v3.8.24 ``` --- @@ -59,7 +59,7 @@ Examples: `fix/codex-token-refresh`, `feat/provider-xyz`, `docs/update-readme` npm run lint # must pass (0 errors) npm run typecheck:core # must pass npm run test:unit # must pass -npm run test:coverage # coverage gate: 75/75/75/70 +npm run test:coverage # coverage gate: 60/60/60/60 (statements/lines/functions/branches) ``` If you changed production code in `src/`, `open-sse/`, `electron/`, or `bin/`, include or update tests in the same PR. @@ -87,7 +87,7 @@ Common scopes: `api`, `dashboard`, `db`, `sse`, `oauth`, `providers`, `combo`, ` git push -u origin fix/your-description ``` -Then open a PR on GitHub targeting **`diegosouzapw/OmniRoute`** → **`release/v3.8.3`**. +Then open a PR on GitHub targeting **`diegosouzapw/OmniRoute`** → **`release/v3.8.24`**. PR description checklist: @@ -105,7 +105,7 @@ PR description checklist: ```bash git fetch upstream -git rebase upstream/release/v3.8.3 +git rebase upstream/release/v3.8.24 git push --force-with-lease ```