pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-07-26 09:52:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(release): v3.8.0 documentation overhaul (FIX 1-9)

Browse Source 
Root docs
- GEMINI.md: remove plaintext credential (Hard Rule 1) and refresh references
- CLAUDE.md: update coverage gate to 75/75/75/70, add module counts for v3.8.0
- SECURITY.md: add Supported Versions section
- AGENTS.md: refresh counts (177 providers, 37 MCP tools, 14 strategies, 5 A2A skills, 3 cloud agents) and module map
- CONTRIBUTING.md: align coverage gate, Node range, conventional-commit scopes
- CODE_OF_CONDUCT.md: refresh contact
- llm.txt: refresh Node range, provider/tool/strategy counts, add v3.8.0 highlights and documentation index
- Tuto_Qdrant.MD -> Tuto_Qdrant.md (rename + dormant-integration status banner)

i18n strict mirrors
- docs/i18n/<40 locales>/llm.txt: refresh body to match root (preserving locale header + flags line + --- separator)

Cross-references
- docs/MEMORY.md, docs/REPOSITORY_MAP.md: update Tuto_Qdrant.md path and note dormant status
- Cleanup: remove .issues/feat-batch-delete-provider-accounts.md and docs/archive/RFC-AUTO-ASSESSMENT-DRAFT.md (already absent)

Agent workflows / skills / commands
- .claude/commands/*-cc.md, .agents/workflows/*-ag.md, .agents/skills/*/SKILL.md:
  - Replace ghost tools: search_web -> WebSearch, read_url_content -> WebFetch,
    view_file -> Read, write_to_file -> Write
  - notify_user -> mandatory stop checkpoints
  - version-bump / generate-release: 2.x.y -> 3.x.y, expand docs table to 28 entries,
    mark /update-docs and /update-i18n as deprecated
  - capture-release-evidences / review-discussions: tool-mapping notes for
    browser_subagent (mcp__claude-in-chrome__* and gh CLI)
  - review-prs: align coverage thresholds (>=75/>=70, ~82% measured)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
diegosouzapw
2026-05-13 08:23:02 -03:00
parent 26d6b7a76f
commit 918a539baf
70 changed files with 3090 additions and 2113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.agents/skills/capture-release-evidences/SKILL.md
View File

@@ -1,11 +1,13 @@
---
name: capture-release-evidences-cx
description: Automatically run the browser_subagent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
---
# Capture Release Evidences Workflow
Use this workflow to automatically drive the `browser_subagent` to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
> **Tool mapping note (v3.8):** The `browser_subagent` tool referenced below is specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps remain the same regardless of the browser-automation surface in use.
## Prerequisites
@@ -36,7 +38,7 @@ _(Note: The `browser_subagent` automatically creates a WebP recording named by t
### 3. Generate Report Artifact
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `write_to_file` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
### Example Invocation

33
.agents/skills/generate-release/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: generate-release-cx
description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
---
# Generate Release Workflow
@@ -12,10 +12,10 @@ Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for use
- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
- When the workflow says `notify_user` or `BlockedOnUser: true`, present the report/status in the final response and stop. Do not continue into the next phase until the user explicitly approves.
> **VERSION RULE: Always use PATCH bumps (2.x.y → 2.x.y+1)**
> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
> NEVER use `npm version minor` or `npm version major`.
> Always use: `npm version patch --no-git-tag-version`
> The threshold rule: when `y` reaches 10, bump to `2.(x+1).0` — e.g. `2.1.10` → `2.2.0`.
> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
@@ -55,7 +55,7 @@ Before creating the release, you must ensure the codebase and supply chain are s
### 1. Create release branch
```bash
git checkout -b release/v2.x.y
git checkout -b release/v3.x.y
```
### 2. Determine and sync version
@@ -78,19 +78,19 @@ grep '"version"' package.json
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v2.x.y` always contains both code changes and the version bump together.
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
### 3. Regenerate lock file (REQUIRED after version bump)
@@ -151,11 +151,12 @@ npm install
### 6. Update README.md and i18n docs
Run `/update-docs` workflow steps to:
Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
- Update feature table rows in `README.md`
- Sync changes to all 29 language `docs/i18n/*/README.md` files
- Update `docs/FEATURES.md` if Settings section changed
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
### 7. Run tests
@@ -173,8 +174,8 @@ All tests must pass before creating the PR.
```bash
git add -A
git commit -m "chore(release): v2.x.y — summary of changes"
git push origin release/v2.x.y
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
```
### 9. Open PR to main
@@ -206,7 +207,7 @@ gh pr create \
### 10. 🛑 STOP — Notify User & Await PR Confirmation
**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Inform the user:
@@ -339,7 +340,7 @@ If a workflow fails:
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v2.x.y`
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
### 20. Preserve release branch
@@ -351,7 +352,7 @@ If a workflow fails:
## Notes
- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump

12
.agents/skills/implement-features/SKILL.md
View File

@@ -208,22 +208,22 @@ For each viable feature, perform systematic research:
**Step 1 — Web search for similar implementations:**
```
search_web("how to implement <feature description> in <tech stack>")
search_web("<feature keyword> implementation nextjs typescript 2025 2026")
search_web("<feature keyword> open source library npm")
WebSearch("how to implement <feature description> in <tech stack>")
WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
WebSearch("<feature keyword> open source library npm")
```
**Step 2 — Find reference Git repositories:**
```
search_web("site:github.com <feature keyword> <tech stack> stars:>100")
search_web("github <feature keyword> implementation recently updated 2026")
WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
WebSearch("github <feature keyword> implementation recently updated 2026")
```
- Find **up to 10 relevant repositories**, sorted by most recently updated.
- For each repository:
- Note the repo URL, star count, last commit date
- Read its README and relevant source files via `read_url_content`
- Read its README and relevant source files via `WebFetch`
- Extract the architectural approach, patterns used, and key code snippets
**Step 3 — Read API docs and standards:**

4
.agents/skills/review-discussions/SKILL.md
View File

@@ -9,6 +9,8 @@ description: Read all open GitHub Discussions, summarize them, respond to pendin
This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
> **Tool mapping note (v3.8):** Where steps below say `browser_subagent`, modern runtimes should substitute with the `gh` CLI — `gh api graphql` for reading discussions and mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
## Codex Execution Notes
- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads and GitHub/browser fetches.
@@ -25,7 +27,7 @@ This workflow reads all open GitHub Discussions, generates a categorized summary
### 2. Fetch All Open Discussions
- Use `read_url_content` to fetch `https://github.com/<owner>/<repo>/discussions`
- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
- For each discussion, fetch the individual page to read the full content and all comments/replies

6
.agents/skills/review-prs/SKILL.md
View File

@@ -91,7 +91,7 @@ If already on a `release/vX.Y.Z` branch, continue working there.
- For each PR number, run:
`gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
- Then read each diff file with `view_file`.
- Then read each diff file with the appropriate file-read tool (`Read` in Claude Code; equivalent in your agent runtime).
- For each open PR, collect:
- PR number, title, author, branch, number of commits, date
@@ -186,7 +186,7 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
### 6. Present to User
- Show the report via `notify_user` with `BlockedOnUser: true`
- Show the report in the final response and stop. Mark this as a blocking checkpoint awaiting explicit user approval before continuing.
- Wait for user decision:
- **Approved** → Proceed to step 7
- **Approved with changes** → Implement the fixes and corrections before merging
@@ -259,7 +259,7 @@ After processing all approved PRs:
- If more PRs remain, go back to step 7
- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
- Run **test coverage** to verify all metrics stay above 85%:
- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
```bash
npm run test:coverage
```

32
.agents/skills/version-bump/SKILL.md
View File

@@ -215,20 +215,34 @@ For each file below, read the current content and determine if the CHANGELOG ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
| File | When to update |
| -------------------------------- | --------------------------------------------------- |
| -------------------------------- | ------------------------------------------------------------------ |
| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |
| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |
| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |
| `docs/FEATURES.md` | New features, removed features, changed settings |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |
| `docs/VM_DEPLOYMENT_GUIDE.md` | Deployment changes, new env vars |
| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |
| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |
| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |
| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |
| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |
| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |
| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |
| `docs/EVALS.md` | Evaluation framework changes, new evaluators |
| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |
| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |
| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |
| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |
| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |
| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |
| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes |
| `docs/RELEASE_CHECKLIST.md` | Process changes |
| `docs/COVERAGE_PLAN.md` | Test changes |
| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |
| `docs/openapi.yaml` | Already updated in step 7 |
**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.
@@ -316,7 +330,7 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy
## Notes
- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
- This workflow does **NOT** update `docs/i18n/` translations. Use `/update-i18n` separately after committing.
- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — there is no `/update-i18n` workflow shipped in this repo.
- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.

8
.agents/workflows/capture-release-evidences-ag.md
View File

@@ -1,10 +1,12 @@
---
description: Automatically run the browser_subagent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
---
# Capture Release Evidences Workflow
Use this workflow to automatically drive the `browser_subagent` to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
> **Tool mapping note (v3.8):** The `browser_subagent` tool referenced below is specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps remain the same regardless of the browser-automation surface in use.
## Prerequisites
@@ -35,7 +37,7 @@ _(Note: The `browser_subagent` automatically creates a WebP recording named by t
### 3. Generate Report Artifact
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `write_to_file` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
### Example Invocation

33
.agents/workflows/generate-release-ag.md
View File

@@ -1,15 +1,15 @@
---
description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
---
# Generate Release Workflow
Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
> **VERSION RULE: Always use PATCH bumps (2.x.y → 2.x.y+1)**
> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
> NEVER use `npm version minor` or `npm version major`.
> Always use: `npm version patch --no-git-tag-version`
> The threshold rule: when `y` reaches 10, bump to `2.(x+1).0` — e.g. `2.1.10` → `2.2.0`.
> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
@@ -49,7 +49,7 @@ Before creating the release, you must ensure the codebase and supply chain are s
### 1. Create release branch
```bash
git checkout -b release/v2.x.y
git checkout -b release/v3.x.y
```
### 2. Determine and sync version
@@ -72,19 +72,19 @@ grep '"version"' package.json
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v2.x.y` always contains both code changes and the version bump together.
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
### 3. Regenerate lock file (REQUIRED after version bump)
@@ -145,11 +145,12 @@ npm install
### 6. Update README.md and i18n docs
Run `/update-docs` workflow steps to:
Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
- Update feature table rows in `README.md`
- Sync changes to all 29 language `docs/i18n/*/README.md` files
- Update `docs/FEATURES.md` if Settings section changed
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
### 7. Run tests
@@ -167,8 +168,8 @@ All tests must pass before creating the PR.
```bash
git add -A
git commit -m "chore(release): v2.x.y — summary of changes"
git push origin release/v2.x.y
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
```
### 9. Open PR to main
@@ -200,7 +201,7 @@ gh pr create \
### 10. 🛑 STOP — Notify User & Await PR Confirmation
**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Inform the user:
@@ -333,7 +334,7 @@ If a workflow fails:
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v2.x.y`
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
### 20. Preserve release branch
@@ -345,7 +346,7 @@ If a workflow fails:
## Notes
- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump

12
.agents/workflows/implement-features-ag.md
View File

@@ -201,22 +201,22 @@ For each viable feature, perform systematic research:
**Step 1 — Web search for similar implementations:**
```
search_web("how to implement <feature description> in <tech stack>")
search_web("<feature keyword> implementation nextjs typescript 2025 2026")
search_web("<feature keyword> open source library npm")
WebSearch("how to implement <feature description> in <tech stack>")
WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
WebSearch("<feature keyword> open source library npm")
```
**Step 2 — Find reference Git repositories:**
```
search_web("site:github.com <feature keyword> <tech stack> stars:>100")
search_web("github <feature keyword> implementation recently updated 2026")
WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
WebSearch("github <feature keyword> implementation recently updated 2026")
```
- Find **up to 10 relevant repositories**, sorted by most recently updated.
- For each repository:
- Note the repo URL, star count, last commit date
- Read its README and relevant source files via `read_url_content`
- Read its README and relevant source files via `WebFetch`
- Extract the architectural approach, patterns used, and key code snippets
**Step 3 — Read API docs and standards:**

4
.agents/workflows/review-discussions-ag.md
View File

@@ -8,6 +8,8 @@ description: Read all open GitHub Discussions, summarize them, respond to pendin
This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
> **Tool mapping note (v3.8):** Where steps below say `browser_subagent`, in modern Claude Code substitute with the `gh` CLI via Bash — `gh api graphql` for reading discussions and mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
// turbo-all
## Steps
@@ -19,7 +21,7 @@ This workflow reads all open GitHub Discussions, generates a categorized summary
### 2. Fetch All Open Discussions
- Use `read_url_content` to fetch `https://github.com/<owner>/<repo>/discussions`
- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
- For each discussion, fetch the individual page to read the full content and all comments/replies

6
.agents/workflows/review-prs-ag.md
View File

@@ -79,7 +79,7 @@ If already on a `release/vX.Y.Z` branch, continue working there.
- For each PR number, run:
`gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
- Then read each diff file with `view_file`.
- Then read each diff file with the appropriate file-read tool (`Read` in Claude Code; equivalent in your agent runtime).
- For each open PR, collect:
- PR number, title, author, branch, number of commits, date
@@ -174,7 +174,7 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
### 6. Present to User
- Show the report via `notify_user` with `BlockedOnUser: true`
- Show the report in the final response and stop. Mark this as a blocking checkpoint awaiting explicit user approval.
- Wait for user decision:
- **Approved** → Proceed to step 7
- **Approved with changes** → Implement the fixes and corrections before merging
@@ -247,7 +247,7 @@ After processing all approved PRs:
- If more PRs remain, go back to step 7
- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
- Run **test coverage** to verify all metrics stay above 85%:
- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
```bash
npm run test:coverage
```

32
.agents/workflows/version-bump-ag.md
View File

@@ -209,20 +209,34 @@ For each file below, read the current content and determine if the CHANGELOG ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
| File | When to update |
| -------------------------------- | --------------------------------------------------- |
| -------------------------------- | ------------------------------------------------------------------ |
| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |
| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |
| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |
| `docs/FEATURES.md` | New features, removed features, changed settings |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |
| `docs/VM_DEPLOYMENT_GUIDE.md` | Deployment changes, new env vars |
| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |
| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |
| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |
| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |
| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |
| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |
| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |
| `docs/EVALS.md` | Evaluation framework changes, new evaluators |
| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |
| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |
| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |
| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |
| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |
| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |
| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes |
| `docs/RELEASE_CHECKLIST.md` | Process changes |
| `docs/COVERAGE_PLAN.md` | Test changes |
| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |
| `docs/openapi.yaml` | Already updated in step 7 |
**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.
@@ -310,7 +324,7 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy
## Notes
- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
- This workflow does **NOT** update `docs/i18n/` translations. Use `/update-i18n` separately after committing.
- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — there is no `/update-i18n` workflow shipped in this repo.
- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.

8
.claude/commands/capture-release-evidences-cc.md
View File

@@ -1,10 +1,12 @@
---
description: Automatically run the browser_subagent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
description: Automatically run a browser-automation agent to visually validate all new UI features from the current release and capture evidence WebP recordings of the changes.
---
# Capture Release Evidences Workflow
Use this workflow to automatically drive the `browser_subagent` to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
Use this workflow to automatically drive a browser-automation agent to explore the newly deployed or locally running application and record evidence of the UI changes introduced in the latest release.
> **Tool mapping note (v3.8):** This workflow references a `browser_subagent` tool that was specific to an earlier agent runtime. In Claude Code, substitute with the available browser MCP tools (e.g. `mcp__claude-in-chrome__*`) for navigation/screenshots, plus the `Write` tool for saving artifacts. The high-level steps below remain the same regardless of which browser-automation surface is used.
## Prerequisites
@@ -35,7 +37,7 @@ _(Note: The `browser_subagent` automatically creates a WebP recording named by t
### 3. Generate Report Artifact
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `write_to_file` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
After the `browser_subagent` finishes its sessions, generate a final Markdown artifact (using `Write` and `IsArtifact=true`) to present the recordings inline to the user using the `![caption](/absolute/path/to/media.webp)` syntax.
### Example Invocation

33
.claude/commands/generate-release-cc.md
View File

@@ -1,15 +1,15 @@
---
description: Create a new release, bump version up to 1.x.10 threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .10 patch threshold, update changelog, and manage Pull Requests
---
# Generate Release Workflow
Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
> **VERSION RULE: Always use PATCH bumps (2.x.y → 2.x.y+1)**
> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
> NEVER use `npm version minor` or `npm version major`.
> Always use: `npm version patch --no-git-tag-version`
> The threshold rule: when `y` reaches 10, bump to `2.(x+1).0` — e.g. `2.1.10` → `2.2.0`.
> The threshold rule: when `y` reaches 10, bump to `3.(x+1).0` — e.g. `3.8.10` → `3.9.0`.
> **🔴 SINGLE BRANCH RULE**: The `release/vX.Y.Z` branch is the **ONLY** development branch for the entire release cycle. ALL work — bug fixes, feature implementations, PR integrations, issue resolutions — MUST be committed directly on this branch. Never create separate `fix/`, `feat/`, or topic branches. When running `/resolve-issues`, `/implement-features`, or `/review-prs`, always work on the current release branch.
@@ -49,7 +49,7 @@ Before creating the release, you must ensure the codebase and supply chain are s
### 1. Create release branch
```bash
git checkout -b release/v2.x.y
git checkout -b release/v3.x.y
```
### 2. Determine and sync version
@@ -72,19 +72,19 @@ grep '"version"' package.json
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v2.x.y — all changes in ONE commit"`
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v2.x.y` always contains both code changes and the version bump together.
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
### 3. Regenerate lock file (REQUIRED after version bump)
@@ -145,11 +145,12 @@ npm install
### 6. Update README.md and i18n docs
Run `/update-docs` workflow steps to:
Manually perform these documentation updates (there is no `/update-docs` slash command — it was deprecated in v3.8):
- Update feature table rows in `README.md`
- Sync changes to all 29 language `docs/i18n/*/README.md` files
- Update `docs/FEATURES.md` if Settings section changed
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed (e.g. `docs/MCP-SERVER.md` when MCP tools change)
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
### 7. Run tests
@@ -167,8 +168,8 @@ All tests must pass before creating the PR.
```bash
git add -A
git commit -m "chore(release): v2.x.y — summary of changes"
git push origin release/v2.x.y
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
```
### 9. Open PR to main
@@ -200,7 +201,7 @@ gh pr create \
### 10. 🛑 STOP — Notify User & Await PR Confirmation
**This is a mandatory stop point.** Use `notify_user` with `BlockedOnUser: true`:
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Inform the user:
@@ -333,7 +334,7 @@ If a workflow fails:
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v2.x.y`
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
### 20. Preserve release branch
@@ -345,7 +346,7 @@ If a workflow fails:
## Notes
- Always run `/update-docs` BEFORE this workflow (ensures CHANGELOG and README are current)
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` slash command anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump

12
.claude/commands/implement-features-cc.md
View File

@@ -201,22 +201,22 @@ For each viable feature, perform systematic research:
**Step 1 — Web search for similar implementations:**
```
search_web("how to implement <feature description> in <tech stack>")
search_web("<feature keyword> implementation nextjs typescript 2025 2026")
search_web("<feature keyword> open source library npm")
WebSearch("how to implement <feature description> in <tech stack>")
WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
WebSearch("<feature keyword> open source library npm")
```
**Step 2 — Find reference Git repositories:**
```
search_web("site:github.com <feature keyword> <tech stack> stars:>100")
search_web("github <feature keyword> implementation recently updated 2026")
WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
WebSearch("github <feature keyword> implementation recently updated 2026")
```
- Find **up to 10 relevant repositories**, sorted by most recently updated.
- For each repository:
- Note the repo URL, star count, last commit date
- Read its README and relevant source files via `read_url_content`
- Read its README and relevant source files via `WebFetch`
- Extract the architectural approach, patterns used, and key code snippets
**Step 3 — Read API docs and standards:**

4
.claude/commands/review-discussions-cc.md
View File

@@ -8,6 +8,8 @@ description: Read all open GitHub Discussions, summarize them, respond to pendin
This workflow reads all open GitHub Discussions, generates a categorized summary, identifies which ones need a response, drafts and posts replies, and optionally creates issues from actionable feature requests. It follows the same flow used for Issues but adapted for the Discussions forum.
> **Tool mapping note (v3.8):** Where steps below say `browser_subagent` (an earlier-runtime tool), in Claude Code use the `gh` CLI via the `Bash` tool — `gh api graphql` for reading discussions and `gh api graphql -F query=...` mutations for posting comments. `WebFetch` is acceptable for read-only HTML scraping when GraphQL is overkill, but prefer `gh` for any write actions.
// turbo-all
## Steps
@@ -19,7 +21,7 @@ This workflow reads all open GitHub Discussions, generates a categorized summary
### 2. Fetch All Open Discussions
- Use `read_url_content` to fetch `https://github.com/<owner>/<repo>/discussions`
- Use `WebFetch` to fetch `https://github.com/<owner>/<repo>/discussions`
- Parse the discussion list to get all discussion titles, IDs, authors, categories, and dates
- For each discussion, fetch the individual page to read the full content and all comments/replies

6
.claude/commands/review-prs-cc.md
View File

@@ -79,7 +79,7 @@ If already on a `release/vX.Y.Z` branch, continue working there.
- For each PR number, run:
`gh pr diff <NUMBER> --repo <owner>/<repo> > /tmp/pr<NUMBER>.diff`
- Then read each diff file with `view_file`.
- Then read each diff file with the `Read` tool.
- For each open PR, collect:
- PR number, title, author, branch, number of commits, date
@@ -174,7 +174,7 @@ Perform a **global impact assessment** to verify whether the PR changes are comp
### 6. Present to User
- Show the report via `notify_user` with `BlockedOnUser: true`
- Show the report in the final response and stop. This is a mandatory checkpoint awaiting explicit user approval before continuing.
- Wait for user decision:
- **Approved** → Proceed to step 7
- **Approved with changes** → Implement the fixes and corrections before merging
@@ -247,7 +247,7 @@ After processing all approved PRs:
- If more PRs remain, go back to step 7
- When all PRs are processed, **update CHANGELOG.md** on the release branch with all new entries
- Run **test coverage** to verify all metrics stay above 85%:
- Run **test coverage** to verify the gate (≥75% statements/lines/functions, ≥70% branches — measured ~82%):
```bash
npm run test:coverage
```

32
.claude/commands/version-bump-cc.md
View File

@@ -209,20 +209,34 @@ For each file below, read the current content and determine if the CHANGELOG ent
For each file in `docs/` (excluding `docs/i18n/`), review if CHANGELOG changes affect it:
| File | When to update |
| -------------------------------- | --------------------------------------------------- |
| -------------------------------- | ------------------------------------------------------------------ |
| `docs/API_REFERENCE.md` | New API endpoints, changed request/response formats |
| `docs/ARCHITECTURE.md` | New modules, new services, changed data flow |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes, module reorganization |
| `docs/REPOSITORY_MAP.md` | New folders / files / one-line descriptions |
| `docs/CLI-TOOLS.md` | New CLI tool integrations, config format changes |
| `docs/FEATURES.md` | New features, removed features, changed settings |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/USER_GUIDE.md` | UX changes, new dashboard pages, settings changes |
| `docs/VM_DEPLOYMENT_GUIDE.md` | Deployment changes, new env vars |
| `docs/PROVIDER_REFERENCE.md` | New providers (regenerate via `scripts/gen-provider-reference.ts`) |
| `docs/MCP-SERVER.md` | New MCP tools, changed tool signatures, scope changes |
| `docs/A2A-SERVER.md` | New A2A skills, protocol changes |
| `docs/AGENT_PROTOCOLS_GUIDE.md` | New external agent protocols supported |
| `docs/CLOUD_AGENT.md` | Cloud agent additions (codex-cloud, devin, jules) or API changes |
| `docs/AUTHZ_GUIDE.md` | New route classifications, policy changes |
| `docs/GUARDRAILS.md` | New guardrails registered, priority/order changes |
| `docs/COMPLIANCE.md` | Audit log / retention / no-log policy changes |
| `docs/SKILLS.md` | Skill framework / registry / built-in skill changes |
| `docs/MEMORY.md` | Memory pipeline / extraction / injection / Qdrant changes |
| `docs/EVALS.md` | Evaluation framework changes, new evaluators |
| `docs/WEBHOOKS.md` | New webhook events, payload schema changes |
| `docs/REASONING_REPLAY.md` | Reasoning capture/replay pipeline changes |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies, scoring weight changes |
| `docs/RESILIENCE_GUIDE.md` | Circuit breaker / cooldown / lockout behavior changes |
| `docs/STEALTH_GUIDE.md` | TLS / CLI fingerprint changes |
| `docs/TUNNELS_GUIDE.md` | Cloudflare tunnel feature changes |
| `docs/ELECTRON_GUIDE.md` | Electron build / signing / packaging changes |
| `docs/TROUBLESHOOTING.md` | New known issues, resolved problems |
| `docs/AUTO-COMBO.md` | Routing changes, new strategies |
| `docs/CODEBASE_DOCUMENTATION.md` | New files, architectural changes |
| `docs/RELEASE_CHECKLIST.md` | Process changes |
| `docs/COVERAGE_PLAN.md` | Test changes |
| `docs/COVERAGE_PLAN.md` | Coverage gate adjustments, target metrics |
| `docs/openapi.yaml` | Already updated in step 7 |
**Only update files where the CHANGELOG entries directly affect the documented content.** Do NOT update files just to bump a version number — only when the documented behavior, features, or architecture has actually changed.
@@ -310,7 +324,7 @@ git commit -m "chore(release): bump to v$VERSION — changelog, docs, version sy
## Notes
- This workflow does **NOT** create tags, releases, or deploy. Use `/generate-release` for the full release cycle after this.
- This workflow does **NOT** update `docs/i18n/` translations. Use `/update-i18n` separately after committing.
- This workflow does **NOT** update `docs/i18n/` translations. Translation updates are handled manually or via release tooling — the `/update-i18n` command does not currently exist as a Claude Code slash command.
- The CHANGELOG generation is based on git commits since the last tag. If there are no new commits, the workflow should inform the user and stop.
- Always verify the generated CHANGELOG entries make sense — raw commit messages may need rewriting for clarity.
- If the version was already bumped (e.g. you're on a `release/vX.Y.Z` branch), skip the `npm version` step and use the existing version.

332
.issues/feat-batch-delete-provider-accounts.md
View File

@@ -1,332 +0,0 @@
# Feature Proposal: Batch Delete Provider Accounts
## Summary
Add **batch delete** functionality for provider accounts (connections) in the provider detail page (`/dashboard/providers/[id]`). Users select multiple accounts via checkboxes and delete them in a single action, replacing the current one-by-one delete workflow.
## Problem Statement
Users managing multiple provider accounts (e.g., 20+ API keys or OAuth connections) have to delete accounts individually. Each deletion requires:
1. Finding the account
2. Clicking the delete button
3. Confirming via browser `confirm()` dialog
4. Waiting for the API call
5. Repeating for every account
This is:
- **Time-consuming**: O(n) confirm dialogs and API calls for n accounts
- **Error-prone**: Easy to accidentally click the wrong account
- **Tedious**: No way to quickly clean up stale or duplicate accounts
## Solution
Add a checkbox-based selection UI to the provider connections list:
```
┌────────────────────────────────────────────────────────────────┐
│ [x] Account #1 (kiro-prod) [Delete Selected (3)] │
│ [x] Account #2 (kiro-staging) │
│ [ ] Account #3 (kiro-backup) │
└────────────────────────────────────────────────────────────────┘
```
## Detailed PR Specification
### Files to Modify
| File | Change |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `src/app/(dashboard)/dashboard/providers/[id]/page.tsx` | Add batch delete state, select-all + per-row checkboxes, batch delete handler |
| `src/app/api/providers/route.ts` | Add `DELETE /api/providers` with `POST` body `ids: string[]` for batch delete |
| `src/lib/db/providers.ts` | Add `deleteProviderConnections(ids: string[])` batch DB function |
| `src/i18n/messages/en.json` | Add i18n keys: `batchDeleteSelected`, `batchDeleteConfirm`, `batchDeleteSuccess` |
| `src/i18n/messages/*.json` | Add i18n keys to all locale files |
| `tests/unit/db-providers-crud.test.ts` | Add unit tests for batch delete DB function |
| `tests/integration/api-routes-critical.test.ts` | Add integration test for batch delete API endpoint |
### 1. DB Layer (`src/lib/db/providers.ts`)
```typescript
export async function deleteProviderConnections(ids: string[]): Promise<number> {
const db = getDbInstance() as unknown as DbLike;
if (ids.length === 0) return 0;
// Delete quota snapshots for each connection first
const deleteSnapshots = db.prepare("DELETE FROM quota_snapshots WHERE connection_id = ?");
for (const id of ids) {
deleteSnapshots.run(id);
}
// Batch delete connections
const placeholders = ids.map(() => "?").join(",");
const result = db
.prepare(`DELETE FROM provider_connections WHERE id IN (${placeholders})`)
.run(...ids);
backupDbFile("pre-write");
invalidateDbCache("connections");
return result.changes ?? 0;
}
```
### 2. API Route (`src/app/api/providers/route.ts`)
Add a new route handler for batch delete. The existing `/api/providers/[id]` only handles single-id operations. The main providers route file (`/api/providers/route.ts`) should be extended:
```typescript
// DELETE /api/providers — Batch delete connections
// Body: { ids: string[] }
export async function DELETE(request: Request) {
const authError = await requireManagementAuth(request);
if (authError) return authError;
let body: { ids?: string[] };
try {
body = await request.json();
} catch {
return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
}
if (!Array.isArray(body.ids) || body.ids.length === 0) {
return NextResponse.json(
{ error: "ids must be a non-empty array of connection IDs" },
{ status: 400 }
);
}
if (body.ids.length > 100) {
return NextResponse.json(
{ error: "Cannot delete more than 100 connections at once" },
{ status: 400 }
);
}
try {
const deleted = await deleteProviderConnections(body.ids);
await syncToCloudIfEnabled();
logAuditEvent({
action: "provider.credentials.batch_revoked",
actor: "admin",
resourceType: "provider_credentials",
status: "success",
metadata: { count: deleted, ids: body.ids },
});
return NextResponse.json({ message: `Deleted ${deleted} connection(s)`, deleted });
} catch (error) {
console.log("Error batch deleting connections:", error);
return NextResponse.json({ error: "Failed to batch delete connections" }, { status: 500 });
}
}
```
### 3. UI Layer (`src/app/(dashboard)/dashboard/providers/[id]/page.tsx`)
#### New State Variables
```typescript
// Batch selection state
const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
const [batchDeleting, setBatchDeleting] = useState(false);
```
#### New Functions
```typescript
const handleToggleSelectAll = useCallback(() => {
setSelectedIds((prev) =>
prev.size === connections.length ? new Set() : new Set(connections.map((c) => c.id))
);
}, [connections]);
const handleToggleSelectOne = useCallback((id: string) => {
setSelectedIds((prev) => {
const next = new Set(prev);
if (next.has(id)) next.delete(id);
else next.add(id);
return next;
});
}, []);
const handleBatchDelete = async () => {
if (selectedIds.size === 0) return;
if (!confirm(t("batchDeleteConfirm", { count: selectedIds.size }))) return;
setBatchDeleting(true);
try {
const res = await fetch("/api/providers", {
method: "DELETE",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ids: Array.from(selectedIds) }),
});
if (res.ok) {
setSelectedIds(new Set());
await fetchConnections();
notify.success(t("batchDeleteSuccess", { count: selectedIds.size }));
} else {
const data = await res.json();
notify.error(data.error || "Batch delete failed");
}
} catch (error) {
notify.error("Network error during batch delete");
} finally {
setBatchDeleting(false);
}
};
```
#### Per-Row Checkbox (inside `ConnectionRow`)
Add a checkbox as the first element of each row:
```tsx
// In ConnectionRow interface, add:
interface ConnectionRowProps {
isSelected?: boolean;
onToggleSelect?: () => void;
// ... existing props
}
// In ConnectionRow render, before priority arrows:
<div className="flex items-center gap-3 flex-1 min-w-0">
<input
type="checkbox"
checked={isSelected}
onChange={onToggleSelect}
className="w-4 h-4 rounded border-border text-primary focus:ring-primary/30 cursor-pointer"
/>
{/* Priority arrows */}
...
```
#### Header Row (above connections list)
```tsx
<div className="flex items-center justify-between px-3 py-2 bg-muted/50 rounded-t-lg border border-b-0 border-border">
<label className="flex items-center gap-2 cursor-pointer select-none">
<input
type="checkbox"
checked={selectedIds.size === connections.length && connections.length > 0}
ref={(el) => {
if (el) el.indeterminate = selectedIds.size > 0 && selectedIds.size < connections.length;
}}
onChange={handleToggleSelectAll}
className="w-4 h-4 rounded border-border text-primary focus:ring-primary/30"
/>
<span className="text-sm font-medium text-text-muted">
{selectedIds.size > 0 ? `${selectedIds.size} selected` : `${connections.length} accounts`}
</span>
</label>
{selectedIds.size > 0 && (
<Button
variant="destructive"
size="sm"
icon="delete"
loading={batchDeleting}
onClick={handleBatchDelete}
>
{t("batchDeleteSelected", { count: selectedIds.size })}
</Button>
)}
</div>
```
### 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

89
AGENTS.md
View File

@@ -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

72
CLAUDE.md
View File

@@ -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
```
@@ -38,16 +38,16 @@ 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) |
| 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/` | 29 tools, 3 transports, 10 scopes |
| 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 |
@@ -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 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.

31
CODE_OF_CONDUCT.md
View File

@@ -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
<https://github.com/diegosouzapw/OmniRoute/security/advisories/new>
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
@@ -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).

4
CONTRIBUTING.md
View File

@@ -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

43
GEMINI.md
View File

@@ -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/<area>.md` |
| Per-area deep dives | `docs/SKILLS.md`, `docs/MEMORY.md`, `docs/EVALS.md`, `docs/GUARDRAILS.md`, `docs/COMPLIANCE.md`, `docs/CLOUD_AGENT.md`, `docs/MCP-SERVER.md`, `docs/A2A-SERVER.md`, `docs/AUTHZ_GUIDE.md`, `docs/RESILIENCE_GUIDE.md`, `docs/AUTO-COMBO.md`, `docs/WEBHOOKS.md`, `docs/REASONING_REPLAY.md`, `docs/STEALTH_GUIDE.md`, `docs/TUNNELS_GUIDE.md`, `docs/ELECTRON_GUIDE.md`, `docs/PROVIDER_REFERENCE.md` |
| Release flow | `docs/RELEASE_CHECKLIST.md` |
## 4. Local development access
The dashboard is reachable at the operator's chosen URL/port (default `http://localhost:20128`). Credentials are operator-specific:
- **Initial admin password** is read from the `INITIAL_PASSWORD` env var on first install (defaults to `CHANGEME` in `.env.example`; rotate immediately after first login).
- **Local VPS / shared dev environments**: ask the operator for the URL and current credentials — they live in their personal vault, NOT in this repo.
> Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.

59
SECURITY.md
View File

@@ -20,9 +20,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
| Version | Support Status |
| ------- | -------------- |
| 3.6.x | ✅ Active |
| 3.5.x | ✅ Security |
| < 3.5.0 | ❌ Unsupported |
| 3.8.x | ✅ Active |
| 3.7.x | ✅ Security |
| < 3.7.0 | ❌ Unsupported |
---
@@ -31,19 +31,22 @@ If you discover a security vulnerability in OmniRoute, please report it responsi
OmniRoute implements a multi-layered security model:
```
Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer → Rate Limiter → Circuit Breaker → Provider
Request → CORS → Authz pipeline (classify → policies → enforce)
→ Guardrails (PII masker, prompt injection, vision bridge)
→ Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider
```
### 🔐 Authentication & Authorization
| Feature | Implementation |
| -------------------- | ---------------------------------------------------------- |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Dashboard Login** | Password-based auth with JWT tokens (HttpOnly cookies) |
| **API Key Auth** | HMAC-signed keys with CRC validation |
| **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) |
| **OAuth 2.0 + PKCE** | 14 providers (Claude, Codex, GitHub, Cursor, Antigravity, Gemini, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Windsurf, GitLab Duo) |
| **Token Refresh** | Automatic OAuth token refresh before expiry |
| **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments |
| **MCP Scopes** | 10 granular scopes for MCP tool access control |
| **Authz Pipeline** | Route classification (PUBLIC / CLIENT_API / MANAGEMENT) — see `docs/AUTHZ_GUIDE.md` |
| **MCP Scopes** | ~13 granular scopes (read:health, write:combos, execute:completions, etc.) — see `docs/MCP-SERVER.md` |
### 🛡️ Encryption at Rest
@@ -58,6 +61,18 @@ All sensitive data stored in SQLite is encrypted using **AES-256-GCM** with scry
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
```
### 🛡️ Guardrails Framework
OmniRoute ships a hot-reloadable **guardrails registry** (`src/lib/guardrails/`) with 3 built-in guardrails ordered by priority:
| Guardrail | Priority | Purpose |
| ------------------ | -------- | --------------------------------------------------------------------------------------- |
| `vision-bridge` | 5 | Bridges non-vision models with image-aware descriptions; SSRF protection for image URLs |
| `pii-masker` | 10 | Pre+post call PII redaction (emails, phone, CPF, CNPJ, credit cards, SSN) |
| `prompt-injection` | 20 | Detects override/role-hijack/jailbreak/leak patterns |
Custom guardrails register via `registerGuardrail(new MyGuardrail())`. The model is fail-open (exceptions never block traffic). Per-request opt-out via `x-omniroute-disabled-guardrails` header. → See [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md).
### 🧠 Prompt Injection Guard
Middleware that detects and blocks prompt injection attacks in LLM requests:
@@ -168,8 +183,30 @@ docker run -d \
## Dependencies
- Run `npm audit` regularly
- Run `npm audit` regularly (`npm run audit:deps` covers main + electron)
- Keep dependencies updated
- The project uses `husky` + `lint-staged` for pre-commit checks
- CI pipeline runs ESLint security rules on every push
- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
- The project uses `husky` + `lint-staged` for pre-commit checks (lint-staged + check-docs-sync + check:any-budget:t11)
- CI pipeline runs ESLint security rules on every push (`no-eval`, `no-implied-eval`, `no-new-func` = error)
- Provider constants validated at module load via Zod (`src/shared/validation/schemas.ts`)
- Secure-by-default libraries used: `dompurify` / `isomorphic-dompurify` (XSS), `jose` (JWT), `better-sqlite3` (no SQLi risk via parameterized queries), `bcryptjs` (password hashing)
## Hard Security Rules
These rules are enforced by tooling and reviewers:
1. **Never commit secrets** — `.env` is gitignored; `.env.example` is the template
2. **Never use `eval()`, `new Function()`, or implied eval** — ESLint enforces
3. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval
4. **Never write raw SQL in routes** — always go through `src/lib/db/` (parameterized)
5. **Always validate inputs with Zod** — `src/shared/validation/schemas.ts`
6. **Always sanitize upstream headers** — denylist in `src/shared/constants/upstreamHeaders.ts`
7. **Encrypt credentials at rest** — AES-256-GCM via `src/lib/db/encryption.ts`
## References
- [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) — authorization pipeline
- [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) — guardrails framework
- [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) — audit log and retention
- [`docs/RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout
- [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) — TLS fingerprinting (legal/ethical notice)
- [`CLAUDE.md`](CLAUDE.md) — hard rules for AI agents

58
Tuto_Qdrant.MD → Tuto_Qdrant.md
View File

@@ -1,9 +1,19 @@
# Tutorial Qdrant no OmniRoute (Guia para vídeo)
> ⚠️ **Status (v3.8.0):** Integração Qdrant está **dormente** no pipeline. As funções de upsert/search/delete existem em `src/lib/memory/qdrant.ts` e a UI de configuração está pronta (`MemorySkillsTab.tsx` + endpoint `/api/settings/qdrant/embedding-models`), mas:
>
> - `upsertSemanticMemoryPoint`, `searchSemanticMemory` e `deleteSemanticMemoryPoint` **não são chamadas** pelo pipeline de chat — busca semântica corrente usa apenas o store local em SQLite (ver `docs/MEMORY.md`).
> - As rotas `/api/settings/qdrant/health`, `/api/settings/qdrant/search` e `/api/settings/qdrant/cleanup` mencionadas neste tutorial **ainda não foram implementadas**.
> - Os botões "Testar conexão" e "Teste de busca" no painel exigem que essas rotas existam; até lá, são placeholders.
>
> Este documento descreve a UX/configuração planejada. Para o sistema de memória ativo hoje, consulte [`docs/MEMORY.md`](docs/MEMORY.md). Acompanhe o status da ativação em issues marcadas com `area:qdrant`.
## 1) O que é o Qdrant no OmniRoute
O Qdrant é o banco vetorial usado para memória semântica.
No OmniRoute, ele ajuda a:
- Encontrar contexto por significado (não só palavra exata).
- Reaproveitar memórias antigas com mais precisão.
- Melhorar respostas com base em histórico relevante.
@@ -12,38 +22,48 @@ No OmniRoute, ele ajuda a:
---
## 2) Quando o OmniRoute envia dados para o Qdrant
Com Qdrant habilitado e modelo de embedding configurado, o sistema envia vetores quando:
- Memórias são salvas (upsert de memória).
- Fluxos de chat recuperam contexto semântico/híbrido.
- Testes de busca no painel geram embedding e consultam a coleção.
Resumo prático:
- Sem Qdrant: busca mais limitada (texto/chave).
- Com Qdrant: busca por similaridade semântica (mais inteligente).
---
## 3) Pré-requisitos
Você precisa de:
- Instância Qdrant acessível (porta 6333).
- Coleção criada (ex.: `omniroute_memory`).
- Modelo de embedding válido (ex.: OpenRouter).
- Credencial do provider do embedding configurada no OmniRoute.
Exemplo de modelo OpenRouter:
- `openrouter/nvidia/llama-nemotron-embed-v1-1b-v2:free`
Importante:
- O texto do modelo deve estar em formato `provider/model`.
- Se usar modelo com dimensão diferente da coleção, a busca falha.
---
## 4) Como configurar no painel do OmniRoute
No menu:
- `Admin > Settings > Qdrant (Memória vetorial)`
Preencha:
- `Ativar Qdrant`: ligado.
- `Host`: IP ou URL do servidor Qdrant (sem porta no campo Host).
- `Porta`: `6333`.
@@ -52,6 +72,7 @@ Preencha:
- `API Key`: opcional (preencha se seu Qdrant exigir).
Depois:
1. Clique em `Salvar`.
2. Clique em `Testar conexão`.
3. No `Teste de busca`, digite um texto e clique em `Buscar`.
@@ -59,7 +80,9 @@ Depois:
---
## 5) Como criar a coleção no Dashboard do Qdrant (sem comando)
No Qdrant Dashboard:
1. Clique em `Create collection`.
2. Escolha `Global search`.
3. Em tipo de busca, use `Custom`.
@@ -70,21 +93,26 @@ No Qdrant Dashboard:
5. Salve a coleção com nome `omniroute_memory`.
Se já tinha coleção com dimensão errada:
- Recrie a coleção com dimensão correta.
---
## 6) Como validar se está funcionando
Checklist rápido:
1. `Testar conexão` no OmniRoute retorna OK.
2. Busca no painel retorna resultados (não “Sem resultados”).
3. No Qdrant Dashboard, aparecem pontos na coleção (payload + vector).
4. Resultados de chat passam a recuperar contexto mais relevante.
Sinal clássico de problema:
- Dados entram no Qdrant, mas busca do painel não retorna nada.
Causas comuns:
- Dimensão do vetor incompatível.
- Nome do vetor diferente do esperado (`omniao`).
- Modelo inválido/incompleto no campo de embedding.
@@ -93,7 +121,9 @@ Causas comuns:
---
## 7) O que melhorou com esta atualização
Nesta melhoria do OmniRoute:
- Suporte a embeddings de qualquer provider compatível (não só OpenAI fixo).
- Endpoint para carregar modelos de embedding na tela de configurações.
- Campo manual para modelo custom quando não aparecer na lista.
@@ -102,7 +132,9 @@ Nesta melhoria do OmniRoute:
---
## 8) Roteiro curto para seu vídeo
Sugestão de demo (3-5 minutos):
1. Mostrar problema sem Qdrant (busca simples).
2. Abrir Settings e habilitar Qdrant.
3. Configurar host/porta/collection/modelo.
@@ -112,25 +144,33 @@ Sugestão de demo (3-5 minutos):
7. Rodar um chat e mostrar melhoria de recuperação semântica.
Mensagem final para a galera:
- "Qdrant no OmniRoute transforma memória de palavra-chave em memória por significado."
---
## 9) Referências de código (para equipe técnica)
- UI de configuração Qdrant:
- `src/app/(dashboard)/dashboard/settings/components/MemorySkillsTab.tsx`
- Endpoint de modelos de embedding para Qdrant:
- `src/app/api/settings/qdrant/embedding-models/route.ts`
- Integração backend com Qdrant (health, upsert, search, cleanup):
- `src/lib/memory/qdrant.ts`
- Recuperação de memórias no fluxo de chat:
- `src/lib/memory/retrieval.ts`
- `open-sse/handlers/chatCore.ts`
**Implementado:**
- UI de configuração Qdrant: `src/app/(dashboard)/dashboard/settings/components/MemorySkillsTab.tsx`
- Endpoint de modelos de embedding: `src/app/api/settings/qdrant/embedding-models/route.ts`
- Funções backend (definidas mas dormentes): `src/lib/memory/qdrant.ts` exporta `upsertSemanticMemoryPoint`, `searchSemanticMemory`, `deleteSemanticMemoryPoint`
**Pendente para ativar a integração:**
- Rotas API: `/api/settings/qdrant/health`, `/api/settings/qdrant/search`, `/api/settings/qdrant/cleanup`
- Wire-up no fluxo de chat: `src/lib/memory/retrieval.ts` e `open-sse/handlers/chatCore.ts` precisam chamar `searchSemanticMemory` quando Qdrant estiver habilitado nas settings
- Wire-up no save de memória: `src/lib/memory/extraction.ts` (ou camada equivalente) precisa chamar `upsertSemanticMemoryPoint` após persistir cada memória
Para o sistema de memória ativo hoje (SQLite-only), ver [`docs/MEMORY.md`](docs/MEMORY.md).
---
## 10) Observação importante de segurança
Nunca exponha em vídeo:
- API key completa do OpenRouter.
- Tokens reais de produção.
- Endpoints internos sem proteção.

2
docs/MEMORY.md
View File

@@ -308,7 +308,7 @@ default TTL 5 min).
definitions alongside memory.
- [MCP-SERVER.md](./MCP-SERVER.md) — MCP transport / scopes.
- [API_REFERENCE.md](./API_REFERENCE.md) — broader API surface.
- [Tuto_Qdrant.MD](../Tuto_Qdrant.MD) — repository-root Qdrant setup tutorial.
- [Tuto_Qdrant.md](../Tuto_Qdrant.md) — repository-root Qdrant setup tutorial (integration currently dormant — see status banner at top of that file).
- Source modules:
- `src/lib/memory/types.ts`, `schemas.ts`
- `src/lib/memory/store.ts`, `retrieval.ts`, `injection.ts`

4
docs/REPOSITORY_MAP.md
View File

@@ -43,7 +43,7 @@ OmniRoute/
## Root files
| File | Purpose |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **README.md** | Marketing landing page + quick start + feature matrix (see also `llm.txt`) |
| **CHANGELOG.md** | Per-release changelog (auto-generated by `/version-bump-cc` skill) |
| **LICENSE** | MIT license text |
@@ -54,7 +54,7 @@ OmniRoute/
| **SECURITY.md** | Vulnerability reporting policy, supported versions, threat model |
| **CODE_OF_CONDUCT.md** | Contributor Covenant — community behavior expectations |
| **llm.txt** | Plain-text landing optimized for LLM crawlers (SEO for AI assistants) |
| **Tuto_Qdrant.MD** | Standalone tutorial for enabling Qdrant vector memory (see also `docs/MEMORY.md`) |
| **Tuto_Qdrant.md** | Tutorial for enabling Qdrant vector memory — **integration currently dormant** (see banner; primary memory docs in `docs/MEMORY.md`) |
| **package.json** | npm manifest, scripts, dependencies, engines, c8 coverage gate |
| **package-lock.json** | Locked dependency tree |
| **tsconfig.json** | Root TypeScript config |

526
docs/archive/RFC-AUTO-ASSESSMENT-DRAFT.md
View File

@@ -1,526 +0,0 @@
# RFC: Auto-Assessment & Self-Healing Combo Engine
> ⚠️ **ARCHIVED (DEPRECATED) — 2026-05-13**
>
> This RFC was partially implemented in `src/domain/assessment/` (Phase 1 ~30%: `assessor.ts`, `categorizer.ts`, `selfHealer.ts` exist; persistence is in-memory only, scoped to `auto/*` models).
>
> **The broader generic eval framework that supplanted this RFC** lives at `src/lib/evals/` and is documented in [EVALS.md](../EVALS.md). For Auto Combo scoring (which absorbed the "self-healing" direction), see [AUTO-COMBO.md](../AUTO-COMBO.md) and `open-sse/services/autoCombo/`.
>
> Kept here for historical context. Do not implement against this document — refer to the source files and the docs above.
## Summary
Omniroute's combo system currently requires manual configuration: users must know which providers and models are actually working, then manually wire them into combo chains. When providers fail (rate limits, auth errors, model deprecation), combos silently degrade — routing to dead endpoints that timeout or return errors. There is no automated way to:
1. **Discover** which provider/model pairs actually respond to chat completions
2. **Categorize** models by capability (coding, reasoning, vision, speed, etc.)
3. **Self-heal** combos by removing dead models and promoting working ones
4. **Auto-generate** sensible combo configurations from available providers
This proposes an **Auto-Assessment Engine** that continuously tests, categorizes, and self-heals combo configurations — making omniroute truly "plug and play" for non-technical users.
---
## Problem Statement
### What we encountered (real production incident)
While configuring omniroute for production use, we discovered:
- **44 combos had models from providers that returned "`Invalid model`" errors** — `kiro/claude-opus-4.6`, `kiro/claude-sonnet-4.6`, `gh/claude-sonnet-4.5` all fail with 400/404
- **No automated way to know which models actually work** — the `/v1/models` endpoint lists 1,236 models, but `/v1/chat/completions` fails for most of them
- **Weight-based routing sends traffic to dead models** — a model weighted at 30% that returns errors wastes 30% of requests
- **Manual diagnosis took hours** — we had to curl each model individually, categorize results, then update the SQLite DB
- **Provider `test_status` field exists but isn't used for routing** — `provider_connections` has `test_status` (active/banned/expired/credits_exhausted) but the combo resolver ignores it
### Current flow (broken)
```
User adds providers → Manually creates combos → Manually assigns models → ???
↓
Some models work,
some return errors,
some timeout...
BUT routing doesn't know!
```
### Proposed flow (self-healing)
```
User adds providers → Auto-Assessment runs → Working models discovered
↓
Capability categorization
↓
Combos auto-generated/updated with working models
↓
Continuous health monitoring keeps combos healthy
```
---
## Architecture
### New Components
```
┌────────────────────────────────────────────────────────┐
│ Auto-Assessment Engine │
├────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Assessor │ │ Categorizer │ │ Self-Healer │ │
│ │ │ │ │ │ │ │
│ │ • Probe all │ │ • Classify │ │ • Remove │ │
│ │ models │ │ models by │ │ dead │ │
│ │ • Measure │ │ capability │ │ models │ │
│ │ latency │ │ • Assign │ │ • Promote │ │
│ │ • Track │ │ tier tags │ │ working │ │
│ │ success │ │ • Build │ │ models │ │
│ │ rates │ │ fitness │ │ • Re-weight │ │
│ │ │ │ scores │ │ combos │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Assessment Database │ │
│ │ │ │
│ │ model_assessments: │ │
│ │ model_id | provider | status | latency_p50 │ │
│ │ latency_p95 | success_rate | last_tested │ │
│ │ error_type | tier | categories[] | fitness │ │
│ │ context_window | output_tokens | vision | tbc │ │
│ │ │ │
│ │ assessment_runs: │ │
│ │ run_id | started_at | completed_at │ │
│ │ models_tested | models_passed | models_failed │ │
│ │ │ │
│ │ combo_health: │ │
│ │ combo_id | healthy_models | dead_models │ │
│ │ last_auto_fix | auto_fix_count │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────┬─────────────────────────┘
│
▼
Existing combo system (weighted-fallback, priority, etc.)
+ Enhanced comboResolver that skips dead models
```
---
## Detailed Design
### 1. Assessor — `src/domain/assessor.ts`
**Purpose**: Probe every provider/model pair with a lightweight chat completion to determine if it works and measure performance.
```typescript
interface ModelAssessment {
modelId: string;
providerId: string;
status: "working" | "broken" | "rate_limited" | "timeout" | "auth_error" | "unknown";
// Performance metrics
latencyP50: number; // milliseconds
latencyP95: number; // milliseconds
successRate: number; // 0..1 over last N probes
// Capability detection
supportsVision: boolean;
supportsToolCall: boolean;
supportsStreaming: boolean;
maxContextWindow: number;
maxOutputTokens: number;
categories: ModelCategory[]; // 'coding' | 'reasoning' | 'chat' | 'fast' | 'vision' | 'reasoning_deep'
tier: "premium" | "balanced" | "fast" | "free";
// Metadata
lastTested: string; // ISO timestamp
lastError: string | null;
consecutiveFails: number;
probeCount: number;
}
type ModelCategory =
| "coding" // Good at code generation, debugging, refactoring
| "reasoning" // Strong logical reasoning, math, analysis
| "reasoning_deep" // Extended thinking, complex multi-step reasoning
| "chat" // Good conversational ability
| "fast" // Sub-2s response time
| "vision" // Image input support
| "tool_call" // Function/tool calling support
| "structured_output"; // JSON mode / structured output
```
**Assessment Probes** — three tiers of testing:
| Probe | Prompt | Max Tokens | Purpose |
| ------------ | ------------------------------------------ | ---------- | ---------------------------------------------- |
| **Quick** | `"ok"` | 1 | Does it respond at all? |
| **Standard** | `"Write a function that adds two numbers"` | 50 | Coding, tool call, structured output detection |
| **Deep** | Vision input + multi-turn | 100 | Vision, streaming, context window |
**Scheduling**:
- Full assessment on startup (or first provider addition)
- Quick probe every 5 minutes for working models
- Standard probe every 30 minutes
- Deep probe every 6 hours (or on demand)
- Immediate probe after any model returns an error
- Exponential backoff: 1 min → 5 min → 15 min → 30 min for consistently failing models
### 2. Categorizer — `src/domain/categorizer.ts`
**Purpose**: Classify each working model into capability categories and assign fitness scores per category.
**Category Detection Logic**:
```typescript
function categorizeModel(assessment: ModelAssessment): ModelCategory[] {
const categories: ModelCategory[] = [];
// Speed classification
if (assessment.latencyP50 < 2000) categories.push("fast");
// Capability from probe responses
if (assessment.supportsToolCall) categories.push("tool_call");
if (assessment.supportsVision) categories.push("vision");
if (assessment.supportsStreaming) categories.push("structured_output"); // if supports JSON mode
// Tier-based reasoning classification
if (assessment.tier === "premium") {
categories.push("reasoning_deep", "coding", "reasoning");
} else if (assessment.tier === "balanced") {
categories.push("coding", "reasoning");
} else if (assessment.tier === "fast") {
categories.push("chat");
}
return categories;
}
```
**Fitness Scores** (0..1 per category):
| Category | Scoring Formula |
| ---------------- | -------------------------------------------------------------------- |
| `coding` | `0.4 * successRate + 0.3 * (1 - latencyP95/10000) + 0.3 * tierScore` |
| `reasoning` | `0.5 * tierScore + 0.3 * successRate + 0.2 * (1 - latencyP95/15000)` |
| `reasoning_deep` | `0.7 * tierScore + 0.3 * successRate` (only premium tier eligible) |
| `chat` | `0.4 * successRate + 0.4 * (1 - latencyP95/5000) + 0.2 * tierScore` |
| `fast` | `0.6 * (1 - latencyP50/3000) + 0.3 * successRate + 0.1 * costInv` |
| `vision` | `0.5 * successRate + 0.3 * (1 - latencyP95/15000) + 0.2 * tierScore` |
### 3. Self-Healer — `src/domain/selfHealer.ts`
**Purpose**: Automatically update combo model lists based on assessment results.
**Auto-Heal Rules**:
```
IF model.status == 'broken' OR model.consecutiveFails >= 3:
REMOVE model from all combos
LOG "Auto-heal: removed {model} from {combo} (status: {status}, fails: {n})"
IF model.status == 'rate_limited' OR model.status == 'timeout':
REDUCE model weight by 50% (minimum weight: 5)
LOG "Auto-heal: reduced weight of {model} in {combo} (status: {status})"
IF combo has 0 working models:
FIND best working model for combo's category
ADD to combo with weight 100
LOG "Auto-heal: emergency added {model} to {combo} (was empty)"
IF combo has fewer than 3 working models:
FIND additional working models in same category
ADD with proportional weights
LOG "Auto-heal: expanded {combo} with {n} models"
IF model.status transitions from 'broken' → 'working':
RESTORE original weight (or proportional weight)
LOG "Auto-heal: restored {model} in {combo}"
```
**Auto-Generation of Combos**:
When a new provider is added, or on first startup, auto-generate standard combos:
```typescript
const AUTO_COMBOS = [
{ name: "auto/best-coding", categories: ["coding"], tier: ["premium", "balanced"] },
{ name: "auto/best-reasoning", categories: ["reasoning_deep"], tier: ["premium"] },
{ name: "auto/best-fast", categories: ["fast"], tier: ["fast", "balanced"] },
{ name: "auto/best-vision", categories: ["vision"], tier: ["premium", "balanced"] },
{ name: "auto/best-chat", categories: ["chat"], tier: ["balanced", "premium"] },
{ name: "auto/coding", categories: ["coding"], tier: ["balanced", "fast", "premium"] },
{ name: "auto/fast", categories: ["fast"], tier: ["fast"] },
{ name: "auto/pro-coding", categories: ["coding"], tier: ["premium"] },
{ name: "auto/pro-reasoning", categories: ["reasoning_deep"], tier: ["premium"] },
{ name: "auto/pro-vision", categories: ["vision"], tier: ["premium"] },
{ name: "auto/pro-chat", categories: ["chat"], tier: ["premium"] },
{ name: "auto/pro-fast", categories: ["fast"], tier: ["fast"] },
];
```
### 4. Database Schema
```sql
-- New tables for assessment engine
CREATE TABLE IF NOT EXISTS model_assessments (
id TEXT PRIMARY KEY,
model_id TEXT NOT NULL,
provider_id TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'unknown', -- working|broken|rate_limited|timeout|auth_error|unknown
latency_p50 INTEGER, -- milliseconds
latency_p95 INTEGER, -- milliseconds
success_rate REAL DEFAULT 0, -- 0..1
supports_vision INTEGER DEFAULT 0,
supports_tool_call INTEGER DEFAULT 0,
supports_streaming INTEGER DEFAULT 0,
supports_structured_output INTEGER DEFAULT 0,
max_context_window INTEGER,
max_output_tokens INTEGER,
categories TEXT DEFAULT '[]', -- JSON array of ModelCategory
fitness_scores TEXT DEFAULT '{}', -- JSON object: {category: score}
tier TEXT DEFAULT 'balanced', -- premium|balanced|fast|free
last_tested TEXT,
last_error TEXT,
consecutive_fails INTEGER DEFAULT 0,
probe_count INTEGER DEFAULT 0,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
UNIQUE(model_id, provider_id)
);
CREATE TABLE IF NOT EXISTS assessment_runs (
id TEXT PRIMARY KEY,
started_at TEXT NOT NULL,
completed_at TEXT,
models_tested INTEGER DEFAULT 0,
models_passed INTEGER DEFAULT 0,
models_failed INTEGER DEFAULT 0,
models_rate_limited INTEGER DEFAULT 0,
duration_ms INTEGER,
trigger TEXT DEFAULT 'scheduled', -- scheduled|on_demand|on_provider_change|on_error
created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE TABLE IF NOT EXISTS combo_health (
combo_id TEXT PRIMARY KEY,
healthy_model_count INTEGER DEFAULT 0,
dead_model_count INTEGER DEFAULT 0,
total_model_count INTEGER DEFAULT 0,
last_auto_fix TEXT,
auto_fix_count INTEGER DEFAULT 0,
health_score REAL DEFAULT 0, -- 0..1, weighted by model health
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
FOREIGN KEY (combo_id) REFERENCES combos(id)
);
CREATE INDEX IF NOT EXISTS idx_model_assessments_status ON model_assessments(status);
CREATE INDEX IF NOT EXISTS idx_model_assessments_provider ON model_assessments(provider_id);
CREATE INDEX IF NOT EXISTS idx_model_assessments_tier ON model_assessments(tier);
CREATE INDEX IF NOT EXISTS idx_combo_health_health_score ON combo_health(health_score);
```
### 5. API Endpoints
```bash
# Trigger assessment (blocking or background)
POST /api/assess/models
Body: { "scope": "all" | "provider:<id>" | "model:<id>", "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?

84
docs/i18n/ar/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/bg/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/bn/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/cs/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/da/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/de/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/es/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/fa/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/fi/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/fr/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/gu/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/he/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/hi/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/hu/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/id/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/in/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/it/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ja/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ko/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/mr/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ms/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/nl/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/no/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/phi/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/pl/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/pt-BR/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/pt/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ro/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ru/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/sk/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/sv/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/sw/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ta/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/te/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/th/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/tr/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/uk-UA/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/ur/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/vi/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
docs/i18n/zh-CN/llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`

84
llm.txt
View File

@@ -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)
### MCP Server (37 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` |
|------------|-------|
| 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`