Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
docs(i18n): demonstrate translator with pt-BR backfill of CLAUDE.md + architecture/ARCHITECTURE.md
diegosouzapwae3d73a2e72c
diff --git a/.i18n-state.json b/.i18n-state.jsonnew file mode 100644index 0000000000..de42539510--- /dev/null+++ b/.i18n-state.json@@ -0,0 +1,24 @@+{+ "sources": {+ "CLAUDE.md": {+ "source_hash": "ee7af1716a6e22feb93bb160f8b2810fa7dce8f56075b218ced51b04863f1786",+ "locales": {+ "pt-BR": {+ "source_hash": "ee7af1716a6e22feb93bb160f8b2810fa7dce8f56075b218ced51b04863f1786",+ "target_hash": "7a85c5795d376e8572598f9d963e32ec62f925b952b61b60c78fa42785836014",+ "updated_at": "2026-05-13T20:02:23.088Z"+ }+ }+ },+ "docs/architecture/ARCHITECTURE.md": {+ "source_hash": "573ccfe1a49d74999101460a3ee055bd07109c832d15dc9a4c6ef61ee8433302",+ "locales": {+ "pt-BR": {+ "source_hash": "573ccfe1a49d74999101460a3ee055bd07109c832d15dc9a4c6ef61ee8433302",+ "target_hash": "6daa8b7db866dd2781efd9ae02a576cf9f2cce2a8597b02a808c341e1d1335c3",+ "updated_at": "2026-05-13T20:09:25.192Z"+ }+ }+ }+ }+}diff --git a/docs/guides/I18N.md b/docs/guides/I18N.mdindex db85d72746..96fe1902ae 100644--- a/docs/guides/I18N.md+++ b/docs/guides/I18N.md@@ -4,16 +4,74 @@ OmniRoute supports **30 languages** with full dashboard UI translation, translat🌐 **Languages:** 🇺🇸 [English](./I18N.md) | 🇧🇷 [Português (Brasil)](./pt-BR/I18N.md) | 🇪🇸 [Español](./es/I18N.md) | 🇫🇷 [Français](./fr/I18N.md) | 🇩🇪 [Deutsch](./de/I18N.md) | 🇮🇹 [Italiano](./it/I18N.md) | 🇷🇺 [Русский](./ru/I18N.md) | 🇨🇳 [中文 (简体)](./zh-CN/I18N.md) | 🇯🇵 [日本語](./ja/I18N.md) | 🇰🇷 [한국어](./ko/I18N.md) | 🇸🇦 [العربية](./ar/I18N.md) | 🇮🇳 [हिन्दी](./hi/I18N.md) | 🇹🇭 [ไทย](./th/I18N.md) | 🇹🇷 [Türkçe](./tr/I18N.md) | 🇺🇦 [Українська](./uk-UA/I18N.md) | 🇻🇳 [Tiếng Việt](./vi/I18N.md) | 🇧🇬 [Български](./bg/I18N.md) | 🇩🇰 [Dansk](./da/I18N.md) | 🇫🇮 [Suomi](./fi/I18N.md) | 🇮🇱 [עברית](./he/I18N.md) | 🇭🇺 [Magyar](./hu/I18N.md) | 🇮🇩 [Bahasa Indonesia](./id/I18N.md) | 🇲🇾 [Bahasa Melayu](./ms/I18N.md) | 🇳🇱 [Nederlands](./nl/I18N.md) | 🇳🇴 [Norsk](./no/I18N.md) | 🇵🇹 [Português (Portugal)](./pt/I18N.md) | 🇷🇴 [Română](./ro/I18N.md) | 🇵🇱 [Polski](./pl/I18N.md) | 🇸🇰 [Slovenčina](./sk/I18N.md) | 🇸🇪 [Svenska](./sv/I18N.md) | 🇵🇭 [Filipino](./phi/I18N.md) | 🇨🇿 [Čeština](./cs/I18N.md)+## Translation pipeline (recommended — v3.8.0)++OmniRoute uses a hash-based incremental translator for docs, backed by an+OpenAI-compatible LLM endpoint (typically `cx/gpt-5.4-mini` through OmniRoute+Cloud):++```bash+# Run translations (incremental — only touches changed sources)+npm run i18n:run++# Limit to one locale+npm run i18n:run -- --locale=pt-BR++# Specific files (comma-separated, repo-relative paths)+npm run i18n:run -- --files=CLAUDE.md,docs/architecture/ARCHITECTURE.md++# Force retranslate everything (expensive)+npm run i18n:run -- --force++# Preview what would happen (no API calls, no writes)+npm run i18n:run:dry++# CI gate — exits non-zero if state is drifting+npm run i18n:check+```++**Source of truth.** `config/i18n.json` lists every locale (UI + docs) plus+the RTL set and the `docsExcluded` codes. The runtime config in+`src/i18n/config.ts` is a thin adapter over that JSON.++**Backend.** Configured via env (set in `.env`, never committed):++| Variable | Purpose |+| ----------------------------------- | --------------------------------------- |+| `OMNIROUTE_TRANSLATION_API_URL` | OpenAI-compatible base URL, e.g. `…/v1` |+| `OMNIROUTE_TRANSLATION_API_KEY` | bearer token (kept out of logs) |+| `OMNIROUTE_TRANSLATION_MODEL` | model id, e.g. `cx/gpt-5.4-mini` |+| `OMNIROUTE_TRANSLATION_TIMEOUT_MS` | optional, default `60000` |+| `OMNIROUTE_TRANSLATION_CONCURRENCY` | optional, default `4` |++**State tracking.** `.i18n-state.json` (committed) keeps SHA-256 hashes per+source + per locale. Drift detection is automatic and deterministic — no API+calls in `i18n:check`.++**Output shape.** Each translated file gets a top-level `# <heading>+(<native>)` line, a `🌐 Languages: …` bar, an `---` separator, and the+translated body. That layout matches what `scripts/check/check-docs-sync.mjs`+already enforces for `llm.txt` and `CHANGELOG.md` mirrors.++### Legacy scripts (deprecated)++The older Python script (`scripts/i18n/i18n_autotranslate.py`) and the+Google-Translate-backed generator (`scripts/i18n/generate-multilang.mjs`)+still exist with a deprecation banner. They will be removed in v3.10. The+`messages` and `readme` modes of `generate-multilang.mjs` (UI strings + root+README variants) are not yet handled by the new pipeline and are still used.+## Quick Reference-| Task | Command |-| ---------------------- | -------------------------------------------------------------------------------------------- |-| Generate translations | `node scripts/i18n/generate-multilang.mjs messages` |-| Translate docs (LLM) | `python3 scripts/i18n/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>` |-| Validate a locale | `python3 scripts/i18n/validate_translation.py quick -l cs` |-| Check code keys | `python3 scripts/i18n/check_translations.py` |-| Generate QA report | `node scripts/i18n/generate-qa-checklist.mjs` |-| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs` |+| Task | Command |+| ----------------------- | ---------------------------------------------------------- |+| Translate docs (LLM) | `npm run i18n:run` (preferred — incremental, hash-based) |+| Translate UI strings | `node scripts/i18n/generate-multilang.mjs messages` |+| Check translation drift | `npm run i18n:check` |+| Validate a locale | `python3 scripts/i18n/validate_translation.py quick -l cs` |+| Check code keys | `python3 scripts/i18n/check_translations.py` |+| Generate QA report | `node scripts/i18n/generate-qa-checklist.mjs` |+| Visual QA (Playwright) | `node scripts/i18n/run-visual-qa.mjs` |## Architecturediff --git a/docs/i18n/pt-BR/CLAUDE.md b/docs/i18n/pt-BR/CLAUDE.mdindex 0d33427f74..be71772ef1 100644--- a/docs/i18n/pt-BR/CLAUDE.md+++ b/docs/i18n/pt-BR/CLAUDE.md@@ -1,233 +1,401 @@-# CLAUDE.md — AI Agent Session Bootstrap (Português (Brasil))+# CLAUDE.md (Português (Brasil))-🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇧🇷 [pt-BR](../pt-BR/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)+🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/CLAUDE.md) · 🇩🇰 [da](../da/CLAUDE.md) · 🇩🇪 [de](../de/CLAUDE.md) · 🇪🇸 [es](../es/CLAUDE.md) · 🇮🇷 [fa](../fa/CLAUDE.md) · 🇫🇮 [fi](../fi/CLAUDE.md) · 🇫🇷 [fr](../fr/CLAUDE.md) · 🇮🇳 [gu](../gu/CLAUDE.md) · 🇮🇱 [he](../he/CLAUDE.md) · 🇮🇳 [hi](../hi/CLAUDE.md) · 🇭🇺 [hu](../hu/CLAUDE.md) · 🇮🇩 [id](../id/CLAUDE.md) · 🇮🇩 [in](../in/CLAUDE.md) · 🇮🇹 [it](../it/CLAUDE.md) · 🇯🇵 [ja](../ja/CLAUDE.md) · 🇰🇷 [ko](../ko/CLAUDE.md) · 🇮🇳 [mr](../mr/CLAUDE.md) · 🇲🇾 [ms](../ms/CLAUDE.md) · 🇳🇱 [nl](../nl/CLAUDE.md) · 🇳🇴 [no](../no/CLAUDE.md) · 🇵🇭 [phi](../phi/CLAUDE.md) · 🇵🇱 [pl](../pl/CLAUDE.md) · 🇵🇹 [pt](../pt/CLAUDE.md) · 🇷🇴 [ro](../ro/CLAUDE.md) · 🇷🇺 [ru](../ru/CLAUDE.md) · 🇸🇰 [sk](../sk/CLAUDE.md) · 🇸🇪 [sv](../sv/CLAUDE.md) · 🇰🇪 [sw](../sw/CLAUDE.md) · 🇮🇳 [ta](../ta/CLAUDE.md) · 🇮🇳 [te](../te/CLAUDE.md) · 🇹🇭 [th](../th/CLAUDE.md) · 🇹🇷 [tr](../tr/CLAUDE.md) · 🇺🇦 [uk-UA](../uk-UA/CLAUDE.md) · 🇵🇰 [ur](../ur/CLAUDE.md) · 🇻🇳 [vi](../vi/CLAUDE.md) · 🇨🇳 [zh-CN](../zh-CN/CLAUDE.md)----> Quick-start context for AI coding agents. For deep architecture details, see `AGENTS.md`.-> For contribution workflow, see `CONTRIBUTING.md`.+Este arquivo fornece orientações para Claude Code (claude.ai/code) ao trabalhar com código neste repositório.## Início Rápido```bash-npm install # Install deps (auto-generates .env from .env.example)-npm run dev # Dev server at http://localhost:20128-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 check # lint + test combined-npm run check:cycles # Detect circular dependencies+npm install # Instalar dependências (gera automaticamente .env a partir de .env.example)+npm run dev # Servidor de desenvolvimento em http://localhost:20128+npm run build # Build de produção (Next.js 16 standalone)+npm run lint # ESLint (0 erros esperados; avisos são pré-existentes)+npm run typecheck:core # Verificação TypeScript (deve estar limpo)+npm run typecheck:noimplicit:core # Verificação rigorosa (sem any implícito)+npm run test:coverage # Testes unitários + gate de cobertura (75/75/75/70 — declarações/líneas/funções/branches)+npm run check # lint + teste combinados+npm run check:cycles # Detectar dependências circulares```-### Running a Single Test+### Executando Testes```bash-# Node.js native test runner (most tests)-node --import tsx/esm --test tests/unit/your-file.test.mjs+# Arquivo de teste único (executador de teste nativo do Node.js — a maioria dos testes)+node --import tsx/esm --test tests/unit/your-file.test.ts-# Vitest (MCP server, autoCombo, cache)+# Vitest (servidor MCP, autoCombo, cache)npm run test:vitest++# Todas as suítes+npm run test:all```+Para a matriz completa de testes, veja `CONTRIBUTING.md` → "Executando Testes". Para arquitetura profunda, veja `AGENTS.md`.+----## Visão Geral--**OmniRoute** — unified AI proxy/router. One endpoint, 100+ 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) |-| Services | `open-sse/services/` | Combo routing, rate limits, caching, etc |-| Database | `src/lib/db/` | SQLite domain modules (22 files) |-| Domain/Policy | `src/domain/` | Policy engine, cost rules, fallback logic |-| MCP Server | `open-sse/mcp-server/` | 25 tools, 3 transports, 10 scopes |-| A2A Server | `src/lib/a2a/` | JSON-RPC 2.0 agent protocol |-| Skills | `src/lib/skills/` | Extensible skill framework |-| Memory | `src/lib/memory/` | Persistent conversational memory |-| UI Components | `src/shared/components/` | React components (Tailwind CSS v4) |-| Provider Consts | `src/shared/constants/` | Provider registry (Zod-validated) |-| Validation | `src/shared/validation/` | Zod v4 schemas |-| Tests | `tests/` | Unit, integration, e2e, security, load |--### Monorepo Layout+## Projeto em Resumo-```-OmniRoute/ # Root package-├── src/ # Next.js 16 app (TypeScript)-├── open-sse/ # @omniroute/open-sse workspace (streaming engine)-├── electron/ # Desktop app (Electron)-├── tests/ # All test suites-├── docs/ # Documentation-└── bin/ # CLI entry point-```+**OmniRoute** — proxy/router de IA unificado. Um endpoint, 160+ provedores de LLM, fallback automático.++| Camada | Localização | Propósito |+| ---------------- | ----------------------- | -------------------------------------------------------------------------------- |+| Rotas da API | `src/app/api/v1/` | Next.js App Router — pontos de entrada |+| Manipuladores | `open-sse/handlers/` | Processamento de requisições (chat, embeddings, etc) |+| Executores | `open-sse/executors/` | Dispatch HTTP específico do provedor |+| Tradutores | `open-sse/translator/` | Conversão de formato (OpenAI↔Claude↔Gemini) |+| Transformador | `open-sse/transformer/` | API de Respostas ↔ Completações de Chat |+| Serviços | `open-sse/services/` | Roteamento combinado, limites de taxa, cache, etc |+| Banco de Dados | `src/lib/db/` | Módulos de domínio SQLite (45+ arquivos, 55 migrações) |+| Domínio/Política | `src/domain/` | Motor de políticas, regras de custo, lógica de fallback |+| Servidor MCP | `open-sse/mcp-server/` | 37 ferramentas (30 base + 3 memória + 4 habilidades), 3 transportes, ~13 escopos |+| Servidor A2A | `src/lib/a2a/` | Protocolo de agente JSON-RPC 2.0 |+| Habilidades | `src/lib/skills/` | Estrutura de habilidades extensível |+| Memória | `src/lib/memory/` | Memória conversacional persistente |++Monorepo: `src/` (aplicativo Next.js 16), `open-sse/` (workspace do motor de streaming), `electron/` (aplicativo desktop), `tests/`, `bin/` (ponto de entrada CLI).----## Request Pipeline (Abbreviated)+## Pipeline de Requisições```-Client → /v1/chat/completions (Next.js route)- → CORS → Zod validation → auth? → policy check → prompt injection guard+Cliente → /v1/chat/completions (rota Next.js)+ → CORS → validação Zod → auth? → verificação de política → proteção contra injeção de prompt→ handleChatCore() [open-sse/handlers/chatCore.ts]- → cache check → rate limit → combo routing?- → resolveComboTargets() → handleSingleModel() per target+ → verificação de cache → limite de taxa → roteamento combinado?+ → resolveComboTargets() → handleSingleModel() por alvo→ translateRequest() → getExecutor() → executor.execute()→ fetch() upstream → retry w/ backoff- → response translation → SSE stream or JSON+ → tradução da resposta → stream SSE ou JSON+ → Se Responses API: responsesTransformer.ts TransformStream```+As rotas da API seguem um padrão consistente: `Rota → pré-vôo CORS → validação de corpo Zod → Autenticação opcional (extractApiKey/isValidApiKey) → aplicação de política de chave da API → delegação de manipulador (open-sse)`. Sem middleware global do Next.js — a interceptação é específica da rota.++**Roteamento combinado** (`open-sse/services/combo.ts`): 14 estratégias (prioridade, ponderada, preenchimento-primeiro, round-robin, P2C, aleatório, menos-usado, otimizado por custo, ciente de reset, estritamente-aleatório, automático, lkgp, otimizado por contexto, retransmissão de contexto). Cada alvo chama `handleSingleModel()`, que envolve `handleChatCore()` com tratamento de erro por alvo e verificações de disjuntor. Veja `docs/routing/AUTO-COMBO.md` para a pontuação Auto-Combo de 9 fatores e `docs/architecture/RESILIENCE_GUIDE.md` para as 3 camadas de resiliência.+----## Key Conventions+## Estado de Execução de Resiliência-### Code Style+OmniRoute possui três mecanismos de falha temporária relacionados, mas distintos. Mantenha seu+escopo separado ao depurar o comportamento de roteamento. Veja o+[diagrama de resiliência de 3 camadas](./docs/diagrams/exported/resilience-3layers.svg)+(fonte: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))+para um mapa rápido.-- **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas-- **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative-- **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE+### Disjuntor de Provedor-### Database Access+**Escopo**: provedor inteiro, por exemplo, `glm`, `openai`, `anthropic`.-- **Always** go through `src/lib/db/` domain modules-- **Never** write raw SQL in routes or handlers-- **Never** add logic to `src/lib/localDb.ts` (re-export layer only)-- **Never** barrel-import from `localDb.ts` — import specific `db/` modules-- DB singleton: `getDbInstance()` from `src/lib/db/core.ts` (WAL journaling)-- Migrations: `src/lib/db/migrations/` — 21 versioned SQL files+**Propósito**: parar de enviar tráfego para um provedor que está falhando repetidamente no+nível upstream/serviço, para que um provedor não saudável não atrase cada requisição.-### Error Handling+**Implementação**:-- try/catch with specific error types, log with pino context-- Never swallow errors in SSE streams — use abort signals-- Return proper HTTP status codes (4xx/5xx)+- Classe principal: `src/shared/utils/circuitBreaker.ts`+- Fiação de gate/executação de chat: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`+- API de status em tempo de execução: `src/app/api/monitoring/health/route.ts`+- Wrappers compartilhados: `open-sse/services/accountFallback.ts`+- Tabela de estado persistido: `domain_circuit_breakers`-### Segurança+**Estados**:-- **Never** commit secrets/credentials-- **Never** use `eval()`, `new Function()`, or implied eval-- Validate all inputs with Zod schemas-- Encrypt credentials at rest (AES-256-GCM)+- `CLOSED`: tráfego normal é permitido.+- `OPEN`: provedor está temporariamente bloqueado; chamadores recebem uma resposta de circuito-aberto do provedor+ ou o roteamento combinado pula para outro alvo.+- `HALF_OPEN`: o tempo limite de reset expirou; permite uma requisição de teste. Sucesso fecha o+ disjuntor, falha o abre novamente.----+**Padrões** (`open-sse/config/constants.ts`):++- Provedores OAuth: limite `3`, tempo limite de reset `60s`.+- Provedores de chave da API: limite `5`, tempo limite de reset `30s`.+- Provedores locais: limite `2`, tempo limite de reset `15s`.++Somente estados de falha em nível de provedor devem acionar o disjuntor do provedor:-## Common Modification Scenarios+```ts+(408, 500, 502, 503, 504);+```++Não acione o disjuntor do provedor inteiro para erros normais de conta/chave/modelo como a maioria+dos casos `401`, `403` ou `429`. Esses geralmente pertencem ao cooldown de conexão ou bloqueio de modelo. Um erro genérico de provedor de chave da API `403` deve ser recuperável, a menos que seja classificado+como um erro terminal de provedor/conta.++O disjuntor usa recuperação preguiçosa, não um temporizador em segundo plano. Quando `OPEN` expira, leituras como `getStatus()`, `canExecute()`, e `getRetryAfterMs()` atualizam o estado para+`HALF_OPEN`, para que painéis e construtores de candidatos de combinação não continuem excluindo um+provedor expirado para sempre.++### Cooldown de Conexão++**Escopo**: uma conexão de provedor/conta/chave.++**Propósito**: pular temporariamente uma chave/conta ruim enquanto permite que outras conexões para+o mesmo provedor continuem atendendo requisições.-### Adding a New Provider+**Implementação**:-1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)-2. Add executor in `open-sse/executors/` if custom logic needed-3. Add translator in `open-sse/translator/` if non-OpenAI format-4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based-5. Register models in `open-sse/config/providerRegistry.ts`-6. Write tests in `tests/unit/` (registration, translation, error handling)+- Caminho de escrita/atualização: `src/sse/services/auth.ts::markAccountUnavailable()`+- Seleção/filtragem de conta: `src/sse/services/auth.ts::getProviderCredentials...`+- Cálculo de cooldown: `open-sse/services/accountFallback.ts::checkFallbackError()`+- Configurações: `src/lib/resilience/settings.ts`-### Adding a New API Route+Campos importantes nas conexões de provedor:-1. Create directory under `src/app/api/v1/your-route/`-2. Create `route.ts` with `GET`/`POST` handlers-3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation-4. Handler goes in `open-sse/handlers/` (import from there, not inline)-5. Add tests+```ts+rateLimitedUntil;+testStatus: "unavailable";+lastError;+lastErrorType;+errorCode;+backoffLevel;+```++Durante a seleção de conta, uma conexão é pulada enquanto:++```ts+new Date(rateLimitedUntil).getTime() > Date.now();+```++Cooldowns também são preguiçosos: quando `rateLimitedUntil` está no passado, a conexão se torna+elegível novamente. Ao usar com sucesso, `clearAccountError()` limpa `testStatus`,+`rateLimitedUntil`, campos de erro e `backoffLevel`.-### Adding a New DB Module+Comportamento padrão de cooldown de conexão:-1. Create `src/lib/db/yourModule.ts`-2. Import `getDbInstance` from `./core.ts`-3. Export CRUD functions for your domain table(s)-4. Add migration in `src/lib/db/migrations/` if new tables needed-5. Re-export from `src/lib/localDb.ts` (add to the re-export list only)-6. Write tests+- Cooldown base de OAuth: `5s`.+- Cooldown base de chave da API: `3s`.+- Chave da API `429` deve preferir dicas de retry upstream (`Retry-After`, cabeçalhos de reset, ou+ texto de reset analisável) quando disponíveis.+- Falhas recuperáveis repetidas usam backoff exponencial:-### Adding a New MCP Tool+```ts+baseCooldownMs * 2 ** failureIndex;+```-1. Add tool definition in `open-sse/mcp-server/tools/`-2. Define Zod input schema + async handler-3. Register in tool set (wired by `createMcpServer()`)-4. Assign to appropriate scope(s)-5. Write tests (tool invocation logged to `mcp_audit` table)+O guardião anti-thundering-herd impede que falhas concorrentes na mesma conexão+estendam repetidamente o cooldown ou dobrem o incremento de `backoffLevel`.-### Adding a New A2A Skill+Estados terminais não são cooldowns. `banned`, `expired`, e `credits_exhausted` são+destinados a permanecer indisponíveis até que credenciais/configurações mudem ou um operador os redefina.+Não sobrescreva estados terminais com estado de cooldown transitório.-1. Create skill in `src/lib/a2a/skills/`-2. Skill receives task context (messages, metadata) → returns structured result-3. Register in the DB-backed skill registry-4. Write tests+### Bloqueio de Modelo++**Escopo**: provedor + conexão + modelo.++**Propósito**: evitar desabilitar uma conexão inteira quando apenas um modelo está indisponível ou+com limite de cota para essa conexão.++Exemplos:++- Provedores de cota por modelo retornando `429`.+- Provedores locais retornando `404` para um modelo ausente.+- Falhas de permissão de modo/modelo específicas do provedor, como modos Grok selecionados.++O bloqueio de modelo vive em `open-sse/services/accountFallback.ts` e permite que a mesma+conexão continue atendendo outros modelos.++### Orientações para Depuração++- Se todas as chaves para um provedor forem puladas, inspecione tanto o estado do disjuntor do provedor quanto o `rateLimitedUntil`/`testStatus` de cada conexão.+- Se um provedor parecer permanentemente excluído após a janela de reset, verifique se o código+ está lendo o `state` bruto em vez de usar `getStatus()`/`canExecute()`.+- Se uma chave de provedor falhar, mas outras devem funcionar, prefira o cooldown de conexão em vez+ do disjuntor do provedor.+- Se apenas um modelo falhar, prefira o bloqueio de modelo em vez do cooldown de conexão.+- Se um estado deve se recuperar automaticamente, ele deve ter um timestamp futuro/tempo limite de reset e um+ caminho de leitura que atualiza o estado expirado. Status permanentes requerem mudanças manuais de credenciais+ ou configuração.++## Convenções Chave++### Estilo de Código++- **2 espaços**, ponto e vírgula, aspas duplas, largura de 100 caracteres, vírgulas finais ES5 (aplicadas pelo lint-staged via Prettier)+- **Imports**: externo → interno (`@/`, `@omniroute/open-sse`) → relativo+- **Nomeação**: arquivos=camelCase/kebab, componentes=PascalCase, constantes=UPPER_SNAKE+- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = erro em todo lugar; `no-explicit-any` = aviso em `open-sse/` e `tests/`+- **TypeScript**: `strict: false`, alvo ES2022, módulo esnext, resolução bundler. Preferir tipos explícitos.++### Banco de Dados++- **Sempre** passe pelos módulos de domínio em `src/lib/db/` — **nunca** escreva SQL bruto em rotas ou manipuladores+- **Nunca** adicione lógica em `src/lib/localDb.ts` (apenas camada de re-exportação)+- **Nunca** faça importação em lote de `localDb.ts` — importe módulos específicos de `db/` em vez disso+- Singleton de DB: `getDbInstance()` de `src/lib/db/core.ts` (journaling WAL)+- Migrações: `src/lib/db/migrations/` — arquivos SQL versionados, idempotentes, executados em transações++### Tratamento de Erros++- try/catch com tipos de erro específicos, registre com contexto pino+- Nunca oculte erros em streams SSE — use sinais de abortar para limpeza+- Retorne códigos de status HTTP apropriados (4xx/5xx)++### Segurança++- **Nunca** use `eval()`, `new Function()`, ou eval implícito+- Valide todas as entradas com esquemas Zod+- Criptografe credenciais em repouso (AES-256-GCM)+- Lista de negação de cabeçalhos upstream: `src/shared/constants/upstreamHeaders.ts` — mantenha a sanitização, esquemas Zod e testes unitários alinhados ao editar----## Testing Cheat Sheet+## Cenários Comuns de Modificação++### Adicionando um Novo Provedor++1. Registre em `src/shared/constants/providers.ts` (validado por Zod ao carregar)+2. Adicione executor em `open-sse/executors/` se lógica personalizada for necessária (estenda `BaseExecutor`)+3. Adicione tradutor em `open-sse/translator/` se formato não for OpenAI+4. Adicione configuração OAuth em `src/lib/oauth/constants/oauth.ts` se baseado em OAuth+5. Registre modelos em `open-sse/config/providerRegistry.ts`+6. Escreva testes em `tests/unit/`++### Adicionando uma Nova Rota de API++1. Crie diretório em `src/app/api/v1/sua-rota/`+2. Crie `route.ts` com manipuladores `GET`/`POST`+3. Siga o padrão: CORS → validação do corpo Zod → autenticação opcional → delegação de manipulador+4. O manipulador vai em `open-sse/handlers/` (importe de lá, não inline)+5. Adicione testes++### Adicionando um Novo Módulo de DB++1. Crie `src/lib/db/seuModulo.ts` — importe `getDbInstance` de `./core.ts`+2. Exporte funções CRUD para sua(s) tabela(s) de domínio+3. Adicione migração em `src/lib/db/migrations/` se novas tabelas forem necessárias+4. Re-exporte de `src/lib/localDb.ts` (adicione apenas à lista de re-exportação)+5. Escreva testes++### Adicionando uma Nova Ferramenta MCP++1. Adicione definição da ferramenta em `open-sse/mcp-server/tools/` com esquema de entrada Zod + manipulador assíncrono+2. Registre no conjunto de ferramentas (conectado por `createMcpServer()`)+3. Atribua aos escopos apropriados+4. Escreva testes (invocação da ferramenta registrada na tabela `mcp_audit`)++### Adicionando uma Nova Habilidade A2A++1. Crie habilidade em `src/lib/a2a/skills/` (5 já existem: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)+2. A habilidade recebe contexto de tarefa (mensagens, metadados) → retorna resultado estruturado+3. Registre em `A2A_SKILL_HANDLERS` em `src/lib/a2a/taskExecution.ts`+4. Exponha em `src/app/.well-known/agent.json/route.ts` (Cartão do Agente)+5. Escreva testes em `tests/unit/`+6. Documente na tabela de habilidades em `docs/frameworks/A2A-SERVER.md`++### Adicionando um Novo Agente de Nuvem++1. Crie classe de agente em `src/lib/cloudAgent/agents/` estendendo `CloudAgentBase` (3 já existem: codex-cloud, devin, jules)+2. Implemente `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`+3. Registre em `src/lib/cloudAgent/registry.ts`+4. Adicione tratamento de OAuth/credenciais se necessário (`src/lib/oauth/providers/`)+5. Testes + documente em `docs/frameworks/CLOUD_AGENT.md`++### Adicionando um Novo Guardrail / Eval / Habilidade / Evento de Webhook++- Guardrail: `src/lib/guardrails/` → docs: `docs/security/GUARDRAILS.md`+- Conjunto de Eval: `src/lib/evals/` → docs: `docs/frameworks/EVALS.md`+- Habilidade (sandbox): `src/lib/skills/` → docs: `docs/frameworks/SKILLS.md`+- Evento de Webhook: `src/lib/webhookDispatcher.ts` → docs: `docs/frameworks/WEBHOOKS.md`++## Documentação de Referência++Para qualquer alteração não trivial, leia primeiro a análise correspondente:++| Área | Documento |+| --------------------------------------------------- | ----------------------------------------------------------------- |+| Navegação no repositório | `docs/architecture/REPOSITORY_MAP.md` |+| Arquitetura | `docs/architecture/ARCHITECTURE.md` |+| Referência de engenharia | `docs/architecture/CODEBASE_DOCUMENTATION.md` |+| Auto-Combo (pontuação de 9 fatores, 14 estratégias) | `docs/routing/AUTO-COMBO.md` |+| Resiliência (3 mecanismos) | `docs/architecture/RESILIENCE_GUIDE.md` |+| Repetição de raciocínio | `docs/routing/REASONING_REPLAY.md` |+| Estrutura de habilidades | `docs/frameworks/SKILLS.md` |+| Sistema de memória (FTS5 + Qdrant) | `docs/frameworks/MEMORY.md` |+| Agentes de nuvem | `docs/frameworks/CLOUD_AGENT.md` |+| Guardrails (PII / injeção / visão) | `docs/security/GUARDRAILS.md` |+| Avaliações | `docs/frameworks/EVALS.md` |+| Conformidade / auditoria | `docs/security/COMPLIANCE.md` |+| Webhooks | `docs/frameworks/WEBHOOKS.md` |+| Pipeline de autorização | `docs/architecture/AUTHZ_GUIDE.md` |+| Stealth (TLS / impressão digital) | `docs/security/STEALTH_GUIDE.md` |+| Protocolos de agente (A2A / ACP / Nuvem) | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` |+| Servidor MCP | `docs/frameworks/MCP-SERVER.md` |+| Servidor A2A | `docs/frameworks/A2A-SERVER.md` |+| Referência de API + OpenAPI | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |+| Catálogo de provedores (gerado automaticamente) | `docs/reference/PROVIDER_REFERENCE.md` |+| Fluxo de lançamento | `docs/ops/RELEASE_CHECKLIST.md` |-| What | Command |-| ----------------------- | ------------------------------------------------------- |-| All tests | `npm run test:all` |-| Unit tests | `npm run test:unit` |-| Single file | `node --import tsx/esm --test tests/unit/file.test.mjs` |-| Vitest (MCP, autoCombo) | `npm run test:vitest` |-| E2E (Playwright) | `npm run test:e2e` |-| Protocol E2E (MCP+A2A) | `npm run test:protocols:e2e` |-| Ecosystem | `npm run test:ecosystem` |-| Coverage gate | `npm run test:coverage` (60% min all metrics) |-| Coverage report | `npm run coverage:report` |+----**PR rule**: If you change production code in `src/`, `open-sse/`, `electron/`, or `bin/`,-you must include or update tests in the same PR.+## Testes-**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.+| O que | Comando |+| ----------------------- | ------------------------------------------------------------------------------- |+| Testes unitários | `npm run test:unit` |+| Arquivo único | `node --import tsx/esm --test tests/unit/file.test.ts` |+| Vitest (MCP, autoCombo) | `npm run test:vitest` |+| E2E (Playwright) | `npm run test:e2e` |+| Protocolo E2E (MCP+A2A) | `npm run test:protocols:e2e` |+| Ecossistema | `npm run test:ecosystem` |+| Portão de cobertura | `npm run test:coverage` (75/75/75/70 — declarações/líneas/funções/ramificações) |+| Relatório de cobertura | `npm run coverage:report` |++**Regra de PR**: Se você alterar o código de produção em `src/`, `open-sse/`, `electron/` ou `bin/`, você deve incluir ou atualizar testes no mesmo PR.++**Preferência de camada de teste**: unitário primeiro → integração (multi-módulo ou estado do DB) → e2e (somente UI/workflow). Codifique reproduções de bugs como testes automatizados antes ou junto com a correção.++**Política de cobertura do Copilot**: Quando um PR altera o código de produção e a cobertura está abaixo de 75% (declarações/líneas/funções) ou 70% (ramificações), não apenas relate — adicione ou atualize testes, reexecute o portão de cobertura e, em seguida, peça confirmação. Inclua comandos executados, arquivos de teste alterados e o resultado final da cobertura no relatório do PR.----## Git Workflow+## Fluxo de Trabalho do Git```bash-# Never commit directly to main-git checkout -b feat/your-feature-# ... make changes ...-git commit -m "feat: describe your change"-git push -u origin feat/your-feature+# Nunca faça commit diretamente no main+git checkout -b feat/sua-funcionalidade+git commit -m "feat: descreva sua alteração"+git push -u origin feat/sua-funcionalidade```-**Branch prefixes**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`+**Prefixos de branch**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`-**Commit format** ([Conventional Commits](https://www.conventionalcommits.org/)):+**Formato de commit** (Commits Convencionais): `feat(db): adicionar circuito de interrupção` — escopos: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`-```-feat: add circuit breaker for provider calls-fix: resolve JWT secret validation edge case-docs: update AGENTS.md with pipeline internals-test: add MCP tool unit tests-refactor(db): consolidate rate limit tables-```+**Ganchos do Husky**:-**Scopes**: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`,-`memory`, `skills`.+- **pre-commit**: lint-staged + `check-docs-sync` + `check:any-budget:t11`+- **pre-push**: `npm run test:unit`----## Environment+## Ambiente-- **Runtime**: Node.js ≥18 <24, ES Modules-- **TypeScript**: 5.9, target ES2022, module esnext, resolution bundler-- **Path aliases**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`-- **Default port**: 20128 (API + dashboard on same port)-- **Data directory**: `DATA_DIR` env var, defaults to `~/.omniroute/`-- **Key env vars**: `PORT`, `JWT_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`+- **Tempo de Execução**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Módulos ES+- **TypeScript**: 5.9+, alvo ES2022, módulo esnext, resolução bundler+- **Aliases de caminho**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`+- **Porta padrão**: 20128 (API + dashboard na mesma porta)+- **Diretório de dados**: variável de ambiente `DATA_DIR`, padrão para `~/.omniroute/`+- **Principais variáveis de ambiente**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`+- Configuração: `cp .env.example .env` e então gere `JWT_SECRET` (`openssl rand -base64 48`) e `API_KEY_SECRET` (`openssl rand -hex 32`)----## Hard Rules (Never Violate)--1. Never commit secrets or credentials-2. Never add logic to `localDb.ts`-3. Never use `eval()` / `new Function()` / implied eval-4. Never commit directly to `main`-5. Never write raw SQL in routes — use `src/lib/db/` modules-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)+## Regras Estritas++1. Nunca faça commit de segredos ou credenciais+2. Nunca adicione lógica ao `localDb.ts`+3. Nunca use `eval()` / `new Function()` / eval implícito+4. Nunca faça commit diretamente no `main`+5. Nunca escreva SQL bruto em rotas — use módulos `src/lib/db/`+6. Nunca silenciosamente ignore erros em streams SSE+7. Sempre valide entradas com esquemas Zod+8. Sempre inclua testes ao alterar código de produção+9. A cobertura deve permanecer ≥75% (declarações, linhas, funções) / ≥70% (ramificações). Medido atualmente: ~82%.+10. Nunca contorne ganchos do Husky (`--no-verify`, `--no-gpg-sign`) sem aprovação explícita do operador.diff --git a/docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md b/docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.mdindex 25f8bca167..fca0451441 100644--- a/docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md+++ b/docs/i18n/pt-BR/docs/architecture/ARCHITECTURE.md@@ -1,149 +1,185 @@# OmniRoute Architecture (Português (Brasil))-🌐 **Languages:** 🇺🇸 [English](../../../../docs/ARCHITECTURE.md) · 🇸🇦 [ar](../../ar/docs/ARCHITECTURE.md) · 🇧🇬 [bg](../../bg/docs/ARCHITECTURE.md) · 🇧🇩 [bn](../../bn/docs/ARCHITECTURE.md) · 🇨🇿 [cs](../../cs/docs/ARCHITECTURE.md) · 🇩🇰 [da](../../da/docs/ARCHITECTURE.md) · 🇩🇪 [de](../../de/docs/ARCHITECTURE.md) · 🇪🇸 [es](../../es/docs/ARCHITECTURE.md) · 🇮🇷 [fa](../../fa/docs/ARCHITECTURE.md) · 🇫🇮 [fi](../../fi/docs/ARCHITECTURE.md) · 🇫🇷 [fr](../../fr/docs/ARCHITECTURE.md) · 🇮🇳 [gu](../../gu/docs/ARCHITECTURE.md) · 🇮🇱 [he](../../he/docs/ARCHITECTURE.md) · 🇮🇳 [hi](../../hi/docs/ARCHITECTURE.md) · 🇭🇺 [hu](../../hu/docs/ARCHITECTURE.md) · 🇮🇩 [id](../../id/docs/ARCHITECTURE.md) · 🇮🇹 [it](../../it/docs/ARCHITECTURE.md) · 🇯🇵 [ja](../../ja/docs/ARCHITECTURE.md) · 🇰🇷 [ko](../../ko/docs/ARCHITECTURE.md) · 🇮🇳 [mr](../../mr/docs/ARCHITECTURE.md) · 🇲🇾 [ms](../../ms/docs/ARCHITECTURE.md) · 🇳🇱 [nl](../../nl/docs/ARCHITECTURE.md) · 🇳🇴 [no](../../no/docs/ARCHITECTURE.md) · 🇵🇭 [phi](../../phi/docs/ARCHITECTURE.md) · 🇵🇱 [pl](../../pl/docs/ARCHITECTURE.md) · 🇵🇹 [pt](../../pt/docs/ARCHITECTURE.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) · 🇷🇴 [ro](../../ro/docs/ARCHITECTURE.md) · 🇷🇺 [ru](../../ru/docs/ARCHITECTURE.md) · 🇸🇰 [sk](../../sk/docs/ARCHITECTURE.md) · 🇸🇪 [sv](../../sv/docs/ARCHITECTURE.md) · 🇰🇪 [sw](../../sw/docs/ARCHITECTURE.md) · 🇮🇳 [ta](../../ta/docs/ARCHITECTURE.md) · 🇮🇳 [te](../../te/docs/ARCHITECTURE.md) · 🇹🇭 [th](../../th/docs/ARCHITECTURE.md) · 🇹🇷 [tr](../../tr/docs/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) · 🇵🇰 [ur](../../ur/docs/ARCHITECTURE.md) · 🇻🇳 [vi](../../vi/docs/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/ARCHITECTURE.md)+🌐 **Languages:** 🇺🇸 [English](../../../../architecture/ARCHITECTURE.md) · 🇸🇦 [ar](../../../ar/docs/architecture/ARCHITECTURE.md) · 🇧🇬 [bg](../../../bg/docs/architecture/ARCHITECTURE.md) · 🇧🇩 [bn](../../../bn/docs/architecture/ARCHITECTURE.md) · 🇨🇿 [cs](../../../cs/docs/architecture/ARCHITECTURE.md) · 🇩🇰 [da](../../../da/docs/architecture/ARCHITECTURE.md) · 🇩🇪 [de](../../../de/docs/architecture/ARCHITECTURE.md) · 🇪🇸 [es](../../../es/docs/architecture/ARCHITECTURE.md) · 🇮🇷 [fa](../../../fa/docs/architecture/ARCHITECTURE.md) · 🇫🇮 [fi](../../../fi/docs/architecture/ARCHITECTURE.md) · 🇫🇷 [fr](../../../fr/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [gu](../../../gu/docs/architecture/ARCHITECTURE.md) · 🇮🇱 [he](../../../he/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [hi](../../../hi/docs/architecture/ARCHITECTURE.md) · 🇭🇺 [hu](../../../hu/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [id](../../../id/docs/architecture/ARCHITECTURE.md) · 🇮🇩 [in](../../../in/docs/architecture/ARCHITECTURE.md) · 🇮🇹 [it](../../../it/docs/architecture/ARCHITECTURE.md) · 🇯🇵 [ja](../../../ja/docs/architecture/ARCHITECTURE.md) · 🇰🇷 [ko](../../../ko/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [mr](../../../mr/docs/architecture/ARCHITECTURE.md) · 🇲🇾 [ms](../../../ms/docs/architecture/ARCHITECTURE.md) · 🇳🇱 [nl](../../../nl/docs/architecture/ARCHITECTURE.md) · 🇳🇴 [no](../../../no/docs/architecture/ARCHITECTURE.md) · 🇵🇭 [phi](../../../phi/docs/architecture/ARCHITECTURE.md) · 🇵🇱 [pl](../../../pl/docs/architecture/ARCHITECTURE.md) · 🇵🇹 [pt](../../../pt/docs/architecture/ARCHITECTURE.md) · 🇷🇴 [ro](../../../ro/docs/architecture/ARCHITECTURE.md) · 🇷🇺 [ru](../../../ru/docs/architecture/ARCHITECTURE.md) · 🇸🇰 [sk](../../../sk/docs/architecture/ARCHITECTURE.md) · 🇸🇪 [sv](../../../sv/docs/architecture/ARCHITECTURE.md) · 🇰🇪 [sw](../../../sw/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [ta](../../../ta/docs/architecture/ARCHITECTURE.md) · 🇮🇳 [te](../../../te/docs/architecture/ARCHITECTURE.md) · 🇹🇭 [th](../../../th/docs/architecture/ARCHITECTURE.md) · 🇹🇷 [tr](../../../tr/docs/architecture/ARCHITECTURE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/ARCHITECTURE.md) · 🇵🇰 [ur](../../../ur/docs/architecture/ARCHITECTURE.md) · 🇻🇳 [vi](../../../vi/docs/architecture/ARCHITECTURE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/ARCHITECTURE.md)----_Last updated: 2026-04-15_--## Executive Summary--OmniRoute is a local AI routing gateway and dashboard built on Next.js.-It provides a single OpenAI-compatible endpoint (`/v1/*`) and routes traffic across multiple upstream providers with translation, fallback, token refresh, and usage tracking.--Core capabilities:--- OpenAI-compatible API surface for CLI/tools (100+ providers, 16 executors)-- Request/response translation across provider formats-- Model combo fallback (multi-model sequence)-- Structured combo steps (`provider + model + connection`) with runtime ordering by `compositeTiers`-- Account-level fallback (multi-account per provider)-- Quota preflight and quota-aware P2C account selection in the main chat path-- OAuth + API-key provider connection management (13 OAuth modules)-- Embedding generation via `/v1/embeddings` (6 providers, 9 models)-- Image generation via `/v1/images/generations` (10+ providers, 20+ models)-- Audio transcription via `/v1/audio/transcriptions` (7 providers)-- Text-to-speech via `/v1/audio/speech` (10 providers)-- Video generation via `/v1/videos/generations` (ComfyUI + SD WebUI)-- Music generation via `/v1/music/generations` (ComfyUI)-- Web search via `/v1/search` (5 providers)-- Moderations via `/v1/moderations`-- Reranking via `/v1/rerank`-- Think tag parsing (`<think>...</think>`) for reasoning models-- Response sanitization for strict OpenAI SDK compatibility-- Role normalization (developer→system, system→user) for cross-provider compatibility-- Structured output conversion (json_schema → Gemini responseSchema)-- Local persistence for providers, keys, aliases, combos, settings, pricing (26 DB modules)-- Usage/cost tracking and request logging-- Optional cloud sync for multi-device/state sync-- IP allowlist/blocklist for API access control-- Thinking budget management (passthrough/auto/custom/adaptive)-- Global system prompt injection-- Session tracking and fingerprinting-- Per-account enhanced rate limiting with provider-specific profiles-- Circuit breaker pattern for provider resilience-- Anti-thundering herd protection with mutex locking-- Signature-based request deduplication cache-- Domain layer: cost rules, fallback policy, lockout policy-- Context Relay: session handoff summaries for account rotation continuity-- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers)-- Policy engine for centralized request evaluation (lockout → budget → fallback)-- Request telemetry with p50/p95/p99 latency aggregation-- Combo target telemetry and historical combo target health via `combo_execution_key` / `combo_step_id`-- Correlation ID (X-Request-Id) for end-to-end tracing-- Compliance audit logging with opt-out per API key-- Eval framework for LLM quality assurance-- Health dashboard with real-time provider circuit breaker status-- MCP Server (25 tools) with 3 transports (stdio/SSE/Streamable HTTP)-- A2A Server (JSON-RPC 2.0 + SSE) with skills and task lifecycle-- Memory system (extraction, injection, retrieval, summarization)-- Skills system (registry, executor, sandbox, built-in skills)-- MITM proxy with certificate management and DNS handling-- Prompt injection guard middleware-- ACP (Agent Communication Protocol) registry-- Modular OAuth providers (13 individual modules under `src/lib/oauth/providers/`)-- Uninstall/full-uninstall scripts-- OAuth environment repair action-- WebSocket bridge for OpenAI-compatible WS clients (`/v1/ws`)-- Sync token management (issue/revoke, ETag-versioned config bundle download)-- GLM Thinking (`glmt`) first-class provider preset-- Hybrid token counting (provider-side `/messages/count_tokens` with estimation fallback)-- Model alias auto-seeding (30+ cross-proxy dialect normalizations at startup)-- Safe outbound fetch with SSRF guard, private URL blocking, and configurable retry-- Cooldown-aware chat retries with configurable `requestRetry` and `maxRetryIntervalSec`-- Runtime environment validation with Zod at startup-- Compliance audit v2 with pagination, provider CRUD events, and SSRF-blocked validation logging--Primary runtime model:--- Next.js app routes under `src/app/api/*` implement both dashboard APIs and compatibility APIs-- A shared SSE/routing core in `src/sse/*` + `open-sse/*` handles provider execution, translation, streaming, fallback, and usage--## Scope and Boundaries--### In Scope--- Local gateway runtime-- Dashboard management APIs-- Provider authentication and token refresh-- Request translation and SSE streaming-- Local state + usage persistence-- Optional cloud sync orchestration--### Out of Scope--- Cloud service implementation behind `NEXT_PUBLIC_CLOUD_URL`-- Provider SLA/control plane outside local process-- External CLI binaries themselves (Claude CLI, Codex CLI, etc.)--## Dashboard Surface (Current)--Main pages under `src/app/(dashboard)/dashboard/`:--- `/dashboard` — quick start + provider overview-- `/dashboard/endpoint` — endpoint proxy + MCP + A2A + API endpoint tabs-- `/dashboard/providers` — provider connections and credentials-- `/dashboard/combos` — combo strategies, templates, step-based builder, model routing rules, manual persisted ordering-- `/dashboard/costs` — cost aggregation and pricing visibility-- `/dashboard/analytics` — usage analytics, evaluations, combo target health-- `/dashboard/limits` — quota/rate controls-- `/dashboard/cli-tools` — CLI onboarding, runtime detection, config generation-- `/dashboard/agents` — detected ACP agents + custom agent registration-- `/dashboard/media` — image/video/music playground-- `/dashboard/search-tools` — search provider testing and history-- `/dashboard/health` — uptime, circuit breakers, rate limits, quota-monitored sessions-- `/dashboard/logs` — request/proxy/audit/console logs-- `/dashboard/settings` — system settings tabs (general, routing, combo defaults, etc.)-- `/dashboard/api-manager` — API key lifecycle and model permissions--## High-Level System Context+🌐 **Idiomas:** 🇺🇸 [English](./ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](i18n/es/ARCHITECTURE.md) | 🇫🇷 [Français](i18n/fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](i18n/it/ARCHITECTURE.md) | 🇷🇺 [Русский](i18n/ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](i18n/zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](i18n/de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](i18n/in/ARCHITECTURE.md) | 🇹🇭 [ไทย](i18n/th/ARCHITECTURE.md) | 🇺🇦 [Українська](i18n/uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](i18n/ar/ARCHITECTURE.md) | 🇯🇵 [日本語](i18n/ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](i18n/vi/ARCHITECTURE.md) | 🇧🇬 [Български](i18n/bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](i18n/da/ARCHITECTURE.md) | 🇫🇮 [Suomi](i18n/fi/ARCHITECTURE.md) | 🇮🇱 [עברית](i18n/he/ARCHITECTURE.md) | 🇭🇺 [Magyar](i18n/hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | 🇰🇷 [한국어](i18n/ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](i18n/nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](i18n/no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](i18n/pt/ARCHITECTURE.md) | 🇷🇴 [Română](i18n/ro/ARCHITECTURE.md) | 🇵🇱 [Polski](i18n/pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](i18n/sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](i18n/sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](i18n/phi/ARCHITECTURE.md) | 🇨🇿 [Čeština](i18n/cs/ARCHITECTURE.md)++_Última atualização: 2026-05-13_++## Resumo Executivo++OmniRoute é um gateway de roteamento de IA local e um painel construído em Next.js.+Ele fornece um único endpoint compatível com OpenAI (`/v1/*`) e roteia o tráfego entre vários provedores upstream com tradução, fallback, atualização de token e rastreamento de uso.++Capacidades principais:++- Superfície de API compatível com OpenAI para CLI/ferramentas (179 provedores, 31 executores)+- Tradução de solicitação/resposta entre formatos de provedores+- Fallback de combinação de modelos (sequência de múltiplos modelos)+- Etapas de combinação estruturadas (`provedor + modelo + conexão`) com ordenação em tempo de execução por `compositeTiers`+- Fallback em nível de conta (múltiplas contas por provedor)+- Pré-verificação de cota e seleção de conta P2C ciente da cota no caminho principal de chat+- Gerenciamento de conexão de provedor OAuth + chave de API (14 módulos OAuth)+- Geração de embeddings via `/v1/embeddings` (6 provedores, 9 modelos)+- Geração de imagens via `/v1/images/generations` (10+ provedores, 20+ modelos)+- Transcrição de áudio via `/v1/audio/transcriptions` (7 provedores)+- Texto para fala via `/v1/audio/speech` (10 provedores)+- Geração de vídeo via `/v1/videos/generations` (ComfyUI + SD WebUI)+- Geração de música via `/v1/music/generations` (ComfyUI)+- Pesquisa na web via `/v1/search` (5 provedores)+- Moderações via `/v1/moderations`+- Reclassificação via `/v1/rerank`+- Análise de tags de pensamento (``) para modelos de raciocínio+- Sanitização de resposta para compatibilidade estrita com o SDK da OpenAI+- Normalização de papéis (desenvolvedor→sistema, sistema→usuário) para compatibilidade entre provedores+- Conversão de saída estruturada (json_schema → Gemini responseSchema)+- Persistência local para provedores, chaves, aliases, combos, configurações, preços (26 módulos de DB)+- Rastreamento de uso/custo e registro de solicitações+- Sincronização em nuvem opcional para sincronização de múltiplos dispositivos/estados+- Lista de permissão/bloqueio de IP para controle de acesso à API+- Gerenciamento de orçamento de pensamento (passagem/automático/customizado/adaptativo)+- Injeção de prompt global+- Rastreamento de sessão e identificação+- Limitação de taxa aprimorada por conta com perfis específicos de provedores+- Padrão de disjuntor para resiliência do provedor+- Proteção contra rebanho de trovão com bloqueio de mutex+- Cache de deduplicação de solicitação baseado em assinatura+- Camada de domínio: regras de custo, política de fallback, política de bloqueio+- Context Relay: resumos de transferência de sessão para continuidade de rotação de conta+- Persistência de estado de domínio (cache de gravação SQLite para fallbacks, orçamentos, bloqueios, disjuntores)+- Motor de políticas para avaliação centralizada de solicitações (bloqueio → orçamento → fallback)+- Telemetria de solicitação com agregação de latência p50/p95/p99+- Telemetria de alvo de combo e saúde histórica do alvo de combo via `combo_execution_key` / `combo_step_id`+- ID de correlação (X-Request-Id) para rastreamento de ponta a ponta+- Registro de auditoria de conformidade com opção de exclusão por chave de API+- Framework de avaliação para garantia de qualidade de LLM+- Painel de saúde com status de disjuntor de provedor em tempo real+- Servidor MCP (37 ferramentas) com 3 transportes (stdio/SSE/Streamable HTTP)+- Servidor A2A (JSON-RPC 2.0 + SSE) com habilidades e ciclo de vida de tarefas+- Sistema de memória (extração, injeção, recuperação, sumarização)+- Sistema de habilidades (registro, executor, sandbox, habilidades integradas)+- Proxy MITM com gerenciamento de certificados e manipulação de DNS+- Middleware de proteção contra injeção de prompt+- Pipeline de compressão de prompt com Caveman, RTK, pipelines empilhados, combos de compressão, pacotes de idiomas e análises+- Registro de ACP (Agent Communication Protocol)+- Provedores OAuth modulares (14 módulos individuais sob `src/lib/oauth/providers/`)+- Scripts de desinstalação/desinstalação completa+- Ação de reparo de ambiente OAuth+- Ponte WebSocket para clientes WS compatíveis com OpenAI (`/v1/ws`)+- Gerenciamento de token de sincronização (emissão/revogação, download de pacote de configuração versionado por ETag)+- Pensamento GLM (`glmt`) como preset de provedor de primeira classe+- Contagem de tokens híbrida (contagem de tokens do lado do provedor `/messages/count_tokens` com fallback de estimativa)+- Auto-semeadura de alias de modelo (30+ normalizações de dialeto cross-proxy na inicialização)+- Busca segura de saída com proteção SSRF, bloqueio de URL privada e retry configurável+- Repetições de chat cientes de cooldown com `requestRetry` e `maxRetryIntervalSec` configuráveis+- Validação do ambiente de execução com Zod na inicialização+- Auditoria de conformidade v2 com paginação, eventos CRUD de provedores e registro de validação bloqueada por SSRF++Modelo de execução principal:++- Rotas de aplicativo Next.js sob `src/app/api/*` implementam tanto APIs de painel quanto APIs de compatibilidade+- Um núcleo compartilhado de SSE/roteamento em `src/sse/*` + `open-sse/*` lida com execução de provedores, tradução, streaming, fallback e uso++## Diagramas de Referência++Fontes canônicas e controladas por versão do Mermaid para a plataforma v3.8.0 estão disponíveis em+[`docs/diagrams/`](../diagrams/README.md). Dois são reproduzidos abaixo para orientação;+os demais estão vinculados a seus guias específicos de domínio.++++> Fonte: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)++++> Fonte: [diagrams/resilience-3layers.mmd](../diagrams/resilience-3layers.mmd) — também vinculado a+> [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) e à referência de resiliência `CLAUDE.md`.++## Escopo e Limites++### Dentro do Escopo++- Tempo de execução do gateway local+- APIs de gerenciamento do painel+- Autenticação de provedor e atualização de token+- Tradução de requisições e streaming SSE+- Persistência de estado local + uso+- Orquestração opcional de sincronização em nuvem++### Fora do Escopo++- Implementação de serviço em nuvem por trás de `NEXT_PUBLIC_CLOUD_URL`+- SLA do provedor/plano de controle fora do processo local+- Binaries de CLI externas (Claude CLI, Codex CLI, etc.)++## Superfície do Painel (Atual)++Páginas principais em `src/app/(dashboard)/dashboard/`:++- `/dashboard` — início rápido + visão geral do provedor+- `/dashboard/endpoint` — proxy de endpoint + MCP + A2A + abas de endpoint API+- `/dashboard/providers` — conexões e credenciais do provedor+- `/dashboard/combos` — estratégias de combo, templates, construtor baseado em etapas, regras de roteamento de modelo, ordenação persistida manual+- `/dashboard/auto-combo` — Motor de Auto Combo: pesos de pontuação, pacotes de modo, predefinições de fábrica virtual, telemetria+- `/dashboard/costs` — agregação de custos e visibilidade de preços+- `/dashboard/analytics` — análises de uso, avaliações, saúde do alvo do combo+- `/dashboard/limits` — controles de cota/taxa+- `/dashboard/cli-tools` — integração de CLI, detecção de tempo de execução, geração de configuração+- `/dashboard/agents` — agentes ACP detectados + registro de agente personalizado+- `/dashboard/cloud-agents` — tarefas de agente hospedadas na nuvem (Codex Cloud, Devin, Jules) e ciclo de vida da tarefa+- `/dashboard/skills` — registro de habilidades A2A, execução em sandbox, catálogo de habilidades embutido+- `/dashboard/memory` — inspeção e recuperação de memória conversacional persistente+- `/dashboard/webhooks` — assinaturas de webhook de saída, rotação de segredos, estatísticas de tentativas+- `/dashboard/batch` — submissão de trabalhos em lote e progresso+- `/dashboard/cache` — estatísticas de cache de leitura e raciocínio, controles de expulsão+- `/dashboard/playground` — playground de chat interativo contra qualquer combo/modelo configurado+- `/dashboard/changelog` — visualizador de changelog no aplicativo (renderiza `CHANGELOG.md`)+- `/dashboard/system` — diagnósticos de tempo de execução, informações de versão, superfície de validação de ambiente+- `/dashboard/onboarding` — assistente de configuração de primeira execução para novas instalações+- `/dashboard/media` — playground de imagem/vídeo/música+- `/dashboard/search-tools` — teste de provedor de busca e histórico+- `/dashboard/health` — tempo de atividade, disjuntores, limites de taxa, sessões monitoradas por cota+- `/dashboard/logs` — logs de requisição/proxy/auditoria/console+- `/dashboard/settings` — abas de configurações do sistema (geral, roteamento, padrões de combo, etc.)+- `/dashboard/context/caveman` — regras de compressão Caveman, pacotes de idioma, visualização e modo de saída+- `/dashboard/context/rtk` — filtros de saída de comando RTK, visualização e configurações de segurança em tempo de execução+- `/dashboard/context/combos` — pipelines de compressão nomeados atribuídos a combos de roteamento+- `/dashboard/translator` — inspeção de tradutor e visualização de conversão de formato de requisição+- `/dashboard/audit` — navegador de log de auditoria de conformidade com paginação e metadados estruturados+- `/dashboard/usage` — navegador de uso por requisição vinculado a `usage_history`+- `/dashboard/compression` — análises de compressão, estatísticas e atribuição de pipeline+- `/dashboard/api-manager` — ciclo de vida da chave API e permissões de modelo++## Contexto do Sistema em Alto Nível```mermaidflowchart LR- subgraph Clients[Developer Clients]+ subgraph Clients[Clientes Desenvolvedores]C1[Claude Code]C2[Codex CLI]C3[OpenClaw / Droid / Cline / Continue / Roo]- C4[Custom OpenAI-compatible clients]- BROWSER[Browser Dashboard]+ C4[Clientes personalizados compatíveis com OpenAI]+ BROWSER[Dashboard do Navegador]end- subgraph Router[OmniRoute Local Process]- API[V1 Compatibility API\n/v1/*]- DASH[Dashboard + Management API\n/api/*]- CORE[SSE + Translation Core\nopen-sse + src/sse]+ subgraph Router[Processo Local OmniRoute]+ API[V1 API de Compatibilidade\n/v1/*]+ DASH[Dashboard + API de Gerenciamento\n/api/*]+ CORE[Núcleo SSE + Tradução\nopen-sse + src/sse]DB[(storage.sqlite)]- UDB[(usage tables + log artifacts)]+ UDB[(tabelas de uso + artefatos de log)]end- subgraph Upstreams[Upstream Providers]- P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/GitHub/Kiro/Cursor/Antigravity]- P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]- P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible]+ subgraph Upstreams[Provedores Upstream]+ P1[Provedores OAuth\nClaude/Codex/Gemini/Qwen/Qoder/GitHub/Kiro/Cursor/Antigravity]+ P2[Provedores de Chave de API\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA]+ P3[Nós Compatíveis\ncompatíveis com OpenAI / compatíveis com Anthropic]end- subgraph Cloud[Optional Cloud Sync]- CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL]+ subgraph Cloud[Sincronização em Nuvem Opcional]+ CLOUD[Ponto de Sincronização em Nuvem\nNEXT_PUBLIC_CLOUD_URL]endC1 --> API@@ -164,168 +200,331 @@ flowchart LRDASH --> CLOUD```-## Core Runtime Components+## Componentes Centrais de Execução-## 1) API and Routing Layer (Next.js App Routes)+## 1) Camada de API e Roteamento (Rotas do App Next.js)-Main directories:+Diretórios principais:-- `src/app/api/v1/*` and `src/app/api/v1beta/*` for compatibility APIs-- `src/app/api/*` for management/configuration APIs-- Next rewrites in `next.config.mjs` map `/v1/*` to `/api/v1/*`+- `src/app/api/v1/*` e `src/app/api/v1beta/*` para APIs de compatibilidade+- `src/app/api/*` para APIs de gerenciamento/configuração+- Reescritas do Next em `next.config.mjs` mapeiam `/v1/*` para `/api/v1/*`-Important compatibility routes:+Rotas de compatibilidade importantes:- `src/app/api/v1/chat/completions/route.ts`- `src/app/api/v1/messages/route.ts`- `src/app/api/v1/responses/route.ts`-- `src/app/api/v1/models/route.ts` — includes custom models with `custom: true`-- `src/app/api/v1/embeddings/route.ts` — embedding generation (6 providers)-- `src/app/api/v1/images/generations/route.ts` — image generation (4+ providers incl. Antigravity/Nebius)+- `src/app/api/v1/models/route.ts` — inclui modelos personalizados com `custom: true`+- `src/app/api/v1/embeddings/route.ts` — geração de embeddings (6 provedores)+- `src/app/api/v1/images/generations/route.ts` — geração de imagens (4+ provedores, incluindo Antigravity/Nebius)- `src/app/api/v1/messages/count_tokens/route.ts`-- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — dedicated per-provider chat-- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — dedicated per-provider embeddings-- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — dedicated per-provider images+- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dedicado por provedor+- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — embeddings dedicados por provedor+- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagens dedicadas por provedor- `src/app/api/v1beta/models/route.ts`- `src/app/api/v1beta/models/[...path]/route.ts`-Management domains:+Domínios de gerenciamento:-- Auth/settings: `src/app/api/auth/*`, `src/app/api/settings/*`-- Providers/connections: `src/app/api/providers*`-- Provider nodes: `src/app/api/provider-nodes*`-- Custom models: `src/app/api/provider-models` (GET/POST/DELETE)-- Model catalog: `src/app/api/models/route.ts` (GET)-- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)+- Auth/configurações: `src/app/api/auth/*`, `src/app/api/settings/*`+- Provedores/conexões: `src/app/api/providers*`+- Nós de provedores: `src/app/api/provider-nodes*`+- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE)+- Catálogo de modelos: `src/app/api/models/route.ts` (GET)+- Configuração de proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST)- OAuth: `src/app/api/oauth/*`-- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`-- Usage: `src/app/api/usage/*`-- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*`-- CLI tooling helpers: `src/app/api/cli-tools/*`-- IP filter: `src/app/api/settings/ip-filter` (GET/PUT)-- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT)-- System prompt: `src/app/api/settings/system-prompt` (GET/PUT)-- Sessions: `src/app/api/sessions` (GET)-- Rate limits: `src/app/api/rate-limits` (GET)-- Resilience: `src/app/api/resilience` (GET/PATCH) — request queue, connection cooldown, provider breaker, wait-for-cooldown config-- Resilience reset: `src/app/api/resilience/reset` (POST) — reset provider breakers-- Cache stats: `src/app/api/cache/stats` (GET/DELETE)-- Telemetry: `src/app/api/telemetry/summary` (GET)-- Budget: `src/app/api/usage/budget` (GET/POST)-- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE)-- Compliance audit: `src/app/api/compliance/audit-log` (GET, with pagination + structured metadata)+- Chaves/aliases/combos/preços: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing`+- Uso: `src/app/api/usage/*`+- Sincronização/nuvem: `src/app/api/sync/*`, `src/app/api/cloud/*`+- Ferramentas auxiliares de CLI: `src/app/api/cli-tools/*`+- Filtro de IP: `src/app/api/settings/ip-filter` (GET/PUT)+- Orçamento de pensamento: `src/app/api/settings/thinking-budget` (GET/PUT)+- Prompt do sistema: `src/app/api/settings/system-prompt` (GET/PUT)+- Compressão: `src/app/api/settings/compression`, `src/app/api/compression/*`, e+ `src/app/api/context/*`+- Sessões: `src/app/api/sessions` (GET)+- Limites de taxa: `src/app/api/rate-limits` (GET)+- Resiliência: `src/app/api/resilience` (GET/PATCH) — fila de requisições, cooldown de conexão, breaker de provedor, configuração de espera por cooldown+- Reset de resiliência: `src/app/api/resilience/reset` (POST) — resetar breakers de provedores+- Estatísticas de cache: `src/app/api/cache/stats` (GET/DELETE)+- Telemetria: `src/app/api/telemetry/summary` (GET)+- Orçamento: `src/app/api/usage/budget` (GET/POST)+- Cadeias de fallback: `src/app/api/fallback/chains` (GET/POST/DELETE)+- Auditoria de conformidade: `src/app/api/compliance/audit-log` (GET, com paginação + metadados estruturados)- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET)-- Policies: `src/app/api/policies` (GET/POST)-- Sync tokens: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)-- Config bundle: `src/app/api/sync/bundle` (GET, ETag-versioned snapshot of settings/providers/combos/keys)-- WebSocket: `src/app/api/v1/ws/route.ts` — Upgrade handler for OpenAI-compatible WS clients--## 2) SSE + Translation Core--Main flow modules:--- Entry: `src/sse/handlers/chat.ts`-- Core orchestration: `open-sse/handlers/chatCore.ts`-- Provider execution adapters: `open-sse/executors/*`-- Format detection/provider config: `open-sse/services/provider.ts`-- Model parse/resolve: `src/sse/services/model.ts`, `open-sse/services/model.ts`-- Account fallback logic: `open-sse/services/accountFallback.ts`-- Translation registry: `open-sse/translator/index.ts`-- Stream transformations: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`-- Usage extraction/normalization: `open-sse/utils/usageTracking.ts`-- Think tag parser: `open-sse/utils/thinkTagParser.ts`-- Embedding handler: `open-sse/handlers/embeddings.ts`-- Embedding provider registry: `open-sse/config/embeddingRegistry.ts`-- Image generation handler: `open-sse/handlers/imageGeneration.ts`-- Image provider registry: `open-sse/config/imageRegistry.ts`-- Response sanitization: `open-sse/handlers/responseSanitizer.ts`-- Role normalization: `open-sse/services/roleNormalizer.ts`--Services (business logic):--- Account selection/scoring: `open-sse/services/accountSelector.ts`-- Context lifecycle management: `open-sse/services/contextManager.ts`-- IP filter enforcement: `open-sse/services/ipFilter.ts`-- Session tracking: `open-sse/services/sessionManager.ts`-- Request deduplication: `open-sse/services/signatureCache.ts`-- System prompt injection: `open-sse/services/systemPrompt.ts`-- Thinking budget management: `open-sse/services/thinkingBudget.ts`-- Wildcard model routing: `open-sse/services/wildcardRouter.ts`-- Rate limit management: `open-sse/services/rateLimitManager.ts`-- Circuit breaker: `open-sse/services/circuitBreaker.ts`-- Context handoff: `open-sse/services/contextHandoff.ts` — handoff summary generation and injection for context-relay strategy-- Codex quota fetcher: `open-sse/services/codexQuotaFetcher.ts` — fetches Codex quota for context-relay handoff decisions-- Cooldown-aware retry: `src/sse/services/cooldownAwareRetry.ts` — per-model cooldown retries with configurable `requestRetry` / `maxRetryIntervalSec`-- Safe outbound fetch: `src/shared/network/safeOutboundFetch.ts` — guarded provider/model fetch with SSRF guard, private-URL blocking, retry, and timeout-- Outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — validates provider URLs against private/localhost CIDR ranges-- Provider request defaults: `open-sse/services/providerRequestDefaults.ts` — provider-level `maxTokens`, `temperature`, `thinkingBudgetTokens` defaults-- GLM provider constants: `open-sse/config/glmProvider.ts` — shared GLM models, quota URLs, GLMT timeout/defaults-- Antigravity upstream: `open-sse/config/antigravityUpstream.ts` — base URL and discovery path constants-- Codex client constants: `open-sse/config/codexClient.ts` — versioned user-agent and client-version values-- Model alias seed: `src/lib/modelAliasSeed.ts` — seeds 30+ cross-proxy dialect aliases at startup--Domain layer modules:--- Cost rules/budgets: `src/lib/domain/costRules.ts`-- Fallback policy: `src/lib/domain/fallbackPolicy.ts`-- Combo resolver: `src/lib/domain/comboResolver.ts`-- Lockout policy: `src/lib/domain/lockoutPolicy.ts`-- Policy engine: `src/domain/policyEngine.ts` — centralized lockout → budget → fallback evaluation-- Error codes catalog: `src/lib/domain/errorCodes.ts`-- Request ID: `src/lib/domain/requestId.ts`-- Fetch timeout: `src/lib/domain/fetchTimeout.ts`-- Request telemetry: `src/lib/domain/requestTelemetry.ts`-- Compliance/audit: `src/lib/domain/compliance/index.ts`-- Eval runner: `src/lib/domain/evalRunner.ts`-- Domain state persistence: `src/lib/db/domainState.ts` — SQLite CRUD for fallback chains, budgets, cost history, lockout state, circuit breakers--OAuth provider modules (13 individual files under `src/lib/oauth/providers/`):--- Registry index: `src/lib/oauth/providers/index.ts`-- Individual providers: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`-- Thin wrapper: `src/lib/oauth/providers.ts` — re-exports from individual modules--## 3) Persistence Layer--Primary state DB (SQLite):--- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL)-- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers)-- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`)-- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**--Usage persistence:--- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`)-- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`-- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)-- legacy JSON files are migrated to SQLite by startup migrations when present--Domain State DB (SQLite):--- `src/lib/db/domainState.ts` — CRUD operations for domain state-- Tables (created in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`-- Write-through cache pattern: in-memory Maps are authoritative at runtime; mutations are written synchronously to SQLite; state is restored from DB on cold start--## 4) Auth + Security Surfaces--- Dashboard cookie auth: `src/proxy.ts`, `src/app/api/auth/login/route.ts`-- API key generation/verification: `src/shared/utils/apiKey.ts`-- Provider secrets persisted in `providerConnections` entries-- Outbound proxy support via `open-sse/utils/proxyFetch.ts` (env vars) and `open-sse/utils/networkProxy.ts` (configurable per-provider or global)-- SSRF / outbound URL guard: `src/shared/network/outboundUrlGuard.ts` — blocks private/loopback/link-local ranges for all provider calls-- Runtime env validation: `src/lib/env/runtimeEnv.ts` — Zod schema for all environment variables, surfaced as startup errors/warnings-- Sync tokens: `src/lib/db/syncTokens.ts` — scoped tokens for config bundle download endpoints; backed by `sync_tokens` SQLite table (migration `024_create_sync_tokens.sql`)-- WebSocket handshake auth: `src/lib/ws/handshake.ts` — validates WS upgrade requests via API key or session cookie--## 5) Cloud Sync--- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`-- Periodic task: `src/shared/services/cloudSyncScheduler.ts`-- Periodic task: `src/shared/services/modelSyncScheduler.ts`-- Control route: `src/app/api/sync/cloud/route.ts`--## Request Lifecycle (`/v1/chat/completions`)+- Políticas: `src/app/api/policies` (GET/POST)+- Tokens de sincronização: `src/app/api/sync/tokens` (GET/POST), `src/app/api/sync/tokens/[id]` (GET/DELETE)+- Pacote de configuração: `src/app/api/sync/bundle` (GET, snapshot versionado por ETag de configurações/provedores/combos/chaves)+- WebSocket: `src/app/api/v1/ws/route.ts` — manipulador de upgrade para clientes WS compatíveis com OpenAI++## 2) SSE + Núcleo de Tradução++Módulos do fluxo principal:++- Entrada: `src/sse/handlers/chat.ts`+- Orquestração central: `open-sse/handlers/chatCore.ts`+- Adaptadores de execução do provedor: `open-sse/executors/*`+- Detecção de formato/configuração do provedor: `open-sse/services/provider.ts`+- Análise/resolução de modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts`+- Lógica de fallback de conta: `open-sse/services/accountFallback.ts`+- Registro de tradução: `open-sse/translator/index.ts`+- Transformações de stream: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts`+- Extração/normalização de uso: `open-sse/utils/usageTracking.ts`+- Analisador de tags de pensamento: `open-sse/utils/thinkTagParser.ts`+- Manipulador de embeddings: `open-sse/handlers/embeddings.ts`+- Registro de provedores de embeddings: `open-sse/config/embeddingRegistry.ts`+- Manipulador de geração de imagem: `open-sse/handlers/imageGeneration.ts`+- Registro de provedores de imagem: `open-sse/config/imageRegistry.ts`+- Sanitização de resposta: `open-sse/handlers/responseSanitizer.ts`+- Normalização de papel: `open-sse/services/roleNormalizer.ts`++Serviços (lógica de negócios):++- Seleção/classificação de conta: `open-sse/services/accountSelector.ts`+- Gerenciamento do ciclo de vida do contexto: `open-sse/services/contextManager.ts`+- Aplicação de filtro de IP: `open-sse/services/ipFilter.ts`+- Rastreamento de sessão: `open-sse/services/sessionManager.ts`+- Deduplicação de requisições: `open-sse/services/signatureCache.ts`+- Injeção de prompt do sistema: `open-sse/services/systemPrompt.ts`+- Gerenciamento de orçamento de pensamento: `open-sse/services/thinkingBudget.ts`+- Roteamento de modelo curinga: `open-sse/services/wildcardRouter.ts`+- Gerenciamento de limite de taxa: `open-sse/services/rateLimitManager.ts`+- Disjuntor: `open-sse/services/circuitBreaker.ts`+- Transferência de contexto: `open-sse/services/contextHandoff.ts` — geração e injeção de resumo de transferência para estratégia de retransmissão de contexto+- Compressão: `open-sse/services/compression/*` — compressão proativa antes da tradução do provedor;+ inclui regras de Caveman, filtros RTK, pipelines empilhados, combos de compressão, estatísticas e validação+- Recuperador de cota Codex: `open-sse/services/codexQuotaFetcher.ts` — recupera a cota Codex para decisões de transferência de contexto+- Retry ciente de cooldown: `src/sse/services/cooldownAwareRetry.ts` — retries de cooldown por modelo com `requestRetry` / `maxRetryIntervalSec` configuráveis+- Fetch seguro de saída: `src/shared/network/safeOutboundFetch.ts` — fetch protegido de provedor/modelo com proteção SSRF, bloqueio de URL privada, retry e timeout+- Guarda de URL de saída: `src/shared/network/outboundUrlGuard.ts` — valida URLs de provedores contra intervalos CIDR privados/localhost+- Padrões de requisição do provedor: `open-sse/services/providerRequestDefaults.ts` — padrões de `maxTokens`, `temperature`, `thinkingBudgetTokens` a nível de provedor+- Constantes do provedor GLM: `open-sse/config/glmProvider.ts` — modelos GLM compartilhados, URLs de cota, timeout/padrões GLMT+- Upstream de antigravidade: `open-sse/config/antigravityUpstream.ts` — constantes de URL base e caminho de descoberta+- Constantes do cliente Codex: `open-sse/config/codexClient.ts` — valores de user-agent e versão do cliente versionados+- Semente de alias de modelo: `src/lib/modelAliasSeed.ts` — semeia 30+ aliases de dialetos cross-proxy na inicialização++Módulos da camada de domínio:++- Regras/orçamentos de custo: `src/lib/domain/costRules.ts`+- Política de fallback: `src/lib/domain/fallbackPolicy.ts`+- Resolvedor de combo: `src/lib/domain/comboResolver.ts`+- Política de bloqueio: `src/lib/domain/lockoutPolicy.ts`+- Motor de políticas: `src/domain/policyEngine.ts` — avaliação centralizada de bloqueio → orçamento → fallback+- Catálogo de códigos de erro: `src/lib/domain/errorCodes.ts`+- ID da requisição: `src/lib/domain/requestId.ts`+- Timeout de fetch: `src/lib/domain/fetchTimeout.ts`+- Telemetria de requisição: `src/lib/domain/requestTelemetry.ts`+- Conformidade/auditoria: `src/lib/domain/compliance/index.ts`+- Executor de avaliação: `src/lib/domain/evalRunner.ts`+- Persistência do estado do domínio: `src/lib/db/domainState.ts` — CRUD SQLite para cadeias de fallback, orçamentos, histórico de custos, estado de bloqueio, disjuntores++Módulos do provedor OAuth (14 arquivos individuais sob `src/lib/oauth/providers/`):++- Índice do registro: `src/lib/oauth/providers/index.ts`+- Provedores individuais: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `qoder.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts`, `windsurf.ts`, `gitlab-duo.ts`+- Wrapper fino: `src/lib/oauth/providers.ts` — re-exporta de módulos individuais++## Subsistemas Principais (v3.8.0)++### A. Motor de Combinação Automática++O Motor de Combinação Automática pontua e escolhe dinamicamente os alvos de roteamento no momento da solicitação, em vez de depender de uma definição de combinação estática. Ele alimenta a família de prefixos de modelo `auto/*`.++- Entrada do motor: `open-sse/services/autoCombo/` (`autoComboEngine.ts`,+ `scoringEngine.ts`, `virtualFactory.ts`, `modePacks.ts`)+- Resolvedor: `src/domain/comboResolver.ts` (detecção automática do prefixo `auto/`)+- Painel: `/dashboard/auto-combo`+- Telemetria: tabela SQLite `auto_combo_decisions`++Principais capacidades:++- **14 estratégias de roteamento** (prioridade, ponderada, preenchimento primeiro, round-robin, P2C, aleatório,+ menos utilizado, otimizado por custo, estritamente aleatório, **auto**, lkgp, otimizado por contexto,+ retransmissão de contexto, além de um caminho de fallback) — auto é a adição principal na v3.8.0.+- **Pontuação de 9 fatores**: custo, latência p95, taxa de sucesso, margem de cota, proximidade de bloqueio,+ estado do disjuntor, falhas recentes, disponibilidade do modelo e afinidade de tags.+- **Fábrica virtual** materializa combinações efêmeras quando nenhuma combinação nomeada correspondente+ existe, obtendo candidatos de conexões de provedores ativos e saudáveis.+- **Prefixos automáticos**: `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`,+ `auto/smart`, `auto/lkgp` — cada um apoiado por um perfil de peso ajustado.+- **4 pacotes de modo**: coding, fast, cheap, smart — enviados como configurações de peso pré-definidas+ chamáveis a partir do painel.++Para detalhes algorítmicos completos (fórmulas de fatores, ajuste de peso), consulte+[`docs/routing/AUTO-COMBO.md`](../routing/AUTO-COMBO.md).++### B. Agentes de Nuvem++Agentes de Nuvem envolvem plataformas de código-agente hospedadas de terceiros (Codex Cloud, Devin,+Jules) por trás de um ciclo de vida de tarefa uniforme baseado em DB. Todos os pontos de criação/inspeção+de tarefas requerem autenticação de gerenciamento.++- Raiz do módulo: `src/lib/cloudAgent/` (`baseAgent.ts`, `registry.ts`, `api.ts`,+ `types.ts`, `db.ts`, além de subdiretórios por agente em `agents/`)+- Implementações por agente: `agents/codex/`, `agents/devin/`, `agents/jules/`+- Pontos finais públicos: `/api/v1/agents/tasks/*` (listar/criar/obter/cancelar)+- Pontos finais de gerenciamento: `/api/cloud/*` (provisionamento, status, lote)+- Painel: `/dashboard/cloud-agents`+- Armazenamento: tabela `cloud_agent_tasks`++Para detalhes de provisionamento por agente e especificidades de OAuth, consulte+[`docs/frameworks/CLOUD_AGENT.md`](../frameworks/CLOUD_AGENT.md).++### C. Guardrails++O módulo de guardrails é uma camada de middleware recarregável que inspeciona solicitações+e respostas em busca de PII, injeção de prompt e conteúdo de visão inseguro. Violações+interrompem a solicitação com HTTP **503** mais um código de erro estruturado, permitindo+que chamadores subsequentes tentem novamente ou ramifiquem.++- Raiz do módulo: `src/lib/guardrails/` (`base.ts`, `registry.ts`, `piiMasker.ts`,+ `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`)+- Recarregamento a quente: o registro observa mudanças de configuração e reconstrói a cadeia no local+- Pontos de conexão: entrada do manipulador de chat, manipulador de geração de imagem, sanitizador de resposta+- Contrato HTTP: violações aparecem como `503` com `error.code = "GUARDRAIL_VIOLATION"`++Para autoria de regras e ajuste de limites, consulte+[`docs/security/GUARDRAILS.md`](../security/GUARDRAILS.md).++### D. Camada de Domínio++O namespace `src/domain/` centraliza decisões de política para que os manipuladores de rota não+precisem montar a lógica de bloqueio/orçamento/fallback por conta própria.++- Motor de políticas: `src/domain/policyEngine.ts` — ponto de entrada único para+ avaliação pré-execução (bloqueio → orçamento → ordem de fallback)+- Regras de custo: `src/domain/costRules.ts`+- Política de fallback: `src/domain/fallbackPolicy.ts`+- Política de bloqueio: `src/domain/lockoutPolicy.ts`+- Roteamento baseado em tags: `src/domain/tagRouter.ts`+- Resolvedor de combinação: `src/domain/comboResolver.ts` — resolve nomes de combinação, prefixos auto/\*+ e alvos de modelo curinga para planos de execução concretos+- Conector de regras de conexão/modelo: `src/domain/connectionModelRules.ts`+- Capturas de disponibilidade do modelo: `src/domain/modelAvailability.ts`+- Rastreamento de expiração do provedor: `src/domain/providerExpiration.ts`+- Cache de cota: `src/domain/quotaCache.ts`+- Estado de degradação: `src/domain/degradation.ts`+- Auditoria de configuração: `src/domain/configAudit.ts`+- Construtor de metadados de resposta OmniRoute: `src/domain/omnirouteResponseMeta.ts`+- Subsistema de avaliação: `src/domain/assessment/` — trabalhos de avaliação periódicos++### E. Pipeline de Autorização++O pipeline de autorização classifica cada solicitação recebida e aplica a+cadeia de políticas apropriada antes do despacho.++- Entrada do pipeline: `src/server/authz/pipeline.ts`+- Classificador de solicitações: `src/server/authz/classify.ts` — distingue rotas de compatibilidade públicas+ de rotas de gerenciamento+- Inventário de rotas públicas: `src/shared/constants/publicApiRoutes.ts`+- Políticas: `src/server/authz/policies/` — predicados compostáveis+ (`requireApiKey`, `requireManagement`, `requireFreshAuth`, etc.)+- Utilitários de cabeçalho: `src/server/authz/headers.ts`+- Helper de asserção: `src/server/authz/assertAuth.ts`+- Contexto da solicitação: `src/server/authz/context.ts`++Rotas públicas vs rotas de gerenciamento são uma fronteira rígida: APIs de agente/cooldown e+mutações de provedores requerem autenticação de gerenciamento (HTTP 401 se ausente).++Para as regras completas de classificação de rotas, consulte+[`docs/architecture/AUTHZ_GUIDE.md`](./AUTHZ_GUIDE.md).++### F. FSM de Workflow e Roteador Consciente de Tarefas++Um roteador acionado por máquina de estados finitos, posicionado acima da seleção de combinações para direcionar+o tráfego com base na fase de workflow detectada (planejamento, execução,+revisão) e afinidade de tarefas em segundo plano.++- FSM de Workflow: `open-sse/services/workflowFSM.ts`+- Roteador consciente de tarefas: `open-sse/services/taskAwareRouter.ts`+- Detector de tarefas em segundo plano: `open-sse/services/backgroundTaskDetector.ts`+- Classificador de intenção: `open-sse/services/intentClassifier.ts`++As transições da FSM alimentam a pontuação do Auto Combo, tendendo a modelos mais baratos+para tarefas de automação/fundo e a modelos mais robustos para turnos interativos de+planejamento/revisão.++### G. Resiliência Específica do Provedor++Vários provedores enviam módulos dedicados de resiliência e furtividade que se aproveitam das+camadas globais de disjuntor / cooldown de conexão / bloqueio de modelo:++- Motor Antigravidade 429: `open-sse/services/antigravity429Engine.ts` (rotaciona+ identidade, limpa cabeçalhos de resposta, controla créditos/rastreamento de versão via+ `antigravityCredits.ts`, `antigravityHeaderScrub.ts`, `antigravityHeaders.ts`,+ `antigravityIdentity.ts`, `antigravityObfuscation.ts`, `antigravityVersion.ts`)+- Política de cota ModelScope: `open-sse/services/modelscopePolicy.ts`+- Claude Code CCH (Handshake de Canal de Compatibilidade): `open-sse/services/claudeCodeCCH.ts`,+ além de `claudeCodeCompatible.ts`, `claudeCodeConstraints.ts`, `claudeCodeExtraRemap.ts`,+ `claudeCodeToolRemapper.ts`+- Modelagem de impressão digital do Claude Code: `open-sse/services/claudeCodeFingerprint.ts`+- Ofuscação do Claude Code: `open-sse/services/claudeCodeObfuscation.ts`+- Cliente TLS do ChatGPT: `open-sse/services/chatgptTlsClient.ts` (estilo curl-impersonate+ para sessões do ChatGPT-Web)+- Cache de imagem do ChatGPT: `open-sse/services/chatgptImageCache.ts`++Para o guia completo de furtividade e orientações operacionais, consulte+[`docs/security/STEALTH_GUIDE.md`](../security/STEALTH_GUIDE.md).++### H. Webhooks, Cache de Raciocínio, Cache de Leitura++- **Webhooks** — despacho de saída para eventos de provedor/conta/tarefa.+ - Dispatcher: `src/lib/webhookDispatcher.ts`+ - Armazenamento: tabela SQLite `webhooks` (via `src/lib/db/webhooks.ts`)+ - Painel: `/dashboard/webhooks` (assinaturas, segredos, histórico de tentativas)+ - Para taxonomia de eventos e semântica de tentativas, consulte [`docs/frameworks/WEBHOOKS.md`](../frameworks/WEBHOOKS.md).+- **Cache de Raciocínio** — blocos de raciocínio replays para provedores que emitem+ tokens de pensamento (Claude, GLMT, etc.) para que turnos consecutivos possam pular o re-pensar.+ - Camada de DB: `src/lib/db/reasoningCache.ts`+ - Camada de serviço: `open-sse/services/reasoningCache.ts`+ - Para semântica de replay, consulte [`docs/routing/REASONING_REPLAY.md`](../routing/REASONING_REPLAY.md).+- **Cache de Leitura** — cache de resposta de curta duração indexado por assinatura e usado para+ colapsar tentativas idênticas de SDKs upstream quebrados.+ - Camada de DB: `src/lib/db/readCache.ts`+ - Endpoint de estatísticas: `GET /api/cache/stats`, painel em `/dashboard/cache`++## 3) Camada de Persistência++Banco de dados de estado primário (SQLite):++- Infraestrutura principal: `src/lib/db/core.ts` (better-sqlite3, migrações, WAL)+- Fachada de re-exportação: `src/lib/localDb.ts` (camada de compatibilidade fina para chamadores)+- arquivo: `${DATA_DIR}/storage.sqlite` (ou `$XDG_CONFIG_HOME/omniroute/storage.sqlite` quando definido, caso contrário `~/.omniroute/storage.sqlite`)+- entidades (tabelas + namespaces KV): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt**++Persistência de uso:++- fachada: `src/lib/usageDb.ts` (módulos decompostos em `src/lib/usage/*`)+- tabelas SQLite em `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs`+- artefatos de arquivo opcionais permanecem para compatibilidade/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `<repo>/logs/...`)+- arquivos JSON legados são migrados para SQLite por migrações de inicialização quando presentes++Banco de dados de estado de domínio (SQLite):++- `src/lib/db/domainState.ts` — operações CRUD para estado de domínio+- Tabelas (criadas em `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`+- Padrão de cache write-through: Maps em memória são autoritativos em tempo de execução; mutações são escritas de forma síncrona no SQLite; estado é restaurado do DB na inicialização a frio++## 4) Superfícies de Autenticação + Segurança++- Autenticação de cookie do painel: `src/proxy.ts`, `src/app/api/auth/login/route.ts`+- Geração/verificação de chave de API: `src/shared/utils/apiKey.ts`+- Segredos do provedor persistidos nas entradas de `providerConnections`+- Suporte a proxy de saída via `open-sse/utils/proxyFetch.ts` (variáveis de ambiente) e `open-sse/utils/networkProxy.ts` (configurável por provedor ou global)+- Proteção SSRF / URL de saída: `src/shared/network/outboundUrlGuard.ts` — bloqueia intervalos privados/loopback/link-local para todas as chamadas de provedor+- Validação do ambiente em tempo de execução: `src/lib/env/runtimeEnv.ts` — esquema Zod para todas as variáveis de ambiente, apresentado como erros/avisos de inicialização+- Tokens de sincronização: `src/lib/db/syncTokens.ts` — tokens escopados para endpoints de download de pacotes de configuração; respaldados pela tabela SQLite `sync_tokens` (migração `024_create_sync_tokens.sql`)+- Autenticação de handshake WebSocket: `src/lib/ws/handshake.ts` — valida solicitações de upgrade WS via chave de API ou cookie de sessão++## 5) Sincronização na Nuvem++- Inicialização do agendador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts`+- Tarefa periódica: `src/shared/services/cloudSyncScheduler.ts`+- Tarefa periódica: `src/shared/services/modelSyncScheduler.ts`+- Rota de controle: `src/app/api/sync/cloud/route.ts`++## Ciclo de Vida da Solicitação (`/v1/chat/completions`)```mermaidsequenceDiagram@@ -372,111 +571,111 @@ sequenceDiagramStream->>Usage: extract usage + persist history/log```-## Combo + Account Fallback Flow+## Fluxo de Fallback de Combo + Conta```mermaidflowchart TD- A[Incoming model string] --> B{Is combo name?}- B -- Yes --> C[Load combo models sequence]- B -- No --> D[Single model path]+ A[Modelo de string de entrada] --> B{É nome de combo?}+ B -- Sim --> C[Carregar sequência de modelos de combo]+ B -- Não --> D[Caminho de modelo único]- C --> E[Try model N]- E --> F[Resolve provider/model]+ C --> E[Tentar modelo N]+ E --> F[Resolver provedor/modelo]D --> F- F --> G[Select account credentials]- G --> H{Credentials available?}- H -- No --> I[Return provider unavailable]- H -- Yes --> J[Execute request]-- J --> K{Success?}- K -- Yes --> L[Return response]- K -- No --> M{Fallback-eligible error?}-- M -- No --> N[Return error]- M -- Yes --> O[Mark account unavailable cooldown]- O --> P{Another account for provider?}- P -- Yes --> G- P -- No --> Q{In combo with next model?}- Q -- Yes --> E- Q -- No --> R[Return all unavailable]+ F --> G[Selecionar credenciais da conta]+ G --> H{Credenciais disponíveis?}+ H -- Não --> I[Retornar provedor indisponível]+ H -- Sim --> J[Executar solicitação]++ J --> K{Sucesso?}+ K -- Sim --> L[Retornar resposta]+ K -- Não --> M{Erro elegível para fallback?}++ M -- Não --> N[Retornar erro]+ M -- Sim --> O[Marcar cooldown de conta indisponível]+ O --> P{Outra conta para o provedor?}+ P -- Sim --> G+ P -- Não --> Q{Em combo com o próximo modelo?}+ Q -- Sim --> E+ Q -- Não --> R[Retornar todas indisponíveis]```-Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run.+As decisões de fallback são impulsionadas por `open-sse/services/accountFallback.ts` usando códigos de status e heurísticas de mensagens de erro. O roteamento de combo adiciona uma proteção extra: 400s específicos do provedor, como bloqueio de conteúdo upstream e falhas de validação de função, são tratados como falhas locais do modelo para que os alvos de combo posteriores ainda possam ser executados.-## OAuth Onboarding and Token Refresh Lifecycle+## Ciclo de Vida de Onboarding OAuth e Atualização de Token```mermaidsequenceDiagramautonumber- participant UI as Dashboard UI- participant OAuth as /api/oauth/[provider]/[action]- participant ProvAuth as Provider Auth Server+ participant UI as UI do Dashboard+ participant OAuth as /api/oauth/[provedor]/[ação]+ participant ProvAuth as Servidor de Autenticação do Provedorparticipant DB as localDbparticipant Test as /api/providers/[id]/test- participant Exec as Provider Executor+ participant Exec as Executor do Provedor- UI->>OAuth: GET authorize or device-code- OAuth->>ProvAuth: create auth/device flow- ProvAuth-->>OAuth: auth URL or device code payload- OAuth-->>UI: flow data+ UI->>OAuth: GET autorizar ou código de dispositivo+ OAuth->>ProvAuth: criar fluxo de auth/dispositivo+ ProvAuth-->>OAuth: URL de auth ou payload de código de dispositivo+ OAuth-->>UI: dados do fluxo- UI->>OAuth: POST exchange or poll- OAuth->>ProvAuth: token exchange/poll- ProvAuth-->>OAuth: access/refresh tokens- OAuth->>DB: createProviderConnection(oauth data)- OAuth-->>UI: success + connection id+ UI->>OAuth: POST trocar ou poll+ OAuth->>ProvAuth: troca/poll de token+ ProvAuth-->>OAuth: tokens de acesso/atualização+ OAuth->>DB: createProviderConnection(dados oauth)+ OAuth-->>UI: sucesso + id da conexãoUI->>Test: POST /api/providers/[id]/test- Test->>Exec: validate credentials / optional refresh- Exec-->>Test: valid or refreshed token info- Test->>DB: update status/tokens/errors- Test-->>UI: validation result+ Test->>Exec: validar credenciais / atualização opcional+ Exec-->>Test: informações de token válidas ou atualizadas+ Test->>DB: atualizar status/tokens/erros+ Test-->>UI: resultado da validação```-Refresh during live traffic is executed inside `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.+A atualização durante o tráfego ao vivo é executada dentro de `open-sse/handlers/chatCore.ts` via executor `refreshCredentials()`.-## Cloud Sync Lifecycle (Enable / Sync / Disable)+## Ciclo de Vida de Sincronização na Nuvem (Habilitar / Sincronizar / Desabilitar)```mermaidsequenceDiagramautonumber- participant UI as Endpoint Page UI+ participant UI as UI da Página de Endpointparticipant Sync as /api/sync/cloudparticipant DB as localDb- participant Cloud as External Cloud Sync+ participant Cloud as Sincronização Externa na Nuvemparticipant Claude as ~/.claude/settings.json- UI->>Sync: POST action=enable- Sync->>DB: set cloudEnabled=true- Sync->>DB: ensure API key exists- Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys)- Cloud-->>Sync: sync result+ UI->>Sync: POST ação=habilitar+ Sync->>DB: definir cloudEnabled=true+ Sync->>DB: garantir que a chave da API exista+ Sync->>Cloud: POST /sync/{machineId} (provedores/aliases/combos/chaves)+ Cloud-->>Sync: resultado da sincronizaçãoSync->>Cloud: GET /{machineId}/v1/verify- Sync-->>UI: enabled + verification status+ Sync-->>UI: habilitado + status de verificação- UI->>Sync: POST action=sync+ UI->>Sync: POST ação=sincronizarSync->>Cloud: POST /sync/{machineId}- Cloud-->>Sync: remote data- Sync->>DB: update newer local tokens/status- Sync-->>UI: synced+ Cloud-->>Sync: dados remotos+ Sync->>DB: atualizar tokens/status locais mais novos+ Sync-->>UI: sincronizado- UI->>Sync: POST action=disable- Sync->>DB: set cloudEnabled=false+ UI->>Sync: POST ação=desabilitar+ Sync->>DB: definir cloudEnabled=falseSync->>Cloud: DELETE /sync/{machineId}- Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed)- Sync-->>UI: disabled+ Sync->>Claude: mudar ANTHROPIC_BASE_URL de volta para local (se necessário)+ Sync-->>UI: desabilitado```-Periodic sync is triggered by `CloudSyncScheduler` when cloud is enabled.+A sincronização periódica é acionada por `CloudSyncScheduler` quando a nuvem está habilitada.-## Data Model and Storage Map+## Modelo de Dados e Mapa de Armazenamento```mermaiderDiagram- SETTINGS ||--o{ PROVIDER_CONNECTION : controls- PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider- PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage+ SETTINGS ||--o{ PROVIDER_CONNECTION : controla+ PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : provedor_compatível+ PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emite_usoSETTINGS {boolean cloudEnabled@@ -571,32 +770,32 @@ erDiagram}```-Physical storage files:+Arquivos de armazenamento físico:-- primary runtime DB: `${DATA_DIR}/storage.sqlite`-- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact)-- structured call payload archives: `${DATA_DIR}/call_logs/`-- optional translator/request debug sessions: `<repo>/logs/...`+- banco de dados de execução primário: `${DATA_DIR}/storage.sqlite`+- linhas de log de requisição: `${DATA_DIR}/log.txt` (artefato de compatibilidade/debug)+- arquivos de carga útil de chamadas estruturadas: `${DATA_DIR}/call_logs/`+- sessões de depuração de tradutor/requisição opcionais: `<repo>/logs/...`-## Deployment Topology+## Topologia de Implantação```mermaidflowchart LR- subgraph LocalHost[Developer Host]+ subgraph LocalHost[Host do Desenvolvedor]CLI[CLI Tools]- Browser[Dashboard Browser]+ Browser[Navegador do Dashboard]end- subgraph ContainerOrProcess[OmniRoute Runtime]- Next[Next.js Server\nPORT=20128]- Core[SSE Core + Executors]+ subgraph ContainerOrProcess[Execução do OmniRoute]+ Next[Servidor Next.js\nPORT=20128]+ Core[Núcleo SSE + Executores]MainDB[(storage.sqlite)]- UsageDB[(usage tables + log artifacts)]+ UsageDB[(tabelas de uso + artefatos de log)]end- subgraph External[External Services]- Providers[AI Providers]- SyncCloud[Cloud Sync Service]+ subgraph External[Serviços Externos]+ Providers[Provedores de IA]+ SyncCloud[Serviço de Sincronização em Nuvem]endCLI --> Next@@ -609,283 +808,333 @@ flowchart LRNext --> SyncCloud```-## Module Mapping (Decision-Critical)--### Route and API Modules--- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs-- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images)-- `src/app/api/providers*`: provider CRUD, validation, testing-- `src/app/api/provider-nodes*`: custom compatible node management-- `src/app/api/provider-models`: custom model management (CRUD)-- `src/app/api/models/route.ts`: model catalog API (aliases + custom models)-- `src/app/api/oauth/*`: OAuth/device-code flows-- `src/app/api/keys*`: local API key lifecycle-- `src/app/api/models/alias`: alias management-- `src/app/api/combos*`: fallback combo management-- `src/app/api/pricing`: pricing overrides for cost calculation-- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE)-- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST)-- `src/app/api/usage/*`: usage and logs APIs-- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers-- `src/app/api/cli-tools/*`: local CLI config writers/checkers-- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT)-- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT)-- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT)-- `src/app/api/sessions`: active session listing (GET)-- `src/app/api/rate-limits`: per-account rate limit status (GET)-- `src/app/api/sync/tokens`: sync token CRUD (GET/POST)-- `src/app/api/sync/tokens/[id]`: sync token get/delete (GET/DELETE)-- `src/app/api/sync/bundle`: config bundle download (GET, ETag versioning)-- `src/app/api/v1/ws`: WebSocket upgrade handler for OpenAI-compatible WS clients--### Routing and Execution Core--- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop-- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup-- `open-sse/executors/*`: provider-specific network and format behavior--### Translation Registry and Format Converters--- `open-sse/translator/index.ts`: translator registry and orchestration-- Request translators: `open-sse/translator/request/*`-- Response translators: `open-sse/translator/response/*`-- Format constants: `open-sse/translator/formats.ts`--### Persistence--- `src/lib/db/*`: persistent config/state and domain persistence on SQLite-- `src/lib/localDb.ts`: compatibility re-export for DB modules-- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables--## Provider Executor Coverage (Strategy Pattern)--Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method.--| Executor | Provider(s) | Special Handling |-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |-| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Dynamic URL/header config per provider |-| `AntigravityExecutor` | Google Antigravity | Custom project/session IDs, Retry-After parsing |-| `CliProxyApiExecutor` | CLIProxyAPI-compatible providers | Custom auth and protocol handling |-| `CloudflareAiExecutor` | Cloudflare Workers AI | Account ID injection, Neurons-based usage tracking |-| `CodexExecutor` | OpenAI Codex | Injects system instructions, forces reasoning effort |-| `CursorExecutor` | Cursor IDE | ConnectRPC protocol, Protobuf encoding, request signing via checksum |-| `GithubExecutor` | GitHub Copilot | Copilot token refresh, VSCode-mimicking headers |-| `GeminiCLIExecutor` | Gemini CLI | Google OAuth token refresh cycle |-| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream binary format → SSE conversion |-| `OpenCodeExecutor` | OpenCode | AI SDK compatible provider setup |-| `PollinationsExecutor` | Pollinations AI | No API key required, rate-limited requests |-| `PuterExecutor` | Puter | Browser-based provider integration |-| `QoderExecutor` | Qoder AI | PAT and OAuth support, multi-model free tier |-| `VertexExecutor` | Google Vertex AI | Service account auth, region-based endpoints |--All other providers (including custom compatible nodes) use the `DefaultExecutor`.--## Provider Compatibility Matrix--| Provider | Format | Auth | Stream | Non-Stream | Token Refresh | Usage API |-| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ------------- | ------------------ |-| Claude | claude | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin only |-| Gemini | gemini | API Key / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |-| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console |-| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ Full quota API |-| OpenAI | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Codex | openai-responses | OAuth | ✅ forced | ❌ | ✅ | ✅ Rate limits |-| GitHub Copilot | openai | OAuth + Copilot Token | ✅ | ✅ | ✅ | ✅ Quota snapshots |-| Cursor | cursor | Custom checksum | ✅ | ✅ | ❌ | ❌ |-| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Usage limits |-| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Per request |-| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Per request |-| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |-| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |-| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |-| OpenRouter | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| GLM/Kimi/MiniMax | claude | API Key | ✅ | ✅ | ❌ | ❌ |-| DeepSeek | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Groq | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| xAI (Grok) | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Mistral | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Perplexity | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Together AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Fireworks AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Cerebras | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Cohere | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| NVIDIA NIM | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Cloudflare AI | openai | API Token + Acct ID | ✅ | ✅ | ❌ | ❌ |-| Pollinations | openai | None (no key) | ✅ | ✅ | ❌ | ❌ |-| Scaleway AI | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| LongCat | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Ollama Cloud | openai | API Key (optional) | ✅ | ✅ | ❌ | ❌ |-| HuggingFace | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Nebius | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| SiliconFlow | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Hyperbolic | openai | API Key | ✅ | ✅ | ❌ | ❌ |-| Vertex AI | gemini | Service Account | ✅ | ✅ | ✅ | ⚠️ Cloud Console |-| Puter | openai | API Key | ✅ | ✅ | ❌ | ❌ |--## Format Translation Coverage--Detected source formats include:+## Mapeamento de Módulos (Crítico para Decisão)++### Módulos de Rota e API++- `src/app/api/v1/*`, `src/app/api/v1beta/*`: APIs de compatibilidade+- `src/app/api/v1/providers/[provider]/*`: rotas dedicadas por provedor (chat, embeddings, imagens)+- `src/app/api/providers*`: CRUD de provedores, validação, teste+- `src/app/api/provider-nodes*`: gerenciamento de nós compatíveis personalizados+- `src/app/api/provider-models`: gerenciamento de modelos personalizados (CRUD)+- `src/app/api/models/route.ts`: API de catálogo de modelos (aliases + modelos personalizados)+- `src/app/api/oauth/*`: fluxos de OAuth/código de dispositivo+- `src/app/api/keys*`: ciclo de vida da chave API local+- `src/app/api/models/alias`: gerenciamento de alias+- `src/app/api/combos*`: gerenciamento de combos de fallback+- `src/app/api/pricing`: substituições de preços para cálculo de custos+- `src/app/api/settings/proxy`: configuração de proxy (GET/PUT/DELETE)+- `src/app/api/settings/proxy/test`: teste de conectividade de proxy de saída (POST)+- `src/app/api/usage/*`: APIs de uso e logs+- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronização em nuvem e helpers voltados para a nuvem+- `src/app/api/cli-tools/*`: escritores/verificadores de configuração CLI local+- `src/app/api/settings/ip-filter`: lista de permissão/bloqueio de IP (GET/PUT)+- `src/app/api/settings/thinking-budget`: configuração do orçamento de tokens de pensamento (GET/PUT)+- `src/app/api/settings/system-prompt`: prompt do sistema global (GET/PUT)+- `src/app/api/settings/compression`: configurações de compressão global (GET/PUT)+- `src/app/api/compression/*`: visualização de compressão, metadados de regras e pacotes de idiomas+- `src/app/api/context/caveman/config`: alias de configurações do Caveman (GET/PUT)+- `src/app/api/context/rtk/*`: configuração RTK, catálogo de filtros, endpoint de teste e recuperação de saída bruta+- `src/app/api/context/combos*`: CRUD de combos de compressão e atribuições de combos de roteamento+- `src/app/api/context/analytics`: alias de análises de compressão+- `src/app/api/sessions`: listagem de sessões ativas (GET)+- `src/app/api/rate-limits`: status de limite de taxa por conta (GET)+- `src/app/api/sync/tokens`: CRUD de tokens de sincronização (GET/POST)+- `src/app/api/sync/tokens/[id]`: obter/excluir token de sincronização (GET/DELETE)+- `src/app/api/sync/bundle`: download de pacote de configuração (GET, versionamento ETag)+- `src/app/api/v1/ws`: manipulador de atualização WebSocket para clientes WS compatíveis com OpenAI++### Núcleo de Roteamento e Execução++- `src/sse/handlers/chat.ts`: análise de requisição, manipulação de combo, loop de seleção de conta+- `open-sse/handlers/chatCore.ts`: tradução, despacho de executores, manipulação de retry/refresh, configuração de stream+- `open-sse/executors/*`: comportamento de rede e formato específico do provedor++### Registro de Tradução e Conversores de Formato++- `open-sse/translator/index.ts`: registro e orquestração de tradutores+- Tradutores de requisição: `open-sse/translator/request/*` (9 módulos — `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`, `gemini-to-openai`, `openai-responses`, `openai-to-claude`, `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`)+- Tradutores de resposta: `open-sse/translator/response/*` (8 módulos — `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`, `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`, `openai-to-claude`)+- Helpers: `open-sse/translator/helpers/*` (8 módulos — `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`, `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`)+- Constantes de formato: `open-sse/translator/formats.ts`+- Bootstrap e registro: `open-sse/translator/bootstrap.ts`, `open-sse/translator/registry.ts`+- Helpers de formato de imagem: `open-sse/translator/image/`++### Persistência++- `src/lib/db/*`: configuração/persistência de estado e domínio persistente no SQLite+- `src/lib/localDb.ts`: re-exportação de compatibilidade para módulos de DB+- `src/lib/usageDb.ts`: fachada de histórico de uso/logs de chamadas sobre tabelas SQLite++## Cobertura do Executor do Provedor (Padrão de Estratégia)++Cada provedor possui um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalhos, tentativas com retrocesso exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`.++| Executor | Provedor(es) | Tratamento Especial |+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |+| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA, etc. | Configuração dinâmica de URL/cabeçalho por provedor |+| `AntigravityExecutor` | Google Antigravity | IDs de projeto/sessão personalizados, análise de Retry-After, ofuscação de 429 |+| `AzureOpenAIExecutor` | Azure OpenAI | Roteamento baseado em implantação, aplicação de consulta de api-version |+| `BlackboxWebExecutor` | Blackbox AI (modo web) | Reversão de sessão web com emulação de impressão digital TLS |+| `ChatGPTWebExecutor` | ChatGPT web | Gerenciamento de cliente TLS + cookie de sessão (`chatgptTlsClient.ts`) |+| `ClaudeIdentityExecutor` | Claude.ai (caminho CCH) | Pipelines de restrição + remapeamento de ferramentas, modelagem de impressão digital |+| `CliProxyApiExecutor` | Provedores compatíveis com CLIProxyAPI | Tratamento personalizado de autenticação e protocolo |+| `CloudflareAiExecutor` | Cloudflare Workers AI | Injeção de ID de conta, rastreamento de uso baseado em Neurons |+| `CodexExecutor` | OpenAI Codex | Injeções de instruções do sistema, força de esforço de raciocínio |+| `CommandCodeExecutor` | Código de Comando | Rotação de cabeçalho por sessão + OAuth |+| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de requisições via checksum |+| `DevinCliExecutor` | Devin CLI | Conexão do ciclo de vida da tarefa Devin via módulo de agente em nuvem |+| `GeminiCLIExecutor` | Gemini CLI | Ciclo de atualização de token OAuth do Google |+| `GithubExecutor` | GitHub Copilot | Atualização de token do Copilot, cabeçalhos imitando VSCode |+| `GitlabExecutor` | GitLab Duo | Roteamento baseado em projeto + OAuth do GitLab |+| `GlmExecutor` | Z.AI GLM (incl. preset `glmt`) | Consciente do orçamento de pensamento, constantes do preset GLMT |+| `GrokWebExecutor` | xAI Grok web | Reversão de sessão web, seleção de modo (pensar/padrão) |+| `KieExecutor` | KIE | Emissão de token personalizada com âncoras de sessão rotativas |+| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário do AWS EventStream → conversão para SSE |+| `MuseSparkWebExecutor` | Muse Spark (web) | Reversão de sessão web com integração de mensagem de imagem |+| `NlpCloudExecutor` | NLP Cloud | Formato de corpo de requisição específico do provedor |+| `OpenCodeExecutor` | OpenCode | Configuração de provedor compatível com AI SDK |+| `PerplexityWebExecutor` | Perplexity web | Reversão de sessão web para continuidade de chat |+| `PetalsExecutor` | Inferência distribuída Petals | Roteamento de enxame descentralizado |+| `PollinationsExecutor` | Pollinations AI | Nenhuma chave de API necessária, requisições limitadas por taxa |+| `PuterExecutor` | Puter | Integração de provedor baseada em navegador |+| `QoderExecutor` | Qoder AI | Suporte a PAT e OAuth, nível gratuito de múltiplos modelos |+| `VertexExecutor` | Google Vertex AI | Autenticação de conta de serviço, endpoints baseados em região |+| `WindsurfExecutor` | Windsurf (Codeium) | Atualização de token de sessão + OAuth do Codeium |++Todos os outros provedores (incluindo nós compatíveis personalizados) usam o `DefaultExecutor`.++## Matriz de Compatibilidade de Provedores++> **Nota:** A matriz abaixo é uma amostra representativa dos 179 provedores registrados no+> OmniRoute v3.8.0. Para a lista canônica e continuamente atualizada, consulte+> [`docs/reference/PROVIDER_REFERENCE.md`](../reference/PROVIDER_REFERENCE.md) (gerada automaticamente) ou a fonte+> de verdade em `src/shared/constants/providers.ts` (validada pelo Zod no carregamento).++| Provedor | Formato | Autenticação | Stream | Não-Stream | Atualização de Token | API de Uso |+| ----------------- | ---------------- | -------------------------- | ---------------- | ---------- | -------------------- | -------------------- |+| Claude | claude | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Somente Admin |+| Gemini | gemini | Chave de API / OAuth | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |+| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |+| Antigravity | antigravity | OAuth | ✅ | ✅ | ✅ | ✅ API de cota total |+| OpenAI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Codex | openai-responses | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxa |+| GitHub Copilot | openai | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Capturas de cota |+| Cursor | cursor | Checksum personalizado | ✅ | ✅ | ❌ | ❌ |+| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso |+| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |+| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |+| Kilo Code | openai | OAuth | ✅ | ✅ | ✅ | ❌ |+| Cline | openai | OAuth | ✅ | ✅ | ✅ | ❌ |+| Kimi Coding | openai | OAuth | ✅ | ✅ | ✅ | ❌ |+| OpenRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| GLM/Kimi/MiniMax | claude | Chave de API | ✅ | ✅ | ❌ | ❌ |+| DeepSeek | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Groq | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| xAI (Grok) | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Mistral | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Perplexity | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Together AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Fireworks AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Cerebras | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Cohere | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| NVIDIA NIM | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Cloudflare AI | openai | Token de API + ID da Conta | ✅ | ✅ | ❌ | ❌ |+| Pollinations | openai | Nenhum (sem chave) | ✅ | ✅ | ❌ | ❌ |+| Scaleway AI | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| LongCat | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Ollama Cloud | openai | Chave de API (opcional) | ✅ | ✅ | ❌ | ❌ |+| HuggingFace | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Nebius | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| SiliconFlow | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Hyperbolic | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Vertex AI | gemini | Conta de Serviço | ✅ | ✅ | ✅ | ⚠️ Console da Nuvem |+| Puter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Command Code | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação |+| Z.AI / GLM | openai | Chave de API / OAuth | ✅ | ✅ | ❌ | ❌ |+| GLMT (preset) | claude | Chave de API | ✅ | ✅ | ❌ | ⚠️ Por solicitação |+| Kimi Coding | openai | OAuth / Chave de API | ✅ | ✅ | ✅ | ❌ |+| KIE | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Windsurf | openai | OAuth (Codeium) | ✅ | ✅ | ✅ | ⚠️ Por solicitação |+| GitLab Duo | openai | OAuth (GitLab) | ✅ | ✅ | ✅ | ❌ |+| Devin CLI | openai | OAuth | ✅ | ✅ | ✅ | ✅ API de Tarefas |+| Codex Cloud | openai-responses | OAuth | ✅ | ❌ | ✅ | ✅ Limites de taxa |+| Jules | openai | OAuth | ✅ | ✅ | ✅ | ✅ API de Tarefas |+| AgentRouter | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| ChatGPT-Web | openai | Cookie de sessão + TLS | ✅ | ✅ | ❌ | ❌ |+| Grok-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |+| Perplexity-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |+| BlackBox-Web | openai | Cookie de sessão + TLS | ✅ | ✅ | ❌ | ❌ |+| Muse-Spark-Web | openai | Cookie de sessão | ✅ | ✅ | ❌ | ❌ |+| ModelScope | openai | Chave de API | ✅ | ✅ | ❌ | ⚠️ Política de cota |+| BazaarLink | openai | Chave de API | ✅ | ✅ | ❌ | ❌ |+| Petals | openai | Nenhum | ✅ | ✅ | ❌ | ❌ |+| Qoder | openai | OAuth / PAT | ✅ | ✅ | ✅ | ⚠️ Por solicitação |+| OpenCode (Go/Zen) | openai | OAuth | ✅ | ✅ | ✅ | ❌ |+| CLIProxyAPI | openai | Personalizado | ✅ | ✅ | ❌ | ❌ |++## Cobertura de Tradução de Formato++Os formatos de origem detectados incluem:- `openai`- `openai-responses`- `claude`- `gemini`-Target formats include:+Os formatos de destino incluem:-- OpenAI chat/Responses+- OpenAI chat/Respostas- Claude-- Gemini/Gemini-CLI/Antigravity envelope+- Gemini/Gemini-CLI/envelope Antigravity- Kiro- Cursor-Translations use **OpenAI as the hub format** — all conversions go through OpenAI as intermediate:+As traduções usam **OpenAI como o formato central** — todas as conversões passam pelo OpenAI como intermediário:```-Source Format → OpenAI (hub) → Target Format+Formato de Origem → OpenAI (central) → Formato de Destino```-Translations are selected dynamically based on source payload shape and provider target format.+As traduções são selecionadas dinamicamente com base na forma do payload de origem e no formato de destino do provedor.-Additional processing layers in the translation pipeline:+Camadas de processamento adicionais no pipeline de tradução:-- **Response sanitization** — Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance-- **Role normalization** — Converts `developer` → `system` for non-OpenAI targets; merges `system` → `user` for models that reject the system role (GLM, ERNIE)-- **Think tag extraction** — Parses `<think>...</think>` blocks from content into `reasoning_content` field-- **Structured output** — Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema`+- **Sanitização de resposta** — Remove campos não padrão das respostas no formato OpenAI (tanto streaming quanto não streaming) para garantir conformidade estrita com o SDK+- **Normalização de função** — Converte `developer` → `system` para alvos que não são OpenAI; mescla `system` → `user` para modelos que rejeitam a função de sistema (GLM, ERNIE)+- **Extração de tag de pensamento** — Analisa blocos ``do conteúdo para o campo`reasoning_content`+- **Saída estruturada** — Converte `response_format.json_schema` do OpenAI para `responseMimeType` + `responseSchema` do Gemini-## Supported API Endpoints+## Endpoints da API Suportados-| Endpoint | Format | Handler |-| -------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |-| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |-| `POST /v1/messages` | Claude Messages | Same handler (auto-detected) |-| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` |-| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |-| `GET /v1/embeddings` | Model listing | API route |-| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` |-| `GET /v1/images/generations` | Model listing | API route |-| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicated per-provider with model validation |-| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicated per-provider with model validation |-| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedicated per-provider with model validation |-| `POST /v1/messages/count_tokens` | Claude Token Count | API route |-| `GET /v1/models` | OpenAI Models list | API route (chat + embedding + image + custom models) |-| `GET /api/models/catalog` | Catalog | All models grouped by provider + type |-| `POST /v1beta/models/*:streamGenerateContent` | Gemini native | API route |-| `GET/PUT/DELETE /api/settings/proxy` | Proxy Config | Network proxy configuration |-| `POST /api/settings/proxy/test` | Proxy Connectivity | Proxy health/connectivity test endpoint |-| `GET/POST/DELETE /api/provider-models` | Provider Models | Provider model metadata backing custom and managed available models |+| Endpoint | Formato | Manipulador |+| -------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |+| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` |+| `POST /v1/messages` | Claude Messages | Mesmo manipulador (detecção automática) |+| `POST /v1/responses` | OpenAI Respostas | `open-sse/handlers/responsesHandler.ts` |+| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` |+| `GET /v1/embeddings` | Listagem de Modelos | Rota da API |+| `POST /v1/images/generations` | OpenAI Imagens | `open-sse/handlers/imageGeneration.ts` |+| `GET /v1/images/generations` | Listagem de Modelos | Rota da API |+| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicado por provedor com validação de modelo |+| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Dedicado por provedor com validação de modelo |+| `POST /v1/providers/{provider}/images/generations` | OpenAI Imagens | Dedicado por provedor com validação de modelo |+| `POST /v1/messages/count_tokens` | Contagem de Tokens Claude | Rota da API |+| `GET /v1/models` | Lista de Modelos OpenAI | Rota da API (chat + embedding + imagem + modelos personalizados) |+| `GET /api/models/catalog` | Catálogo | Todos os modelos agrupados por provedor + tipo |+| `POST /v1beta/models/*:streamGenerateContent` | Nativo do Gemini | Rota da API |+| `GET/PUT/DELETE /api/settings/proxy` | Configuração de Proxy | Configuração de proxy de rede |+| `POST /api/settings/proxy/test` | Conectividade de Proxy | Endpoint de teste de saúde/conectividade do proxy |+| `GET/POST/DELETE /api/provider-models` | Modelos de Provedor | Metadados do modelo do provedor que suportam modelos disponíveis personalizados e gerenciados |-## Bypass Handler+## Manipulador de Bypass-The bypass handler (`open-sse/utils/bypassHandler.ts`) intercepts known "throwaway" requests from Claude CLI — warmup pings, title extractions, and token counts — and returns a **fake response** without consuming upstream provider tokens. This is triggered only when `User-Agent` contains `claude-cli`.+O manipulador de bypass (`open-sse/utils/bypassHandler.ts`) intercepta solicitações conhecidas como "descartáveis" do Claude CLI — pings de aquecimento, extrações de título e contagens de tokens — e retorna uma **resposta falsa** sem consumir tokens do provedor upstream. Isso é acionado apenas quando o `User-Agent` contém `claude-cli`.-## Request Logging and Artifacts+## Registro de Solicitações e Artefatos-The older file-based request logger (`open-sse/utils/requestLogger.ts`) is retained only for-legacy compatibility. The current runtime contract uses:+O antigo registrador de solicitações baseado em arquivo (`open-sse/utils/requestLogger.ts`) é mantido apenas para compatibilidade com versões anteriores. O contrato de tempo de execução atual utiliza:-- `APP_LOG_TO_FILE=true` for application and audit logs written under `<repo>/logs/`-- SQLite-backed call log records in `call_logs`-- `${DATA_DIR}/call_logs/YYYY-MM-DD/...` artifacts when the call log pipeline is enabled+- `APP_LOG_TO_FILE=true` para logs de aplicação e auditoria gravados em `<repo>/logs/`+- Registros de log de chamadas com suporte a SQLite em `call_logs`+- Artefatos em `${DATA_DIR}/call_logs/YYYY-MM-DD/...` quando o pipeline de log de chamadas está habilitado-## Failure Modes and Resilience+## Modos de Falha e Resiliência-## 1) Account/Provider Availability+## 1) Disponibilidade de Conta/Provedor-- connection cooldown on retryable upstream failures-- account fallback before failing request-- combo model fallback when current model/provider path is exhausted+- cooldown de conexão em falhas upstream recuperáveis+- fallback de conta antes de falhar a solicitação+- fallback de modelo combinado quando o caminho atual de modelo/provedor é esgotado-## 2) Token Expiry+## 2) Expiração de Token-- pre-check and refresh with retry for refreshable providers-- 401/403 retry after refresh attempt in core path+- pré-verificação e atualização com tentativa de repetição para provedores atualizáveis+- tentativa de repetição 401/403 após tentativa de atualização no caminho principal-## 3) Stream Safety+## 3) Segurança do Stream-- disconnect-aware stream controller-- translation stream with end-of-stream flush and `[DONE]` handling-- usage estimation fallback when provider usage metadata is missing+- controlador de stream ciente de desconexões+- stream de tradução com descarte de fim de stream e tratamento de `[DONE]`+- fallback de estimativa de uso quando os metadados de uso do provedor estão ausentes-## 4) Cloud Sync Degradation+## 4) Degradação da Sincronização na Nuvem-- sync errors are surfaced but local runtime continues-- scheduler has retry-capable logic, but periodic execution currently calls single-attempt sync by default+- erros de sincronização são exibidos, mas o tempo de execução local continua+- o agendador possui lógica capaz de repetição, mas a execução periódica atualmente chama a sincronização de tentativa única por padrão-## 5) Data Integrity+## 5) Integridade dos Dados-- SQLite schema migrations and auto-upgrade hooks at startup-- legacy JSON → SQLite migration compatibility path+- migrações de esquema SQLite e ganchos de autoatualização na inicialização+- caminho de compatibilidade de migração legado JSON → SQLite-## 6) SSRF / Outbound URL Guard+## 6) SSRF / Proteção de URL de Saída-- `src/shared/network/outboundUrlGuard.ts` blocks all private/loopback/link-local target URLs before they reach provider executors-- Provider model discovery and validation routes use `src/shared/network/safeOutboundFetch.ts` which applies the guard before every outbound request-- Guard errors surface as `URL_GUARD_BLOCKED` with HTTP 422 and are logged to the compliance audit trail via `providerAudit.ts`+- `src/shared/network/outboundUrlGuard.ts` bloqueia todas as URLs de destino privadas/loopback/link-local antes que elas cheguem aos executores do provedor+- As rotas de descoberta e validação do modelo do provedor usam `src/shared/network/safeOutboundFetch.ts`, que aplica a proteção antes de cada solicitação de saída+- Erros de proteção aparecem como `URL_GUARD_BLOCKED` com HTTP 422 e são registrados na trilha de auditoria de conformidade via `providerAudit.ts`-## Observability and Operational Signals+## Observabilidade e Sinais Operacionais-Runtime visibility sources:+Fontes de visibilidade em tempo de execução:-- console logs from `src/sse/utils/logger.ts`-- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`)-- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true`-- textual request status log in `log.txt` (optional/compat)-- optional application log files under `logs/` when `APP_LOG_TO_FILE=true`-- optional request artifacts under `${DATA_DIR}/call_logs/` when the call log pipeline is enabled-- dashboard usage endpoints (`/api/usage/*`) for UI consumption+- logs do console de `src/sse/utils/logger.ts`+- agregados de uso por solicitação em SQLite (`usage_history`, `call_logs`, `proxy_logs`)+- capturas detalhadas de payload em quatro estágios em SQLite (`request_detail_logs`) quando `settings.detailed_logs_enabled=true`+- log de status de solicitação textual em `log.txt` (opcional/compat)+- arquivos de log de aplicação opcionais em `logs/` quando `APP_LOG_TO_FILE=true`+- artefatos de solicitação opcionais em `${DATA_DIR}/call_logs/` quando o pipeline de log de chamadas está habilitado+- endpoints de uso do dashboard (`/api/usage/*`) para consumo da UI-Detailed request payload capture stores up to four JSON payload stages per routed call:+A captura detalhada do payload da solicitação armazena até quatro estágios de payload JSON por chamada roteada:-- raw request received from the client-- translated request actually sent upstream-- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata-- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form+- solicitação bruta recebida do cliente+- solicitação traduzida realmente enviada para upstream+- resposta do provedor reconstruída como JSON; respostas transmitidas são compactadas para o resumo final mais metadados do stream+- resposta final do cliente retornada pelo OmniRoute; respostas transmitidas são armazenadas na mesma forma de resumo compacto-## Security-Sensitive Boundaries+## Limites Sensíveis à Segurança-- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing-- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning-- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format-- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level-- Cloud sync endpoints rely on API key auth + machine id semantics+- O segredo do JWT (`JWT_SECRET`) protege a verificação/assinatura do cookie de sessão do painel+- A senha inicial de bootstrap (`INITIAL_PASSWORD`) deve ser configurada explicitamente para o provisionamento na primeira execução+- O segredo HMAC da chave da API (`API_KEY_SECRET`) protege o formato da chave da API local gerada+- Segredos do provedor (chaves/tokens da API) são persistidos no banco de dados local e devem ser protegidos a nível de sistema de arquivos+- Os endpoints de sincronização em nuvem dependem da autenticação da chave da API + semântica do id da máquina-## Environment and Runtime Matrix+## Matriz de Ambiente e Tempo de Execução-Environment variables actively used by code:+Variáveis de ambiente ativamente usadas pelo código:- App/auth: `JWT_SECRET`, `INITIAL_PASSWORD`-- Storage: `DATA_DIR`-- Compatible node behavior: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`-- Optional storage base override (Linux/macOS when `DATA_DIR` unset): `XDG_CONFIG_HOME`-- Security hashing: `API_KEY_SECRET`, `MACHINE_ID_SALT`-- Logging: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`-- Sync/cloud URLing: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`-- Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` and lowercase variants-- SOCKS5 feature flags: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`-- Platform/runtime helpers (not app-specific config): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`--## Known Architectural Notes--1. `usageDb` and `localDb` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration.-2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift.-3. Request logger writes full headers/body when enabled; treat log directory as sensitive.-4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability.-5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency.-6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates).-7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`).-8. Settings page is organized into 7 tabs: General, Appearance, AI, Security, Routing, Resilience, Advanced. The Resilience page only configures request queue, connection cooldown, provider breaker, and wait-for-cooldown behavior; live breaker runtime state is shown on the Health page.-9. **Context Relay** strategy (`context-relay`) is split across two layers: `combo.ts` decides if a handoff should be generated, `chat.ts` injects the handoff after account resolution. Handoff data lives in `context_handoffs` SQLite table. This split is intentional because only `chat.ts` knows whether the actual account changed.-10. **Proxy enforcement** is now comprehensive: `tokenHealthCheck.ts` resolves proxy per connection, `/api/providers/validate` uses `runWithProxyContext`, and `proxyFetch.ts` uses `undici.fetch()` to maintain dispatcher compatibility on Node 22.-11. **Node.js runtime policy detection**: `/api/settings/require-login` returns `nodeVersion` and `nodeCompatible` fields. The login page renders a warning banner when the runtime falls outside the supported secure Node.js lines.--## Operational Verification Checklist--- Build from source: `npm run build`-- Build Docker image: `docker build -t omniroute .`-- Start service and verify:+- Armazenamento: `DATA_DIR`+- Comportamento compatível do node: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE`+- Sobrescrita opcional da base de armazenamento (Linux/macOS quando `DATA_DIR` não estiver definido): `XDG_CONFIG_HOME`+- Hashing de segurança: `API_KEY_SECRET`, `MACHINE_ID_SALT`+- Registro: `APP_LOG_TO_FILE`, `APP_LOG_RETENTION_DAYS`, `CALL_LOG_RETENTION_DAYS`+- URL de sincronização/nuvem: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL`+- Proxy de saída: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e variantes em minúsculas+- Flags de recurso SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY`+- Auxiliares de plataforma/tempo de execução (não configuração específica do app): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME`++## Notas Arquitetônicas Conhecidas++1. `usageDb` e `localDb` compartilham a mesma política de diretório base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) com migração de arquivos legados.+2. `/api/v1/route.ts` delega para o mesmo construtor de catálogo unificado usado por `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) para evitar desvios semânticos.+3. O registrador de solicitações escreve cabeçalhos/corpo completos quando habilitado; trate o diretório de logs como sensível.+4. O comportamento em nuvem depende do correto `NEXT_PUBLIC_BASE_URL` e da acessibilidade do endpoint em nuvem.+5. O diretório `open-sse/` é publicado como o pacote de **workspace npm** `@omniroute/open-sse`. O código-fonte o importa via `@omniroute/open-sse/...` (resolvido pelo Next.js `transpilePackages`). Os caminhos de arquivos neste documento ainda usam o nome do diretório `open-sse/` para consistência.+6. Gráficos no painel usam **Recharts** (baseado em SVG) para visualizações analíticas interativas e acessíveis (gráficos de barras de uso de modelo, tabelas de divisão de provedores com taxas de sucesso).+7. Testes E2E usam **Playwright** (`tests/e2e/`), executados via `npm run test:e2e`. Testes unitários usam **Node.js test runner** (`tests/unit/`), executados via `npm run test:unit`. O código-fonte sob `src/` é **TypeScript** (`.ts`/`.tsx`); o workspace `open-sse/` permanece em JavaScript (`.js`).+8. A página de configurações é organizada em 7 abas: Geral, Aparência, IA, Segurança, Roteamento, Resiliência, Avançado. A página de Resiliência configura apenas a fila de solicitações, o tempo de espera de conexão, o disjuntor do provedor e o comportamento de espera pelo tempo de espera; o estado de tempo de execução do disjuntor ao vivo é mostrado na página de Saúde.+9. A estratégia de **Context Relay** (`context-relay`) é dividida em duas camadas: `combo.ts` decide se uma transferência deve ser gerada, `chat.ts` injeta a transferência após a resolução da conta. Os dados da transferência vivem na tabela SQLite `context_handoffs`. Essa divisão é intencional porque apenas `chat.ts` sabe se a conta real mudou.+10. A **aplicação de proxy** agora é abrangente: `tokenHealthCheck.ts` resolve o proxy por conexão, `/api/providers/validate` usa `runWithProxyContext`, e `proxyFetch.ts` usa `undici.fetch()` para manter a compatibilidade do despachante no Node 22.+11. **Detecção de política de tempo de execução do Node.js**: `/api/settings/require-login` retorna os campos `nodeVersion` e `nodeCompatible`. A página de login renderiza um banner de aviso quando o tempo de execução está fora das linhas seguras suportadas do Node.js.++## Lista de Verificação de Verificação Operacional++- Compilar a partir do código-fonte: `npm run build`+- Construir a imagem Docker: `docker build -t omniroute .`+- Iniciar o serviço e verificar:- `GET /api/settings`- `GET /api/v1/models`-- CLI target base URL should be `http://<host>:20128/v1` when `PORT=20128`+- A URL base do alvo da CLI deve ser `http://<host>:20128/v1` quando `PORT=20128`