mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
1bda6c15dc
* fix(install): add pnpm-workspace.yaml allowBuilds + pnpm.json for pnpm 11+ pnpm 11 introduced ERR_PNPM_IGNORED_BUILDS for native addon packages. Without explicit allowBuilds approval, these packages silently skip build scripts and OmniRoute fails to start with missing native modules. Changes: - pnpm-workspace.yaml: Set allowBuilds=true for all 13 native addon packages (@parcel/watcher, @swc/core, better-sqlite3, core-js, esbuild, keytar, koffi, libxmljs2, onnxruntime-node, protobufjs, sharp, tls-client-node, unrs-resolver) - pnpm.json: Migrate onlyBuiltDependencies from package.json (deprecated field) to the new pnpm.json config file per pnpm 11 spec. Tested on: pnpm 11.9.0, Node 24, Windows 11. Fixes: pnpm install ERR_PNPM_IGNORED_BUILDS on fresh clone with pnpm 11. * chore(release): open v3.8.44 development cycle * test(security): parse Kimi Web URL host instead of substring match (CodeQL #689) (#5928) Alert js/incomplete-url-substring-sanitization: the Kimi Web executor test asserted result.url.includes("www.kimi.com"), which a hostile host like www.kimi.com.evil.net would also satisfy. Parse the URL and assert on the exact hostname (new URL(result.url).hostname === "www.kimi.com"), which is both a stronger check and clears the CodeQL warning. * refactor(translator): extract thinking-budget fitting from openai-to-claude (#5932) Extract the thinking-budget fitting cluster (fitThinkingToMaxTokens + private safeCapMaxOutputTokens + MIN_* constants) verbatim into the pure leaf openai-to-claude/thinkingBudget.ts. Host re-exports fitThinkingToMaxTokens so external importers keep working and imports it back for internal use. Host 822 -> 738 LOC (under the 800 cap). No behavior change: byte-identical bodies, public export set unchanged. Adds a split-guard test; all consumer tests stay green (translator-openai-to-claude, strip-empty, minimax-m3, passthrough). * chore(release): pipeline hardening — test-masking pre-flight gate + contributors/uncovered helpers (#5926) * chore(ci): add test-masking PR-context gate to release-green pre-flight Reproduce check:test-masking (vs origin/main) inside validate-release-green so non-allowlisted net-assert reductions surface in the local pre-flight instead of in a ~40-min CI layer on the release PR. run() now merges a per-gate opts.env so GITHUB_BASE_REF reaches the child. HARD gate; skipped under --quick. Context: v3.8.43 release cost 3 CI round-trips for PR-context gates (test-masking, file-size, pr-evidence) that check:release-green did not reproduce locally. * chore(release): add contributors generator + uncovered-commit reconciliation helpers - scripts/release/gen-contributors.mjs: reproducible `### 🙌 Contributors` table for a CHANGELOG version (parenthetical-group parser → accurate per-PR attribution, noise-handle denylist). v3.8.43 shipped without the section (a real miss) because it was hand-built. npm run release:contributors <version> [--inject]. - scripts/release/list-uncovered-commits.mjs: lists commits since the last tag with no CHANGELOG bullet (v3.8.43 had 123/176 uncovered at reconciliation start). Advisory, maintainer-side. npm run release:uncovered. - 20 unit tests (parenthetical attribution, noise exclusion, idempotent injection, coverage window). * chore(quality): absorb web-cookie-providers-new file-size drift from #5928 (base-red on release/v3.8.44) * refactor(translator): split openai-responses request translator into pure leaves (#5940) Extract the shared pure primitives and the chat->Responses direction out of the 894-line openai-responses.ts request translator: - openai-responses/helpers.ts: pure primitives (toRecord/toString/clampCallId/ normalizeVerbosity/etc + markers/regexes/JsonRecord), zero host imports - openai-responses/toResponses.ts: openaiToOpenAIResponsesRequest (chat->Responses), imports the helpers leaf Host keeps openaiResponsesToOpenAIRequest (Responses->chat, imported by production) plus both register() directions, and re-exports openaiToOpenAIResponsesRequest so external importers (tests) keep working. Host 894 -> 529 LOC (under the 800 cap). Verbatim bodies (multiset check: leaf A 54/54, leaf B 294 lines, fn1 intact), public export set unchanged, leaves never import the host (no cycle). Adds a split-guard test; all consumer tests stay green (responses-translation-fixes 37, verbosity 4, reasoning-effort 4, orphaned-tool-filter 8, empty-tool-name-loop 8, headroom-responses-format 3). * chore(ci): pr-evidence FAIL output tells you to push (body edit does not re-run the gate) (#5944) ci.yml ignores the 'edited' event, so adding the Evidence block to the PR body after a push does not re-run check:pr-evidence — you need another commit. The FAIL report now says so, at the exact place someone sees the red check. + 5 unit tests (classification + hint-on-fail / no-hint-on-pass). Decided against a separate edited-triggered workflow: pr-evidence is not a required check (no ruleset gates it; release PRs merge UNSTABLE, not BLOCKED), so the gap is cosmetic and the generate-release skill already puts Evidence in the body before the first push. * fix(providers): Perplexity Web emits real tool_calls in streaming mode (mirror chatgpt-web toolMode) (#5927) (#5937) Perplexity Web (Pro/Max) only converted <tool>{...}</tool> text into OpenAI tool_calls for non-streaming requests (hasTools && !stream). Streaming requests -- the default for agentic coding clients -- got the raw <tool> text as plain delta.content and never emitted a tool_calls SSE delta, so clients could not execute tools. Reuses the provider-agnostic buildToolModeResponse()/ toolCompletionToSseStream() helpers already shipped for chatgpt-web (#5240): when tools are requested, buffer the full completion and convert it into either a JSON completion or a terminal SSE replay carrying delta.tool_calls + finish_reason: tool_calls, regardless of the caller's stream flag. Extended buildToolModeResponse()'s idSeed to be caller-supplied (default 'cgpt', perplexity-web passes 'pplx') so tool_call ids stay provider-specific without duplicating the helper. Non-tool streaming is unchanged (still lives token-by-token via buildStreamingResponse). * fix(discovery): resolve duplicate /v1 paths and redirect aborts (#5904) Integrated into release/v3.8.44. Thanks @hamsa0x7 for diagnosing the doubled /v1 discovery path and the REDIRECT_BLOCKED probe-loop abort (#5899). De-scoped to the discovery fix (the #5903 session-affinity work is handled by #5943) and added Rule #18 regression guards. * docs(changelog): record #5926 + #5944 (release-pipeline hardening) under v3.8.44 Maintenance (#5952) * docs(claude): add Hard Rule #22 — cross-session safety (git stash + in-flight PRs) (#5955) Integrated into release/v3.8.44 — Hard Rule #22 (cross-session safety). * refactor(translator): extract pure helpers from response/openai-responses (#5949) Extract the 5 stateless helpers (normalizeToolName, stripEmptyOptionalToolArgs, normalizeOutputIndex, normalizeUpstreamFailure, extractResponsesReasoningSummaryText) verbatim into the pure leaf openai-responses/pureHelpers.ts (no stream state, no host import). Host imports them back and re-exports normalizeUpstreamFailure for external importers (tests). Host 1091 -> 1001 LOC. The stateful streaming core stays in the host (out of scope). Byte-identical bodies (multiset 73/73), no cycle. Adds a split-guard; consumer tests stay green (responses-translation-fixes 37, combo-param-validation-fallback-4519 5). * docs(compression): document upstream sync policy for RTK/Caveman engines (#5830) (#5948) Integrated into release/v3.8.44 — docs-only upstream sync policy for RTK/Caveman engines (closes #5830). All 7 checks green. * fix(sse): strip ANSI/VT100 codes from gemini-cli stream frames (#5934) Integrated into release/v3.8.44 — ReDoS-safe ANSI/VT100 strip for gemini-cli stream frames (port of upstream #2273, thanks @anki1kr). PR test green (5/5), file-size gate OK. * fix(translator): strict Anthropic content-block compliance in antigravity→openai request (#5935) Integrated into release/v3.8.44 — strict Anthropic content-block compliance in antigravity→openai (port upstream #2296). PR test green (9/9). UNSTABLE red is the pre-existing environmental setup-claude base-red (opencode-plugin dist not built in fast-path), not a regression from this PR. * fix(mcp): auto-recover stale streamable HTTP sessions on initialize (#5957) Integrated into release/v3.8.44 — MCP stale streamable-HTTP session auto-recovery (thanks @Chewji9875). * fix(providers): validate v0 Platform API keys via chats endpoint (#5954) Integrated into release/v3.8.44 — v0-vercel Platform API key validation (thanks @vittoroliveira-dev). * fix(api): relax provider-scoped chat completion validation (#5907) Integrated into release/v3.8.44 — relaxed provider-scoped chat validation + regression test (thanks @nickwizard). * fix(providers): strip /v1 unconditionally to avoid /v1/v1/models fetch error (#5899) (#5920) Integrated into release/v3.8.44 — unconditional /v1 strip in both models-discovery paths + regression test (thanks @anki1kr). * fix(resilience): per-window is_exhausted + honor quota-exhaustion preflight for priority combos (#5923) (#5941) Integrated into release/v3.8.44. * fix(resilience): honor active codex session affinity over per-request reset-aware re-scoring (#5903) (#5943) Integrated into release/v3.8.44. * fix(thinking): only inject redacted_thinking replay block when tool_use present and thinking enabled (#5945) (#5953) Integrated into release/v3.8.44. * feat(providers): add ClinePass API-key provider (#5942) Integrated into release/v3.8.44 — ClinePass API-key (BYOK) provider (port upstream 9router#2304, co-authored @adentdk). Validated locally: 16 clinepass tests green; fixed the APIKEY count 158→159 + translate-path golden snapshot (clinepass is a genuine new provider). Remaining UNSTABLE red is the pre-existing environmental setup-claude base-red (opencode-plugin dist not built in fast-path). Supersedes stub #5541. * feat(api): add /v1/ocr endpoint (Mistral OCR) + Mistral moderation (#5950) Integrated into release/v3.8.44 — /v1/ocr endpoint (Mistral OCR) + Mistral moderation (port upstream 9router#2064, co-authored @waguriagentic). Validated locally: 14 ocr-route tests + moderation/servicekind/endpoint-category suites green (CORS→Zod→handler + no-stack-leak assertion). Reds are inherited DRIFT only: cognitive-complexity ratchet (none from OCR files — pre-existing cycle drift, rebaselined at release) + environmental setup-claude base-red. * fix(codex): convert chat json schema to responses text format (#5933) Integrated into release/v3.8.44 — converts Chat Completions json_schema response_format → Responses API text.format on the Codex path, and preserves existing text.format through verbosity normalization. Base redirected main→release; the openai-responses.ts split that landed this cycle was reconciled by re-applying the delta onto openai-responses/toResponses.ts. Validated locally: 48 translator-openai-responses-req + 8 codex-verbosity tests green. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(providers): add Claude Sonnet 5 support across the model pipeline (#5833) Integrated into release/v3.8.44 — wires claude-sonnet-5 end-to-end (registries, modelSpecs, pricing ×3, cost, Sonnet-family fallback, 1M-ctx, static models). Reconciled the add/add overlap with the already-merged #5796 (kept the PR's superset test with the family-fallback assertion). Validated locally: kiro-sonnet-5 + catalog + pricing/modelSpecs/fallback suites all green. Thanks @ggiak! Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(relay): gate bifrost auto routing by provider manifest (#5870) Integrated into release/v3.8.44 — gates Bifrost auto-routing by the provider plugin manifest (only manifest-eligible providers reach the sidecar; ineligible/unknown fall back to the TS path with explicit reasons). Superset of #5869 (carries the full manifest + registry + docs). Resolved an integration-test conflict in favor of the release (which already subsumes this PR's readiness/removeDirWithRetry improvements). Validated locally: 4 provider-plugin-manifest + 11 relay-routing-backend tests green. Thanks @KooshaPari! Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * refactor(translator): extract pure message helpers from openai-to-kiro (852→751) (#5947) * refactor(translator): extract pure message helpers from openai-to-kiro Extract the pure tool/message helpers (parseToolInput, normalizeKiroToolSchema, serializeToolResultContent) verbatim into the leaf openai-to-kiro/messageHelpers.ts. The host imports them back for convertMessages. They were module-private, so the public export set is unchanged (no re-export needed). Host 852 -> 751 LOC. Byte-identical bodies (multiset 99/99), leaf has zero imports (no cycle). Adds a split-guard; consumer tests stay green (translator-openai-to-kiro 33, translator-ai-sdk-image-parts 3). * chore: re-trigger CI (stuck runner on 2/2 shard) * refactor(executors): extract pure prompt + composer helpers from cursor (#5960) Extract two pure clusters from the cursor executor into sibling leaves: - cursor/prompt.ts: isRecordLike + toolChoiceDirectiveLine + buildCursorOutputConstraints - cursor/composer.ts: composer thinking-as-content decoding (isComposerModel, visibleComposerContentFromThinking, composerReasoningRemainder + markers) Host imports both back for internal use and re-exports the 3 composer helpers for external importers (tests). Host 1576 -> 1451 LOC. Byte-identical bodies (verbatim multiset prompt 65/65, composer 32/32), leaves have zero imports (no cycle). Adds a split-guard; consumer tests stay green (cursor-composer-thinking, cursor-streaming, cursor-agent-tool-calls, translator-openai-to-cursor, cursor-agent-system-prompt). * refactor(executors): extract pure SSE-collect parsing from antigravity (#5962) Extract the pure SSE-payload -> collected-stream parser (AntigravityCollectedStream, stripZeroWidth, parseAntigravityTextualToolCall, addAntigravityTextualToolCall, processAntigravitySSEPayload/Text, flushAntigravitySSEText) verbatim into the leaf antigravity/sseCollect.ts. Host imports the helpers it uses and re-exports processAntigravitySSEPayload for external importers (tests). Host 1812 -> 1671 LOC. Byte-identical bodies (verbatim multiset 135/135), leaf does not import the host (no cycle). Credit/quota state, auth, and HTTP dispatch untouched. Adds a split-guard; consumer tests stay green (executor-agy 8, executor-antigravity 26, antigravity-sse-collect-socket-release, copilot-agent-antigravity-parity 6). * refactor(executors): extract pure model maps + resolvers from chatgpt-web (#5967) Extract the static model maps (MODEL_MAP, MODEL_FORCED_EFFORT, THINKING_CAPABLE_SLUGS) and the pure thinking-effort resolvers (isThinkingCapableModel, normalizeThinkingEffort, resolveThinkingEffort, ResolvedChatGptModel, resolveChatGptModel) verbatim into the pure leaf chatgpt-web/models.ts. Host imports the two resolvers it uses back. Host 3205 -> 3076 LOC. Byte-identical bodies (verbatim multiset 120/120), leaf has zero imports (no cycle). Auth/PoW/session/HTTP dispatch and all module caches untouched. Adds a split-guard; consumer tests stay green (chatgpt-web 86, chatgpt-web-tools-5240 4, chatgpt-web-sha3-boringssl-5531 5). * refactor(executors): decompose grok-web into pure tool/markup leaves (#5994) Extract the pure OpenAI<->Grok tool-translation, native-tool mapping, markup cleanup, and NDJSON stream types out of the 1872-line grok-web executor into 4 sibling leaves: - grok-web/types.ts: GrokStreamResponse/GrokStreamEvent (stream types) - grok-web/tool-bridge.ts: OpenAI<->Grok tool translation + registry + classifiers - grok-web/native-tools.ts: native-tool selection/scoring + native->OpenAI mapping - grok-web/text-cleanup.ts: Grok markup stripping + GrokMarkupFilter Layered, acyclic: types <- tool-bridge <- native-tools; text-cleanup <- types; host imports the leaves. All symbols module-private (no host re-export). Host 1872 -> 887 LOC. Byte-identical bodies (verbatim per-leaf), no cycle, all new leaves <= 800 cap (tool-bridge split at line 753 to stay under). Auth/cookie/TLS/HTTP dispatch untouched. Adds a split-guard; consumer tests stay green (grok-web 62, grok-cli-oauth 15, grok-cli-strip-params 2). * refactor(executors): extract pure quota parsing from codex (#5999) Extract the pure Codex quota-snapshot parsing + reset/cooldown scheduling (CodexQuotaSnapshot, parseCodexQuotaHeaders, getCodexResetTime, getCodexDualWindowCooldownMs) verbatim into the leaf codex/quota.ts. Host re-exports the 4 symbols so handlers/chatCore/codexQuota.ts + tests keep resolving. Host 1539 -> 1427 LOC. Byte-identical bodies (verbatim 98/98), leaf has zero imports (only Date, no cycle). WS transport, auth, HTTP dispatch untouched. Adds a split-guard; consumer tests stay green (executor-codex 40, codex-quota-fetcher 7, chatcore-codex-quota 5). * refactor(executors): extract pure stream formatters from deepseek-web (#6000) Extract the pure content/citation formatters (isThinkingModel, isSearchModel, cleanDeepSeekToken, formatStreamContent, DeepSeekSearchResult, appendSearchCitations) verbatim into the leaf deepseek-web/stream-format.ts. Host imports the 5 it uses back into transformSSE/collectSSEContent (cleanDeepSeekToken stays internal to the leaf). Host 1147 -> 1108 LOC. Byte-identical bodies (verbatim 34/34), leaf has zero imports (no cycle), all module-private (no re-export). PoW/auth/token-cache/HTTP dispatch untouched. Adds a split-guard; consumer tests stay green (deepseek-web 35, deepseek-web-rolling-window-2942 5, deepseek-web-tools-execute 3). * refactor(api): add validatedJsonBody helper (salvage #5075) (#5931) Fuses JSON body parsing + Zod validation into a single call that returns either type-narrowed data or a ready-to-return 400 NextResponse with the standard error envelope. Salvaged as the Tier 1 portable helper from the closed refactor PR #5075; the bulk route migration is intentionally not ported. Adds a focused 6-case regression test. Co-authored-by: KooshaPari <KooshaPari@users.noreply.github.com> * feat(qoder): drive PAT auth via qodercli, add dashboard quota, fix connection display (#5816) Integrated into release/v3.8.44 — Qoder PAT auth via qodercli binary + dashboard quota + dual-auth connection fix. Thanks @AgentKiller45 (co-author @judy459)! Validated locally (release-green on its own merits): lint 0, typecheck:core 0, 104 qoder/usage/UI tests green, file-size gate OK (owner-approved qoderCli.ts baseline-freeze 666→989), env-doc-sync fixed (documented QODER_CLI_CONFIG_DIR). The 2 remaining CI reds are INHERITED base-reds, not caused by this PR: (1) LEDGER-4 minimax-m3 supportsVision (minimax-m3 base + cline-pass/minimax-m3 from the already-merged #5942); (2) mutation-test-coverage missing 3 tests in stryker.conf (#5903/#5942/#5923). Both cleaned up separately. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(providers): minimax-m3 supportsVision (LEDGER-4) + stryker tap.testFiles drift (#6012) Release-green cleanup — clears LEDGER-4 minimax-m3 supportsVision + stryker tap.testFiles drift base-reds. Validated locally. * fix(registry): flag cline-pass/minimax-m3 as multimodal (supportsVision) (#6003) The cline-pass provider's minimax-m3 entry was missing supportsVision, breaking the LEDGER-4 registry-consistency test (all minimax-m3 entries must set supportsVision to match lite.ts — minimax-m3 is multimodal). Every other minimax-m3 registry entry (trae, bazaarlink, cline, ollama-cloud, ...) already sets it. This was a base-red on release/v3.8.44 inherited by every open PR. Validated by the existing failing-then-passing guard tests/unit/review-reviews-v3814-fixes.test.ts (LEDGER-4). * refactor(executors): extract pure payload construction from claude-web (#6006) Extract the pure Claude-web payload types + transforms + default tools/style (ClaudeWebRequestPayload, ClaudeWebStreamChunk, DEFAULT_CLAUDE_MODEL, generateMessageUUIDs, getDefaultTools, getDefaultPersonalizedStyle, transformToClaude, transformFromClaude) verbatim into the leaf claude-web/payload.ts. Host imports the 3 it uses back (ClaudeWebRequestPayload type + the two transforms). Host 1056 -> 835 LOC. Byte-identical bodies (verbatim 149/149), leaf imports only randomUUID (no host import, no cycle), all module-private (no re-export). Cookie/auth/ Turnstile/TLS/HTTP dispatch untouched. Adds a split-guard; consumer tests stay green (claude-web 13, claude-web-auto-refresh 6). * refactor(executors): extract pure upstream-header helpers from base (#6008) Extract the pure upstream-header helpers (mergeUpstreamExtraHeaders, getCustomUserAgent, setUserAgentHeader, applyConfiguredUserAgent, isOpenAICompatibleEndpoint, stripStainlessHeadersForOpenAICompat) verbatim into the leaf base/headers.ts. base.ts is imported by ~18 executors, so the host re-exports all 6 to keep those import paths intact; it also imports the 4 it uses internally in the BaseExecutor class. The trivial JsonRecord type alias is redefined locally in the leaf to avoid a base<->leaf cycle. Host 1539 -> 1451 LOC. Byte-identical bodies (verbatim 78/78), leaf does not import the host (no cycle). typecheck:core validates all base importers still resolve via the re-export. Adds a split-guard; consumer tests stay green (executor-base-utils 22, executor-default-base 49, executor-strip-stainless-openai-compat 6, plus executor sanity via typecheck). * refactor(executors): extract pure wire protocol from perplexity-web (#6014) Extract the pure Perplexity wire protocol (consts, SSE stream types, SSE parsing, OpenAI<->Perplexity message translation, request/query builders, content extraction, sseChunk) verbatim into the leaf perplexity-web/protocol.ts. Host imports back the 10 symbols it uses; everything module-private (no re-export). Session cache, TLS fetch, auth, and the executor class stay in the host. Host 1028 -> 534 LOC. Byte-identical bodies (verbatim), leaf imports only randomUUID (no host import, no cycle). Adds a split-guard; consumer tests stay green (perplexity-web 26, streaming-tools-5927 2, tls-client 6, key-validation-models 2). * refactor(executors): extract pure URL normalizers from default (#6015) Extract the pure per-provider chat-URL normalizers (normalizeBailianMessagesUrl, normalizeDataRobotChatUrl, normalizeAzureAiChatUrl, normalizeWatsonxChatUrl, normalizeOciChatUrl, normalizeSapChatUrl, normalizeXiaomiMimoChatUrl, normalizeOpenAIChatUrl, getOpenRouterConnectionPreset) verbatim into the leaf default/urlNormalizers.ts. Host imports them back into buildUrl/transformRequest; the now-dead build*ChatUrl/normalizeBaseUrl imports move to the leaf. All module-private (no re-export). Host 864 -> 815 LOC (shrunk below its frozen baseline). Byte-identical bodies (verbatim 45/45), leaf does not import the host (no cycle). buildHeaders/execute/auth untouched. Adds a split-guard; consumer tests stay green (executor-default-base 49, anthropic-compatible-bearer 3, strip-client-metadata 3). * feat(webfetch): support self-hosted FireCrawl instances (#5793) Integrated into release/v3.8.44 — self-hosted FireCrawl support (FIRECRAWL_BASE_URL/FIRECRAWL_TIMEOUT_MS). Re-cut clean onto the release tip (branch was fossilized from a pre-v3.8.40 snapshot). Validated: 4 firecrawl tests green, env-doc-sync + docs-sync pass. UNSTABLE red is the inherited environmental setup-claude base-red. * feat(xai): register XaiExecutor with reasoning-effort suffix parsing (#5800) Integrated into release/v3.8.44 — XaiExecutor with reasoning-effort suffix parsing. Re-cut clean onto the release tip (branch was fossilized). Validated: 6 xai-executor tests green, provider-consistency OK, typecheck:core 0 errors, env-doc-sync in sync. UNSTABLE red is the inherited environmental setup-claude base-red. * feat(discovery): Phase 2 — reporter, /api/discovery/* routes (strict loopback-only) + dashboard UI (#5939) * feat(discovery): Phase 2 reporter — discoveryResults DB module + service wiring Adds src/lib/db/discoveryResults.ts (CRUD over the discovery_results table from migration 074) and wires the opt-in discovery service to persist and read findings through it: persistDiscoveryResult / getDiscoveryResults / getDiscoveryResultById / markVerified / deleteDiscoveryResult, with (provider, method, endpoint) upsert de-duplication. Re-exported from localDb. The service stays opt-in / default-off. The /api/discovery/* routes and the dashboard UI tab are intentionally deferred to Phase 2b — they need the local-only enforcement model (Hard Rules #15/#17 territory) decided first. TDD: tests/unit/db/discovery-results.test.ts (8 cases, DB + service delegation), isolated DATA_DIR with resetDbInstance cleanup. * feat(discovery): Phase 2b — /api/discovery/* routes (strict loopback-only) Adds the discovery HTTP surface on top of the reporter DB module: GET /api/discovery/results list findings (optional ?providerId) GET /api/discovery/results/:id one finding (404 if absent) DELETE /api/discovery/results/:id delete a finding POST /api/discovery/scan scan a provider + persist findings POST /api/discovery/verify/:id mark a finding verified Authorization: strict loopback-only. "/api/discovery/" is added to LOCAL_ONLY_API_PREFIXES so the central authz pipeline (proxy.ts → runAuthzPipeline → managementPolicy) rejects non-loopback callers with a 403 LOCAL_ONLY before any handler runs. It is deliberately NOT in LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES — no remote manage-scope bypass — because POST /scan issues outbound probes to provider endpoints (SSRF-adjacent) and must never be tunnel-reachable. Handlers also call requireManagementAuth (defense in depth) and return sanitized errors via createErrorResponse. Tests: - tests/unit/authz/discovery-routes-local-only.test.ts (8) — security guard: isLocalOnlyPath true + not manage-scope-bypassable for all four paths. - tests/unit/api/discovery-routes.test.ts (6) — handler integration over an isolated DATA_DIR: list/filter, by-id 200/404/400, scan persist + 400 on empty/malformed body, verify 200/404, delete 200/404, no stack-trace leak. * feat(discovery): Phase 2c — dashboard UI tab (Tools → Discovery) Adds the /dashboard/discovery page (DiscoveryPageClient) that consumes the Phase 2b /api/discovery/* routes: scan a provider, list findings, verify or delete them. Registered in the sidebar under the Tools group (icon travel_explore) and given a "discovery" i18n namespace + sidebar keys in en.json (other locales fall back to en via next-intl until synced — the locale files are in a pre-existing coverage deficit unrelated to this change). Registers the UI test path in vitest.config.ts (advisory ui suite). Tests: src/app/(dashboard)/dashboard/discovery/__tests__/DiscoveryPageClient.test.tsx (3 cases: loads+renders results, empty state, fetches /api/discovery/results on mount; stable useTranslations mock to avoid the fetch-loop). NOTE: the ui vitest suite cannot run in this workspace — @testing-library/dom (a @testing-library/ react peer dep) is absent from node_modules, which fails ALL existing ui tests equally; the test runs in CI. Component verified locally via typecheck + lint. * test(discovery): register discovery-routes-local-only in stryker tap.testFiles The mutation-test-coverage gate (--strict) flags any unit test covering a mutated module that isn't listed in stryker.conf.json tap.testFiles. This PR's tests/unit/authz/discovery-routes-local-only.test.ts covers src/server/authz/ routeGuard.ts (a mutated module, which this PR edits by adding the /api/discovery/ local-only prefix), so it must be registered for its mutant kills to count. No behavior change. * refactor(discovery): split DiscoveryPageClient to satisfy max-lines-per-function The complexity ratchet (max-lines-per-function: 80) flagged the single 184-line DiscoveryPageClient function (+1 over baseline). Extract the data layer into two hooks (useDiscoveryResults for list/loading/feedback, useDiscoveryActions for scan/verify/delete), a shared callApi helper, and two presentational sub-components (DiscoveryScanForm, DiscoveryResultCard). Every function is now under the 80-line ceiling; complexity gate back to baseline 1995. No behavior change — same exported component, same endpoints, same props. * test(sidebar): include discovery in omni-proxy item-order snapshot Adding the Discovery item to the Tools group (this PR's sidebar entry) extends the ordered omni-proxy section list. Update the exact-match deepEqual snapshot in sidebar-visibility.test.ts to include "discovery" in its position (after traffic-inspector). The assertion stays exact — this reflects the intentional new item, it does not weaken the check. * docs(changelog): restore release bullets eaten by merge auto-resolve; re-add discovery bullet additively * chore(quality): bump testFrozen for translator-openai-responses-req.test.ts (1097 -> 1172) Base-red inherited from #5933, which grew the test file to 1171 lines (Hard Rule #18 regression tests) without adjusting the frozen cap. The release tip itself fails check:file-size; this unblocks every PR into release/v3.8.44. File untouched by this PR. * chore(quality): restore stryker tap.testFiles entries eaten by merge auto-resolve The merge of origin/release/v3.8.44 silently dropped the 3 entries added on the release side (#5903, clinepass, #5923). Took the release version verbatim and re-added only this PR's entry (discovery-routes-local-only) in alphabetical order. check:mutation-test-coverage green locally. * chore(quality): reconcile inherited v3.8.44 merge-burst drift + include discovery in tools-group order test - complexity 1995->2003 and cognitive 856->859: both measure IDENTICAL on the pristine release tip (3a3d618fe) and this PR's merged HEAD — the PR is complexity-net-zero; drift is from the 2026-07-02 merge burst (notes added to both baselines, same family as prior reconciliations). - sidebar-tools-group.test.ts: append 'discovery' to the expected TOOLS_GROUP order — the intentional new sidebar item this PR adds (same expected-value update already made in sidebar-visibility.test.ts). * feat(providers): custom icon URL for compatible provider nodes (#5815) Integrated into release/v3.8.44 — custom icon URL for compatible provider nodes (DB migration 113 + nodes.ts + Zod schema + API routes + catalog + ProviderIcon UI). Re-cut onto the release tip (branch was fossilized ~13 real files); reconciled icon_url into the release's evolved nodes.ts/routes via 3-way. Validated: 14 backend + 5 frontend(vitest) + 24 page-utils tests green, typecheck:core 0, provider-consistency OK, file-size/env-doc-sync pass. UNSTABLE red is the inherited environmental setup-claude base-red. * feat(api): add /v1/audio/translations endpoint (#5809) Integrated into release/v3.8.44 — /v1/audio/translations endpoint (Whisper-style audio translation) + audioTranslation handler + translation providers in audioRegistry. Re-cut clean onto the release tip (branch was fossilized). Validated: 8 route tests (incl. no-stack-leak), typecheck:core 0, route-guard-membership OK, docs gates pass. UNSTABLE red is the inherited environmental setup-claude base-red. * feat(dashboard): wildcard-CORS runtime warning + CORS security doc (#5602) (#5759) Integrated into release/v3.8.44 — wildcard-CORS runtime warning banner + docs/security/CORS.md security guide (#5602). Re-cut clean onto the release tip (branch was fossilized). Validated: 20+9 backend + 2 banner(vitest) tests green, typecheck:core 0, docs-sync/symbols/fabricated/doc-links pass. UNSTABLE red is the inherited environmental setup-claude base-red. * refactor(executors): extract pure JSONL stream translation from huggingchat (#6016) Extract the pure JSONL->OpenAI-SSE translation (sseChunk, parseJsonlLine, streamJsonlToOpenAi, readJsonlResponse) verbatim into the leaf huggingchat/jsonlStream.ts. They consume a passed-in ReadableStream (no fetch/network/state). Host imports back the two it uses; all module-private (no re-export). Host 812 -> 594 LOC. Byte-identical bodies (verbatim), leaf has zero imports (no cycle). Cookie/auth/multipart/execute untouched. Adds a split-guard; consumer tests stay green (executor-huggingchat 6, huggingchat-model-catalog 3). * refactor(executors): extract pure Meta AI response parser from muse-spark-web (#6017) Extract the pure Meta AI SSE/JSON response parsing + content/reasoning/error extraction (parseMetaSseFrames, readMetaJsonPayloads, collect*/extract*/classify* helpers, parseMetaAiResponseText, isRecord, the reasoning/renderer key arrays, MetaSseFrame/ ParsedMetaAiResponse types) verbatim into the leaf muse-spark-web/response-parser.ts. Host imports back the 3 it uses; all module-private (no re-export). Host 1301 -> 925 LOC. Byte-identical bodies (verbatim), leaf has zero imports (no cycle). Conversation cache, cookie/auth, fetch, executor class untouched. Adds a split-guard; consumer tests stay green (muse-spark-cookie-copy-5449 2, muse-spark-web-continuation 6). * refactor(executors): extract pure EventStream framing from kiro (#6018) Extract the pure AWS EventStream binary framing (ByteQueue, CRC32 table + crc32, TEXT_ENCODER/TEXT_DECODER, KIRO_VERIFY_FULL_CRC, parseEventFrame, EventFrame type) verbatim into the self-contained leaf kiro/eventstream.ts (local JsonRecord alias to avoid a cycle). Host imports back the 3 it uses (ByteQueue, TEXT_ENCODER, parseEventFrame). Host 943 -> 758 LOC. Byte-identical bodies (verbatim 145/145), leaf has zero host imports (no cycle). Auth/token-refresh/streaming-state/executor class untouched; the test-imported flushBufferedToolArgs/resolveKiroRegion/kiroRuntimeHost stay exported on the host. Adds a split-guard; consumer tests stay green (executor-kiro 9, kiro-tool-args-streaming 7, kiro-iam-region 10). * refactor(executors): extract challenge solver from duckduckgo-web (#6020) Extract the DuckDuckGo anti-abuse challenge solver + FE signals (CHALLENGE_STUBS, countHtmlElements, buildHtmlLookup, sha256Base64, solveDuckDuckGoChallenge, makeDuckDuckGoFeSignals) verbatim into the leaf duckduckgo-web/challenge.ts. The vm sandbox + 5s timeout (SECURITY note) are preserved. Host imports back the two it uses. Host 924 -> 788 LOC. Byte-identical bodies (verbatim 132/132), leaf does not import the host (no cycle). The now-dead createHash/parse5 host imports are removed; vm stays (still used in host). Auth/cookie/warm/seed/executor untouched. Adds a split-guard; consumer tests stay green (duckduckgo-web-executor 15, duckduckgo-domain-4037 8). * test(cli): deflake setup-claude.test.ts — silence console to stop stdout/report interleaving (#5959) (#6019) Integrated into release/v3.8.44. Deflakes tests/unit/cli/setup-claude.test.ts (#5959) — verified in CI: setup-claude now passes in Unit Tests fast-path (2/2). Merged with --admin over two PRE-EXISTING base-reds proven independent of this test-only change (this PR only touches setup-claude.test.ts + CHANGELOG): - Fast Quality Gates → check:test-discovery: tests/unit/executors/{firecrawl-fetch,xai-executor}.test.ts are orphaned on release/v3.8.44 (added by #5793/#5800); the shard glob 'tests/unit/{api,...,ui}/**' omits 'executors'. Both blobs exist on the pristine base. - Unit Tests fast-path (2/2): tests/unit/settings-i18n-keys.test.ts → 'direct translation calls have English messages' fails on the pristine base too (unrelated i18n base-red). * fix(cli): stabilize setup-claude.test.ts flake — inject dry-run log sink (#6021) * fix(cli): stabilize setup-claude.test.ts flake — inject dry-run log sink (#5959) Root cause (isolated empirically, 5/10 fail on the pristine base): the dry-run path of syncClaudeProfilesFromModels console.log's a multi-byte box-drawing heading ("── [dry-run] … ──"). Under the node:test runner that write lands on the test child's stdout and corrupts the runner's V8-serialized event stream ~50% of the time ("Unable to deserialize cloned data due to invalid or unsupported version"), killing the file at the first logging test. ASCII-only logging never reproduced it (0/20); the unicode heading alone reproduced it (10/20). Fix: syncClaudeProfilesFromModels accepts an injectable log sink (opts.log, CLI default unchanged: console.log). The dry-run test injects a collector — keeping unicode off the child's stdout — and gains assertions on the dry-run report (path + parsed settings content), which FAIL on the old code (log ignored) and PASS on the new one. Validation: 0/30 failures post-fix vs 5/10 pre-fix on the same tree. Baselines: complexity 2003->2006 and cognitive 859->860 are inherited post-3a3d618fe release drift — measured identical on the pristine base with and without this change (notes added in both files). * test(ci): collect the orphaned tests/unit/executors/ directory (base-red unblock) #5800 created tests/unit/executors/ outside every unit-runner brace glob, so its 2 test files (firecrawl-fetch, xai-executor) never ran anywhere and check:test-discovery flags them as NEW orphans on the pristine base, red-flagging every PR into release/v3.8.44. Added 'executors' to the runner globs in package.json (7 scripts), ci.yml unit shards, quality.yml TIA glob, build-test-impact-map.mjs, and the test-discovery gate's COLLECTORS (the gate enforces those stay in sync). Both files pass when actually collected (10/10); cli+executors under suite flags: 99/99. * chore(quality): complexity baseline 2006 -> 2007 (CI-observed value) The GitHub fast-gates runner measures 2007 where local measures 2006 — the same local-vs-CI off-by-one documented in the 2026-06-26 note. Pin the CI-observed value so the gate is deterministic where it runs. * fix(i18n): add the 6 missing en.json keys flagged by settings-i18n-keys (base-red unblock) providers.iconUrlLabel/iconUrlHint (referenced by AddCompatibleProviderModal and EditCompatibleNodeModal) and settings.authz.cors.wildcard.title/desc (the #5602 CORS_ALLOW_ALL banner in AuthzSection) shipped without their en.json messages — 'direct translation calls have English messages' fails on the pristine release tip, red-flagging every PR. git log -S proves the keys never existed (not a merge-eat). Scanner test: 10/10 green. * refactor(executors): extract reasoning-effort (base) + tool-normalization (codex) leaves (#6030) Two pure-leaf follow-ups closing the Block H tail: - base/reasoningEffort.ts: provider-aware reasoning_effort sanitation (MISTRAL/GITHUB reject patterns, supportsMaxEffortForProvider, sanitizeReasoningEffortForProvider). Deps are config/services only (PROVIDER_CLAUDE, isClaudeCodeCompatible, supportsClaudeMaxEffort/supportsXHighEffort) so the leaf never imports the host — no cycle. base.ts re-exports sanitizeReasoningEffortForProvider for its external importers (mimoThinking + tests). base.ts 1466 -> 1312 LOC. - codex/tools.ts: Responses-API tool normalization (CODEX_HOSTED_TOOL_TYPES hosted-tool passthrough, isCodexFreePlan gating, normalizeCodexTools). Self-contained (console.debug only). codex.ts re-exports isCodexFreePlan + normalizeCodexTools for external importers (tests + provider services). codex.ts 1430 -> 1268 LOC. Byte-identical bodies (verbatim: base 100/100, codex 126/126); both leaves have zero host imports. Adds two split-guards asserting the leaf owns the symbol and both import paths resolve to the same function. Consumer tests stay green (base-executor-sanitize-effort 34, executor-codex 40, mimoThinking 9, codex-free-plan-image-generation 3, issue-fixes 6). * test(ci): move orphaned executor tests to top-level so a runner collects them (#6027) Integrated into release/v3.8.44 — collect orphaned executor tests (check:test-discovery base-red). * test(cli): deflake cli-setup-opencode.test.ts — silence console (#5959-class landmine) (#6033) The command under test prints CLI progress with multi-byte glyphs (printSuccess "✔" in the happy paths, printError "✖" in the dist-missing path that test 4 exercises) via console.log. Under the node:test runner those child-stdout writes interleave with the V8-serialized report frames and can corrupt the stream — the exact #5959 mechanism proven for setup-claude.test.ts; this file's ✖ line was already visible entangled in red CI runs. No test here asserts on stdout, so silence console.log/info/ warn for the file (same pattern as #6019/#6021, restored in after()). Validation: pre-fix the ✖/✔ lines reach stdout every run (grep-able); post-fix stdout is clean, 4/4 tests green, 0/20 failures across 20 runs. * feat(agy): support Google Cloud project ID settings (#5905) * feat(agy): support Antigravity project ID settings * refactor(agy): collapse Antigravity family project gate --------- Co-authored-by: Nikolay Alafuzov <alafuzov_nn@rusklimat.ru> * feat(proxy): add Webshare proxy pool import and sync (#5993) * feat(proxy): add Webshare proxy pool import and sync Adds Webshare (https://proxy.webshare.io) as a fourth source in the free-proxy provider framework alongside 1proxy, Proxifly, and IPLocate. WebshareProvider paginates the account's `/api/v2/proxy/list/` endpoint (Authorization: Token <key>), upserts proxies into the shared `free_proxies` table via the existing db/freeProxies.ts helpers, and tombstones proxies the account no longer lists (recycled/retired IDs) while never touching rows already promoted into the live proxy pool. Unlike the other sources, Webshare is a paid per-account list, so it is gated on FREE_PROXY_WEBSHARE_API_KEY rather than a plain on/off flag. No DB migration needed — reuses the existing free_proxies table and proxy_registry-on-promote path. Co-authored-by: ricatix <d.enistraju155@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1176 * chore(changelog): restore release entries + add webshare bullet --------- Co-authored-by: ricatix <d.enistraju155@gmail.com> * feat(api-keys): add per-key device/connection tracking (#5998) * feat(api-keys): add per-key device/connection tracking Tracks distinct client devices (SHA-256 fingerprint of IP + User-Agent) seen with each API key, with a 30-minute TTL and per-key/global caps. The tracker is in-memory only (module-scoped Map, same pattern as sessionManager.ts — no global.* singleton) and never stores the raw IP: it is masked before being written. Hooked into open-sse/handlers/chatCore.ts (the real chat entry) rather than the legacy src/sse/handlers path. New GET /api/keys/[id]/devices management route exposes masked device details for a key, and the API Keys dashboard tab gets a "Devices" count badge alongside the existing Sessions badge. This is a new granularity distinct from the existing maxSessions cap (src/lib/db/apiKeys.ts), which limits concurrent sticky-routing sessions rather than tracking device identity. Co-authored-by: Muhammad Mugni Hadi <mugni@rukita.co> Inspired-by: https://github.com/decolua/9router/pull/931 * chore(changelog): restore release entries + add api-keys device-tracking bullet --------- Co-authored-by: Muhammad Mugni Hadi <mugni@rukita.co> * fix(providers): only apply openai-family model inference fallback when no cataloged provider serves the id (#5852) (#5938) resolveModelByProviderInference() in open-sse/services/model.ts had an unconditional /^gpt-/i heuristic that hijacked any model id starting with gpt-/o1/o3 into provider openai, even when the id is cataloged under other providers. This broke bare (non-combo) requests for open-weight models like gpt-oss-120b (served by fireworks/cerebras/scaleway/byteplus/sambanova/ heroku), which don't exist on openai's catalog, producing a 404 with no fallback. Gate the heuristic on providers.length === 0 so it only fires for genuinely uncataloged openai-family ids, letting cataloged ids fall through to the existing single-candidate / ambiguous-candidate resolution paths. Regression guard: tests/unit/gptoss-provider-inference-5852.test.ts * fix(cc-compatible): send SSE accept for streamed requests (#5958) Integrated into release/v3.8.44 — SSE Accept header for streamed cc-compatible requests (thanks @rdself). * fix: deepseek-web reliability — auto-refresh on 401/403, refresh v2.0.0 client headers, fix token-kind bulk import (#5988) Integrated into release/v3.8.44 — deepseek-web auto-refresh + v2.0.0 headers + token-kind bulk import (thanks @backryun). * feat(providers): support Vercel AI Gateway embeddings and images (#5968) * feat(providers): support Vercel AI Gateway embeddings and images Extends the existing vercel-ai-gateway (alias vag) provider — currently chat-only — with embeddings and image generation support, since the gateway's OpenAI-compatible /v1 API also exposes /embeddings and /images/generations. Adds entries to EMBEDDING_PROVIDERS (embeddingRegistry.ts) and IMAGE_PROVIDERS (imageRegistry.ts) modeled on the existing openai entries. Out of scope for this PR (tracked as follow-ups): the /v1/credits usage reader, retry:{429:2} tuning, and claude->reasoning_effort mapping. Co-authored-by: Ngô Tấn Tài <tantai@newnol.io.vn> Inspired-by: https://github.com/decolua/9router/pull/1704 * chore(changelog): restore release entries + add vercel-gateway media bullet --------- Co-authored-by: Ngô Tấn Tài <tantai@newnol.io.vn> * feat(cli-tools): add Crush CLI tool to the dashboard (#5970) * feat(cli-tools): add Crush CLI tool to the dashboard Add a `crush` entry to the dashboard CLI-Tools catalog and a new `/api/cli-tools/crush-settings` route (GET/POST/DELETE), cloned from the `pi` tool's route as a template. OmniRoute already ships a `crush` CLI command path (bin/cli/commands/setup-crush.mjs) but the dashboard catalog had no matching entry. The new route writes the real Crush config shape (providers.omniroute as an openai-compat provider block) to the same canonical config path (~/.config/crush/crush.json) that setup-crush.mjs's resolveCrushTarget() already writes to, so the dashboard and the CLI command agree on one location. Adds CLI_TOOL_RUNTIME_CONFIG.crush for detection/status, and bumps EXPECTED_CODE_COUNT (18 -> 19) plus the catalog-count/schema tests that enumerate the full tool list. Co-authored-by: dopaemon <polarisdp@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1233 * chore(changelog): restore release entries + add crush cli bullet --------- Co-authored-by: dopaemon <polarisdp@gmail.com> * feat(dashboard): suggest HuggingFace Hub media models (#5990) * feat(dashboard): suggest HuggingFace Hub media models MVP scope: - imageRegistry.ts: add an image kind entry for the huggingface provider (HF Inference API text-to-image), with a dedicated "huggingface-image" format since the endpoint returns raw image bytes rather than JSON. - New handler open-sse/handlers/imageGeneration/providers/huggingface.ts, wired into imageGeneration.ts's format dispatch. - New pure helper module open-sse/services/hfModelSuggestions.ts: maps a dashboard media kind to an HF Hub pipeline_tag and sorts/limits raw HF Hub search results (unit-tested directly). - New route GET /api/v1/providers/suggested-models proxies the public HF Hub models search API server-side (Zod-validated query, buildErrorBody on every error path, no HF token exposed client-side — this project has no server-side HF search token config, so it calls unauthenticated). - UI: ImageExampleCard now fetches suggested HF Hub models for the huggingface provider and merges them into the model picker as a selectable chip row, alongside the existing static provider models list. - i18n: adds media.suggestedModels to en.json only. Co-authored-by: yicone <yicone@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1633 * chore(changelog): restore release entries + add hf-hub media suggest bullet --------- Co-authored-by: yicone <yicone@gmail.com> * feat(dashboard): collapse and sort provider quota rows by remaining (#5977) * feat(dashboard): collapse and sort provider quota rows by remaining Sort the expanded quota list by remaining percentage (highest first) and collapse it to the first 3 rows by default, with a "Show N more" / "Show less" toggle when a connection reports more than 3 quotas. This keeps the most at-risk quotas out of view below a long list of healthy ones. Extracts the sort/slice logic into pure helpers (sortQuotasByRemaining, getVisibleQuotas) exported from QuotaCardExpanded.tsx and unit-tests them directly. Co-authored-by: CườngNH <j2.cuong@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1919 * chore(changelog): restore release entries + add quota collapse/sort bullet --------- Co-authored-by: CườngNH <j2.cuong@gmail.com> * feat(providers): refresh The Old LLM (Free) model catalog (#5181) * feat(dashboard): add tool-source diagnostics settings toggle (#5978) * feat(dashboard): add tool-source diagnostics settings toggle Adds a Settings > Advanced card (cloned from DebugModeCard) that lets operators flip the existing `logToolSources` flag from the UI instead of editing the DB row directly. The backend gate (chatCore.ts) and DB default were already present but had no toggle. Also adds `logToolSources` to the /api/settings Zod PATCH schema (it is `.strict()`, so the key was previously rejected) and en-only i18n strings. Co-authored-by: DuyPrX <93126969+DuyPrX@users.noreply.github.com> Inspired-by: https://github.com/decolua/9router/pull/1825 * chore(changelog): restore release entries + add tool-source toggle bullet --------- Co-authored-by: DuyPrX <93126969+DuyPrX@users.noreply.github.com> * feat(oauth): import Codex connection from a raw ChatGPT access token (#5995) * feat(oauth): import Codex connection from a raw ChatGPT access token OmniRoute's only Codex import path (/api/oauth/codex/import) required both access_token and refresh_token, leaving no import path for a user who only has a bare ChatGPT website access token (no refresh token). - src/lib/db/providers.ts: createProviderConnection gains an explicit authType "access_token" branch — intentionally never deduped (no stable long-lived identity to match on) — and derives the connection name from email/name the same way "oauth" does. - src/lib/oauth/services/codexImport.ts: export extractCodexAccountInfo so the new import path reuses the existing JWT decode instead of duplicating one. - New route POST /api/oauth/codex/import-token (Zod-validated body { accessToken, name? }); errors routed through buildErrorBody / sanitizeErrorMessage. The executor's refreshCredentials() already degrades safely to null when there is no refresh token, forcing re-auth on expiry instead of a refresh exchange. - OAuthModal.tsx: the callback-URL manual-paste path for codex now detects an eyJ-prefixed pasted token and posts it to the new endpoint, mirroring the existing grok-cli raw-token paste pattern. Co-authored-by: ryanngit <74137224+ryanngit@users.noreply.github.com> Inspired-by: https://github.com/decolua/9router/pull/1290 * chore(changelog): restore release entries + add codex token-import bullet --------- Co-authored-by: ryanngit <74137224+ryanngit@users.noreply.github.com> * fix(resilience): parse Retry-After from 429 JSON body for cooldown (#5974) Integrated into release/v3.8.44 — parse Retry-After from 429 JSON body for cooldown (incl. #6013 retry-after-json extraction by @KooshaPari). * fix(embeddings): forward connection-level proxy to embedding requests (#5975) Integrated into release/v3.8.44 — forward connection-level proxy to embedding requests. * fix(api): guard shared API client against non-JSON error responses (#5973) Integrated into release/v3.8.44 — guard shared API client against non-JSON error responses. * feat(dashboard): surface Codex banked reset credits per account (#5199) * feat(providers): add NVIDIA NIM image generation (#5971) * feat(providers): add NVIDIA NIM image generation NVIDIA already exists as a chat provider (integrate.api.nvidia.com, OpenAI-compatible) but image generation is served on a different host (ai.api.nvidia.com/v1/genai/<model>) with a native NIM body shape, so it gets a dedicated `nvidia-nim` image format and handler rather than reusing the OpenAI image path. Adds the 4 FLUX models (flux.1-dev, flux.1-schnell, flux.1-kontext-dev, flux.2-klein-4b) to IMAGE_PROVIDERS, plus handleNvidiaNimImageGeneration() which shapes the per-model NIM request body (flux.1-dev's mode/cfg_scale and 768-1344px/64px-increment dimension validation, flux.1-kontext-dev's required input image + aspect_ratio, schnell/klein's optional array-form edit image) and normalizes the NIM response (artifacts[]/images[]/data[]/ single-value shapes) into the OpenAI `{created, data}` shape. Co-authored-by: eng2007 <aleksey.semenov@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1195 * chore(changelog): restore release entries + add nvidia-nim image bullet --------- Co-authored-by: eng2007 <aleksey.semenov@gmail.com> * feat(providers): add Augment (Auggie CLI) local provider (#5972) * feat(providers): add Augment (Auggie CLI) local provider Adds a new local, no-auth provider that spawns the user's local `auggie` CLI (`auggie --print --quiet --model <m> --`) and pipes a flattened prompt via stdin, wrapping stdout as an OpenAI-compatible SSE stream or a single chat.completion JSON body depending on the request's `stream` flag. Auth is delegated entirely to `auggie login` outside OmniRoute — the connection is registered `noAuth: true` and `refreshCredentials()` is a no-op, matching the existing `NOAUTH_PROVIDERS` credential-less flow (synthetic connection, no DB row required). An optional connection row is still admitted via `FREE_APIKEY_PROVIDER_IDS` for display/priority tracking, consistent with `opencode`. The dashboard "Test Connection" flow spawns `auggie --version` to confirm the CLI is installed and runnable, since there is no API key to validate upstream. Security hardening (spawn is an untrusted-input sink): - Command injection: spawn no longer passes `shell: true` on Windows. The binary is resolved to a concrete path/name and argv is handed straight to the OS loader, so no cmd.exe metacharacter interpretation is possible. - Argument injection (flag smuggling): `model` is validated against the registry allowlist (`auggieProvider.models`) before any spawn — a model that is unknown or starts with "-" is rejected with a sanitized error and the subprocess is never started. A trailing `--` marks end-of-options in the argv as belt-and-suspenders. Co-authored-by: chamdanilukman <16629923+chamdanilukman@users.noreply.github.com> Inspired-by: https://github.com/decolua/9router/pull/1200 * test(golden): regenerate translate-path for auggie provider --------- Co-authored-by: chamdanilukman <16629923+chamdanilukman@users.noreply.github.com> * feat(providers): add ModelScope OpenAI-compatible provider (#5965) * feat(providers): add ModelScope OpenAI-compatible provider Ports ModelScope (Alibaba 魔搭) as a new API-key, OpenAI-compatible provider — upstream 9router PR #1764. The upstream PR hardcoded `https://api-inference.modelscope.ai/...` (`.ai` TLD); verified against ModelScope's own API-Inference docs and third-party integration guides that the real production domain is `api-inference.modelscope.cn` (`.cn` TLD) and shipped that instead. Also drops the PR's static 5-model snapshot in favor of `passthroughModels: true` with an empty seed list + `modelsUrl`, since ModelScope's open-model catalog moves fast. Updates the providers-constants-split characterization test's hardcoded APIKEY_PROVIDERS count (159 -> 160) to match the new entry. Co-authored-by: Umar Javed <114807145+tn5052@users.noreply.github.com> Inspired-by: https://github.com/decolua/9router/pull/1764 * chore(changelog): restore release entries + add modelscope bullet * test(golden): regenerate translate-path for modelscope provider --------- Co-authored-by: Umar Javed <114807145+tn5052@users.noreply.github.com> * feat(providers): add Qiniu OpenAI-compatible provider (#5966) * feat(providers): add Qiniu OpenAI-compatible provider Wires Qiniu (七牛云) AI inference gateway as a BYOK API-key provider. Qiniu proxies many upstream models (DeepSeek V3/V4, Claude, Kimi and more) behind a single key, so it ships with an empty static seed and relies on passthroughModels + the live /v1/models catalog instead of a single stale hardcoded model id. - metadata: src/shared/constants/providers/apikey/gateways.ts - registry entry: open-sse/config/providers/registry/qiniu/index.ts (format openai, executor default, bearer auth, baseUrl https://api.qnaigc.com/v1/chat/completions, modelsUrl https://api.qnaigc.com/v1/models) - added to NAMED_OPENAI_STYLE_PROVIDERS so model import serves the live catalog and falls back to the (empty) local catalog on error, same pattern as the existing dgrid/zenmux/orcarouter gateways - tests: tests/unit/qiniu-provider.test.ts (metadata, registry resolution, passthrough validation, live /v1/models fetch + fallback) Co-authored-by: JiangZhuo <jiangzhuo@qiniu.com> Inspired-by: https://github.com/decolua/9router/pull/911 * chore(changelog): restore release entries + add qiniu bullet * test(golden): regenerate translate-path for qiniu provider * test(providers): bump APIKEY count 160→161 for qiniu --------- Co-authored-by: JiangZhuo <jiangzhuo@qiniu.com> * feat(providers): add b.ai OpenAI-compatible provider (#5969) * feat(providers): add b.ai OpenAI-compatible provider Adds bai as a new OpenAI-compatible BYOK provider, distinct from the existing thebai/theb.ai provider, using passthrough model discovery (no hardcoded model list, live catalog served from api.b.ai/v1/models). Co-authored-by: Delynn Assistant <zhen@dkzhen.org> Inspired-by: https://github.com/decolua/9router/pull/963 * test(golden): regenerate translate-path for b.ai provider * test(providers): bump APIKEY count 161→162 for b.ai --------- Co-authored-by: Delynn Assistant <zhen@dkzhen.org> * feat(providers): add Nube.sh OpenAI-compatible provider (#5936) * feat(providers): add Nube.sh OpenAI-compatible provider Nube.sh is a live BYOK OpenAI-compatible gateway (LiteLLM proxy) at https://ai.nube.sh/api/v1, Bearer/API-key auth. Registered as an apikey inference-host with an OpenAI-format, default-executor registry entry. Its live model catalog is only reachable with a valid key (/api/v1/models returns 401 unauthenticated), so no model IDs are hardcoded — the entry uses passthroughModels + modelsUrl for live enumeration instead of shipping unverifiable IDs. Co-authored-by: whale9820 <87256750+whale9820@users.noreply.github.com> Inspired-by: https://github.com/decolua/9router/pull/2294 * test(golden): regenerate translate-path for nube provider * test(providers): bump APIKEY count 162→163 for nube --------- Co-authored-by: whale9820 <87256750+whale9820@users.noreply.github.com> * feat(providers): add Charm Hyper OpenAI-compatible provider (#5961) * feat(providers): add Charm Hyper OpenAI-compatible provider Registers Charm Hyper (hyper.charm.land) as a new API-key gateway provider: OpenAI-compatible chat completions format, bearer auth, free tier (100 monthly Hypercredits). Models are resolved via passthrough (modelsUrl + live /v1/models import) instead of a hardcoded upstream model list, since the specific model catalog is not publicly documented. Co-authored-by: whale <admin@dyntech.cc> Inspired-by: https://github.com/decolua/9router/pull/2006 * test(golden): regenerate translate-path for charm-hyper provider * test(providers): bump APIKEY count 163→164 for charm-hyper --------- Co-authored-by: whale <admin@dyntech.cc> * feat(providers): add SumoPod and X5Lab OpenAI-compatible providers (#5963) * feat(providers): add SumoPod and X5Lab OpenAI-compatible providers Both are OpenAI-compatible BYOK aggregator gateways, wired via the default executor with bearer API-key auth. Neither ships a hardcoded model list — both use passthroughModels with an empty seed list and a live /v1/models fetcher, so the catalog always reflects what each gateway actually serves instead of speculative model IDs. - SumoPod: https://ai.sumopod.com/v1/chat/completions (sk- keys) - X5Lab: https://api.x5lab.dev/v1/chat/completions (x5- keys) Regression guard: tests/unit/sumopod-x5lab-provider.test.ts. Co-authored-by: Rigel Ramadhani Waloni <rigel8911@gmail.com> Inspired-by: https://github.com/decolua/9router/pull/1288 * chore(changelog): restore release entries + add sumopod/x5lab bullet * test(golden): regenerate translate-path for sumopod + x5lab providers * test(providers): bump APIKEY count 164→166 for sumopod + x5lab --------- Co-authored-by: Rigel Ramadhani Waloni <rigel8911@gmail.com> * feat(server): support reverse-proxy basePath deployment (#5992) * feat(server): support reverse-proxy basePath deployment Adds OMNIROUTE_BASE_PATH (opt-in, empty by default) to next.config.mjs using Next.js's native basePath support so a deployment behind a reverse-proxy subpath (e.g. https://host/omniroute/) works without manual header stripping. Next.js strips the configured prefix from nextUrl.pathname before route classification, so classifyRoute() and isLocalOnlyPath() keep matching un-prefixed paths. The two hardcoded auth redirect targets in src/server/authz/pipeline.ts (root "/" -> "/dashboard" and unauthenticated dashboard -> "/login") now prefix with request.nextUrl.basePath so they stay inside the deployed subpath. Default empty basePath is a no-op for existing root-path deployments. Co-authored-by: zocomputer <help@zocomputer.com> Inspired-by: https://github.com/decolua/9router/pull/1810 * docs(env): document OMNIROUTE_BASE_PATH in .env.example + ENVIRONMENT.md; restore changelog * docs(env): document AUGGIE_BIN + CLI_AUGGIE_BIN (base-red from #5972 auggie) --------- Co-authored-by: zocomputer <help@zocomputer.com> * refactor(combo): extract buildTargetTimeoutRunner from handleComboChat (#6036) Bloco J (hot-path decomposition), Task 1. Extract the per-target-timeout dispatch wrapper (handleComboChat's handleSingleModelWithTimeout closure) verbatim into the leaf combo/targetTimeoutRunner.ts as a factory buildTargetTimeoutRunner({handleSingleModel, comboTargetTimeoutMs, log}). The per-model abort still comes from target.modelAbortSignal, so the outer request signal is intentionally not a dependency. Host call-sites unchanged. combo.ts shrinks ~60 LOC; leaf is 91 LOC (<800). Body byte-identical (verbatim), no cycle. This is the first slice toward extracting the shared attempt-loop/success/error handlers (Tasks 3-4) that de-duplicate handleComboChat and handleRoundRobinCombo. Adds a dedicated test (5) so the failover path can be mutated independently. Consumer tests stay green (combo-strategy-fallbacks 24, combo-499-abort 5, empty-content-failover 3, body-400-stop 1, priority-quota-exhaustion 2, rr-streaming-lock 1, rr-session-stickiness 2). Plan: _tasks/superpowers/plans/2026-07-03-blocoJ-combo-hotpath-decomposition.md * feat(cli-tools): add CodeWhale CLI tool (#5996) CodeWhale (https://github.com/Hmbown/CodeWhale) is the actively-maintained successor to DeepSeek TUI — same author, renamed project. Added as a dual entry alongside the existing "deepseek-tui" catalog entry (rather than a hard rename) so users who still run the old DeepSeek TUI binary keep a working dashboard card, while new users are steered to "codewhale". New /api/cli-tools/codewhale-settings route writes the primary ~/.codewhale/config.toml and keeps an existing legacy ~/.deepseek/config.toml in sync (read fallback + best-effort write sync), mirroring deepseek-tui-settings/route.ts. CLI_TOOLS and cliRuntime catalogs updated; catalog cardinality tests/constants bumped accordingly (18→19 visible code tools, 28→29 total). Inspired-by: https://github.com/decolua/9router/pull/1761 Co-authored-by: aristorinjuang <aristorinjuang@gmail.com> * feat(i18n): auto-detect browser language on first visit (#5979) * feat(i18n): auto-detect browser language on first visit Adds a pure detectBrowserLocale() matcher (exact match, zh-HK/zh-MO folded to zh-TW, language-prefix match, else null) plus a client-only LocaleAutoDetect component mounted once in the root layout. On first visit (no locale cookie set), it reads navigator.languages, computes a match against the supported locales, and persists it via the same cookie/localStorage writer LanguageSelector already used for manual selection (now extracted to shared/lib/persistLocale.ts) before refreshing the router. Co-authored-by: anmingwei <anmingwei@dobest.com> Inspired-by: https://github.com/decolua/9router/pull/1324 * chore(changelog): restore release entries + add browser-lang-detect bullet --------- Co-authored-by: anmingwei <anmingwei@dobest.com> * fix(dashboard): render Update-now API errors as text, not the raw envelope object (#5991) (#6028) Integrated into release/v3.8.44 — fix(dashboard) render Update-now API errors as text, not the raw envelope object (#5991). Merged with --admin: the fix is a one-line frontend change funneling the error body through the already-tested extractApiErrorMessage() helper, guarded by tests/unit/ui/home-update-error-render-5991.test.ts (3/3 pass, 3/3 fail on pre-fix source). The release branch is under a heavy parallel-merge storm (tip advanced ~6× mid-CI), so the branch is synced to the latest tip and landed atomically to avoid perpetual CONFLICTING; unit-shard reds seen earlier were pre-existing base-reds/flakes unrelated to this source-scan-only change. * feat(api): expose provider plugin manifest (#6001) * feat(api): expose provider plugin manifest * test(translator): split responses chat request coverage * test(mutation): register provider coverage tests * feat(api): expose provider plugin manifest * fix(ci): fail closed for prerelease latest promotion * chore(ci): reconcile provider manifest complexity gate * feat(api): expose provider plugin manifest * test(translator): split responses chat request coverage * test(mutation): register provider coverage tests * fix(ci): fail closed for prerelease latest promotion * chore: rebase onto release tip; drop out-of-scope translator test split + promote-script tweak Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * docs(changelog): add provider plugin manifest entry Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * chore(stryker): register account-fallback-retry-after-json test (base-red) Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: kooshapari <kooshapari@users.noreply.github.com> Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@outlook.com> Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(providers): add CN sign-up geo-restriction notices for SenseNova & StepFun (#5462) * feat(sidecar): advertise provider manifest url (#6007) * feat(sidecar): advertise provider manifest url via X-OmniRoute-Provider-Manifest-Url header Re-cut onto release tip: manifest-url feature only (dropped stale-base noise). Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * docs(changelog): add sidecar manifest-url entry Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * chore(complexity): rebaseline 2009->2015 (inherited release-tip drift; feature adds 0) Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: KooshaPari <KooshaPari@users.noreply.github.com> Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(autoCombo): latency/speed-optimized routing mode + omniroute_pick_fastest_model MCP tool (#6011) * feat(autoCombo): latency/speed-optimized routing mode + omniroute_pick_fastest_model MCP tool * test(translator): split responses chat request coverage * refactor(mcp): extract fastest-model tool modules * fix(i18n): cover provider icon and cors labels * test(mutation): register latency coverage files * test(ci): collect executor unit tests * refactor(ci): reduce latency path complexity * fix(mcp): include models catalog module * feat(autoCombo): latency/speed-optimized routing + omniroute_pick_fastest_model MCP tool Re-cut onto release tip: keep speed-routing + MCP tool + supporting catalog split; drop out-of-scope translator split, en.json/ci.yml/package.json orphans, and unrelated proxyFetch/responsesStreamHelpers/tokenLimitCounter refactors. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: kooshapari <kooshapari@users.noreply.github.com> Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@outlook.com> Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * docs(changelog): restore #5181/#5199/#5462 feature bullets eaten by merge * feat(usage): on-demand period-scoped usage-data reset (re-cut onto release tip) (#5831) * chore(quality): rebaseline eslintWarnings 4199->4256 + cognitiveComplexity 860->861 (v3.8.44 cycle drift) Inherited v3.8.44 cycle drift measured on release tip72ee80649by the release-green pre-flight during the /review-prs fix-batch round. The Quality Ratchet does NOT run on PR->release fast-gates, so eslint warnings + cognitive complexity accrue unmeasured across the cycle. Cyclomatic complexity is already green (2012 < baseline 2015) and needs no bump. Each value carries a dated justification note; no production code touched. * feat(claude-code): opt-in auto-permission classifier compat mode (re-cut onto release tip) (#5810) * feat(providers): client-identity header profiles for compatible nodes (re-cut) + forbid cookie in custom headers (#5812) * docs(openapi): document 9 newly-added routes to restore coverage ratchet (v3.8.44) Documents the routes added this cycle that dropped openapiCoverage 36.9%->36.2% below the ratchet baseline: 2 public v1 endpoints (/v1/ocr Mistral-OCR-compatible, /v1/audio/translations Whisper-compatible) with full request/response specs, plus 7 dashboard/CLI-local routes marked x-internal:true (suggested-models, provider-plugin- manifest, keys/{id}/devices, settings/purge-usage-history, oauth/codex/import-token, cli-tools crush-settings + codewhale-settings). Coverage 36.2%->37.8% (207/547), above baseline 36.9. check:openapi-routes/security-tiers/fabricated-docs all pass. * refactor(sse): decompose handleComboChat auto-strategy region (Block J Task 2 — parseAutoConfig + resolveAutoStrategyOrder) (#6049) * refactor(sse): extract pure parseAutoConfig leaf from handleComboChat Block J Task 2 (safe slice): the auto-strategy config-resolution block in handleComboChat is a pure function of (combo, eligibleTargets) with no side effects, no early returns and no mutation. Extract it verbatim into open-sse/services/combo/autoConfig.ts::parseAutoConfig so the god-function shrinks and the derivation is independently unit-testable. Behavior is byte-identical (verbatim-audited); combo.ts 3309->3280 LOC. Adds tests/unit/combo-auto-config-split.test.ts (5 cases) pinning the strategy-precedence, candidate-pool, weights and fallback derivations. * refactor(sse): extract resolveAutoStrategyOrder leaf from handleComboChat Block J Task 2 (coupled slice): the ~215-line `if (strategy === "auto")` branch of handleComboChat is extracted into open-sse/services/combo/resolveAutoStrategy.ts::resolveAutoStrategyOrder. The branch is a control-flow region (mutates orderedTargets + autoUsedExplicitRouter, early-returns 429, side-effect _registerExecutionCandidates), so it is not a pure byte-identical move: the two `return unavailableResponse(...)` exits become `{ earlyResponse }` and the mutated locals are returned instead of closed over. Every other logic line is verbatim (semantic diff = only those wrappers + the deeper getLKGP import path). `buildAutoCandidates` lives in combo.ts, so it is injected via deps to keep the leaf acyclic (same DI pattern as buildTargetTimeoutRunner) — which also makes the branch independently testable. combo.ts 3280->3065 LOC. typecheck:core + check:cycles clean; dead host imports removed. 60/60 consumer tests (router-strategies / auto-combo-engine / combo-strategy-fallbacks / scoring-clamp / candidate-expansion / hidden-models) cover the routable path end-to-end; new tests/unit/combo-resolve-auto-strategy-split.test.ts pins the DI contract + the early-429 and default-ordering exits. * test(sse): point quota-bypass source scan at resolveAutoStrategy leaf The 'auto combo disables hard provider quota cutoffs when relay requests bypass' source scan asserted combo.ts contains the bypass logic (relayOptions?.bypassProviderQuotaPolicy === true + quotaPreflight enabled:false). That block was extracted verbatim into combo/resolveAutoStrategy.ts (Block J Task 2), so the scan now reads the leaf. Behavior unchanged. * fix(ci): release-green base-reds — #5695 test regex + file-size rebaseline (#6093) - tests/unit/ui/quick-start-api-keys-link-5695.test.ts: tolerate Prettier splitting <Link href=...> across lines (\s+) so the step1Desc regex matches the multi-line /dashboard/api-manager Link instead of skipping to step2's single-line /dashboard/providers Link. Code is correct; the test was brittle. - config/quality/file-size-baseline.json: rebaseline 5 files that grew via already-merged PRs on the release tip (ApiManagerPageClient 3017->3058, OAuthModal 969->989, cliRuntime 1090->1100, webProvidersA 805->809, deepseek-web.test 1081->1092). Dated note added; shrink tracked in #3501. * fix(translator): wrap Kiro system prompt in <system-reminder> (port from 9router#2306) (#6053) Kiro/CodeWhisperer has no system role, so system messages were normalized to a user turn with no wrapper — the full Claude Code system prompt then appeared as raw user text, polluting the model context. Wrap system-origin content in <system-reminder> tags before merging it into the Kiro user message. Real user turns are unaffected. Existing history-merge tests aligned to the wrapped value. Reported-by: VitzS7 (https://github.com/decolua/9router/issues/2306) * fix(translator): strip multipleOf from antigravity/gemini tool schemas (port from 9router#2309) (#6052) `multipleOf` is not part of the Gemini/antigravity OpenAPI 3.0 schema subset, so leaving it in function_declaration parameters triggered a hard upstream 400 ("Unknown name multipleOf"). Add it to GEMINI_UNSUPPORTED_SCHEMA_KEYS so it is stripped at every schema level; minimum/maximum stay (Gemini accepts them). Reported-by: abil0321 (https://github.com/decolua/9router/issues/2309) * fix(kimi-web, qwen-web): align model catalog with live /models + map scenario per model (#5915) * fix(kimi-web): align catalog with live models Update the kimi-web catalog and request scenario selection to match www.kimi.com's live GetAvailableModels response. * fix(qwen-web): stop aliasing qwen3-coder-plus Keep qwen3-coder-plus as its own model because it is present in the live Qwen web models catalog. * feat(minimax): extract M3 <think> to reasoning_content on OpenAI-format tiers (#6050) MiniMax M3 is registered with format:"openai" on 8 provider tiers (trae, huggingchat, bazaarlink, ollama-cloud, opencode, cline, opencode-zen, codebuddy-cn), where its raw <think>...</think> tags leaked directly into `content` instead of surfacing as a separate `reasoning_content` field. OmniRoute already has the extraction primitive (extractThinkingFromContent in responseSanitizer/reasoning.ts); it was just gated to deepseek-r1/r1-distill/qwq. Extend the allowlist (isTextualReasoningTagNativeRoute) with a minimax-m3-only pattern, excluding the two direct minimax/minimax-cn tiers, which stay on Anthropic's Messages format (targetFormat: "claude") and already surface reasoning natively. Inspired-by: https://github.com/decolua/9router/pull/2231 Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com> Co-authored-by: zmf963 <19422469+zmf963@users.noreply.github.com> * fix: unwrap Cline response envelope (#6046) Co-authored-by: KooshaPari <KooshaPari@users.noreply.github.com> * refactor(sse): extract applyStrategyOrdering leaf from handleComboChat (Block J Task 3) (#6063) * refactor(sse): extract applyStrategyOrdering leaf from handleComboChat Block J Task 3: the ~177-line else-if chain covering every non-auto combo strategy (lkgp / strict-random / random / fill-first / p2c / least-used / cost-optimized / reset-aware / reset-window / context-optimized / headroom / quota-share) is extracted into open-sse/services/combo/applyStrategyOrdering.ts::applyStrategyOrdering. Each branch only reorders orderedTargets (no early returns, no other mutable state), so the extraction is a clean verbatim move returning the reordered list; the host replaces the chain with `else { orderedTargets = await applyStrategyOrdering(strategy, orderedTargets, deps); }`. Semantic diff vs the original chain = only the leading `if` (was `} else if`), the trailing return and the deeper getLKGP import path — no logic line changed. None of the 13 strategy helpers live in combo.ts, so no DI/cycle (unlike the auto branch). combo.ts 3065->2883 LOC (3309->2883 across Task 2+3). typecheck:core + check:cycles clean; 9 dead host imports removed (targetSorters block emptied). 47/47 consumer tests (router-strategies / combo-strategy-fallbacks / rr-session-stickiness / tag-routing) cover the DB-backed branches end-to-end; new tests/unit/combo-apply-strategy-ordering-split.test.ts pins random / fill-first / unknown exits. * test(sse): point #2359 modelStr-guard scans at applyStrategyOrdering leaf The LKGP fallback + non-auto strategy ordering (the two target.modelStr string- method call sites) were extracted verbatim from combo.ts into the applyStrategyOrdering leaf (Block J Task 3). The #2359 source scans now read the leaf that owns those usages; the guard and the no-unguarded-usage assertions are unchanged in intent. * chore(ci): scan combo strategy leaves in check:known-symbols Block J decomposed the combo dispatch: the `strategy === "..."` branches for the 12 non-auto strategies moved to combo/applyStrategyOrdering.ts and the auto branch to combo/resolveAutoStrategy.ts. The known-symbols gate previously scanned only combo.ts, so it would report those strategies as canonicalNotHandled. Scan all three dispatch files. Verified: 18/18 canonical strategies via dispatch. * fix(combo): fallback to sibling model on 500 for per-model-quota providers (#5976) * fix(combo): fallback to sibling model on 500 for per-model-quota providers Two issues prevented combo fallback when gemini/gemma-4-31b-it returned 500: 1. targetExhaustion: connection-level exhaustion marked the shared gemini connection as exhausted, skipping the sibling model (gemma-4-26b-a4b-it). Skip markConnectionLevelExhaustion for per-model-quota providers (gemini, github, passthrough, compatible) since a model-level 500 does not mean the connection is bad. 2. combo retry loop: the auth layer records a model lockout on 500, but the retry loop did not check isModelLocked before retrying — it retried the same locked model instead of falling back. Add isModelLocked guard before the transient-retry decision. * fix tests timeout * fix: clear quota fallback CI gates * quality-gate: extract test SSE stream helpers * drop scope creep * fix(combo): retry sibling models only on 500 errors * fix(combo): reconcile onto release/v3.8.44 — keep targetExhaustion 500 fix, drop slow integration test Reconciled by maintainer onto the current release tip: - kept the core fix (targetExhaustion.ts model-500 guard for per-model-quota providers + the isModelLocked retry early-return in combo.ts) and its unit test - dropped tests/integration/combo-concurrent-failure-recovery.test.ts + _sseTestHelpers.ts: they use Math.random()-based delays and 30s timeouts, run >3min and are flake-prone in the test:integration CI job; the unit test (tests/unit/combo/combo-target-exhaustion.test.ts, 21 cases) fully covers the fix - CHANGELOG entry added Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> --------- Co-authored-by: Koosha Pari <kooshapari@gmail.com> Co-authored-by: Diego Rodrigues de Sa e Souza <diegosouza.pw@outlook.com> Co-authored-by: hartmark <hartmark@users.noreply.github.com> Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(xai): surface Grok usage on quota dashboard via local usageHistory aggregation (#5806) xAI has no public per-account quota API (the billing console requires a session cookie, not an API key). Add getXaiUsage(connectionId), mirroring the existing Xiaomi MiMo self-track pattern: sum tokens routed to the connection from usage_history via getMonthlyProviderTokensForConnection and surface them as a cumulative, uncapped quota (unlimited: true, remaining: 100 — xAI has no fixed monthly cap). Register 'xai' in USAGE_FETCHER_PROVIDERS and wire a switch case in getUsageForProvider. Inspired-by: https://github.com/decolua/9router/pull/2150 Co-authored-by: ron <devestacion@gmail.com> * feat(services): add Mux managed embedded service (#6034) Adds Mux (coder/mux — local agent-orchestration daemon) as a fourth-tier embedded service built on the existing ServiceSupervisor framework, the same shape as 9Router and CLIProxyAPI: - Installer (src/lib/services/installers/mux.ts): npm install/update via runNpm (array args + env-based prefix, no shell interpolation), modeled on ninerouter.ts. Mux ships an npm package (`mux`) with a documented headless `mux server --host <host> --port <port>` mode, so no git-clone+build path was needed. - Registered in bootstrap.ts (SERVICES[] + buildSpawnArgsFactory). - DB seed migration 113 (version_manager row, not_installed/auto_start=0). - 7 API endpoints under /api/services/mux/ (install/start/stop/restart/ update/status/auto-start) plus the shared [name]/logs SSE endpoint, mirroring the cliproxy route shape and delegating errors through createErrorResponse(). - Dashboard tab (MuxServiceTab) reusing ServiceStatusCard, ServiceLifecycleButtons, AutoStartToggle, ServiceLogsPanel. - Docs: EMBEDDED-SERVICES.md (service table, architecture diagram, API reference, key-injection section), openapi.yaml, ENVIRONMENT.md, .env.example. Security: - Every /api/services/mux/* route is covered by the existing LOCAL_ONLY_API_PREFIXES "/api/services/" prefix (Hard Rule #17); added an explicit isLocalOnlyPath regression test for all 8 routes. - Mux binds to 127.0.0.1 explicitly (never 0.0.0.0) as defense-in-depth, since it orchestrates AI agents that can execute host commands. - The bearer token is generated the same way as 9Router's key (getOrCreateApiKey) and injected via MUX_SERVER_AUTH_TOKEN (mux's documented env form) rather than a CLI flag, so it never appears in `ps`/process listings. - No shell interpolation anywhere in the installer (Hard Rule #13): all npm/spawn args are static arrays; the install prefix and auth token travel via the env option. Inspired-by: https://github.com/decolua/9router/pull/1802 Co-authored-by: Ansh7473 <Ansh7473@users.noreply.github.com> * feat(services): promote Bifrost to embedded/supervised service (#5670) (#5817) Promotes Bifrost (@maximhq/bifrost — Go AI-gateway) from an env-only relay sidecar to a first-class embedded/supervised service, matching the existing cliproxy/9router model. Implements item #2 of #5670; the broader RouterBackend contract (items #1, #3-#5) stays out of scope. - Installer (npm-style, ninerouter model): install/update/getInstalledVersion/ getLatestVersion (1h cache)/resolveSpawnArgs (Go single-dash flags, pinned BIFROST_TRANSPORT_VERSION), needsApiKey=false - Bootstrap SERVICES entry (healthPath /v1/models) + spawn-args factory branch - Migration 113 seeds the version_manager row (not_installed, port 8080, auto_update=1, provider_expose=1) - 7 lifecycle API routes under /api/services/bifrost/ (verbatim from cliproxy, errors sanitized) — loopback-only via existing LOCAL_ONLY_API_PREFIXES - Shared [name]/logs branch for bifrost - Dashboard tab + registration in the services page shell - Relay auto-wiring: getBifrostRoutingConfig defaults BIFROST_BASE_URL to the supervised port when the instance is running; explicit env still wins; the env-only relay path (/v1/relay/.../bifrost) stays unchanged (compat layer) - Docs (EMBEDDED-SERVICES, openapi) + unit tests (installer/route-guard/routing, 19 tests) + RUN_SERVICES_INT-gated integration lifecycle Note: the actual Go-binary install/start/health path requires a documented VPS live-test before merge (Hard Rule #18 / spec section 7); the gated integration harness is the vehicle for that run. * fix(ci): document BIFROST_PORT to clear env-doc-sync base-red The Bifrost embedded-service merge referenced process.env.BIFROST_PORT (src/lib/services/bootstrap.ts, default 8080) without adding it to .env.example / ENVIRONMENT.md, so check:env-doc-sync failed on the release tip and reddened Fast Quality Gates for every open PR->release. Docs-only. * fix(providers): emulate OpenAI tool_calls in GitLab Duo executor (#6051) (#6111) Co-authored-by: felssxs <felssxs@users.noreply.github.com> * fix(providers): strip orphan tool_result on Antigravity MITM path (#6026) (#6115) * fix(registry): update grok-cli model context lengths (#5913) grok-build 128k→256k, grok-composer-2.5-fast 128k→200k to match actual Grok CLI /context capacities so context-aware routing stops filtering these models out. Registry-only. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(proxy): batch delete, auto-test, health scheduler + transitive alias fix (#5918) Proxy-registry batch management (batch-delete, auto-test, background health scheduler) + fix resolveProviderAlias to follow the alias chain transitively (oc -> opencode -> opencode-zen). Probe target now operator-configurable via PROXY_HEALTH_TEST_URL. Scope-creep files from the original branch dropped. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * feat(minimax): extract M3 reasoning_content on OpenAI-format tiers (#6073) MiniMax M3 leaks raw <think>...</think> into content on 8 OpenAI-format provider tiers; extract it into reasoning_content, leaving the direct minimax/minimax-cn (Claude-format) tiers untouched. Replacement for the stale #5804 branch. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(ci): harden provider translate-path golden across CI runners (#6076) Normalize OS/arch-derived request headers (X-Stainless-Os/Arch, (OS;arch) UAs, and Antigravity's os.platform()-derived platform substring) in the golden so the test is runner-independent. Fixes the Mac-literal Antigravity UA that would have failed on Linux CI. Supersedes stale #6002. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * test(embeddings): pin seeded connection to direct egress in route-edge-coverage (#5975 collateral) #5975 made the embeddings service honor the connection-level proxy. The pre-existing route-edge-coverage embeddings edge-case tests seed an openai connection while the settings-proxy suite has left a provider-level proxy (provider.local:8080) in the shared DATA_DIR that resetStorage() does not clear — inert before #5975, but now the leaked proxy fast-fails the embedding upstream with PROXY_UNREACHABLE. These tests do not exercise proxying, so seedOpenAIConnection now pins the connection to proxyEnabled:false, making resolveProxyForConnection return a direct egress regardless of leaked global proxyConfig. No assertions weakened; 16/16 in the file pass. Regression surfaced by the concurrency=1 full-suite run; passes on #5975's parent, red after it. * fix(config): externalize ws for copilot-m365-web executor (#6130, closes #6062) Re-lands the #6098 ws-externalization fix onto release/v3.8.44 (it had merged to main by mistake and was reverted). Externalize ws/bufferutil/utf-8-validate so the copilot-m365-web WebSocket masking path works at runtime. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(providers): update Perplexity Web models (#6106) Refresh the Perplexity Web model catalog + mode/model_preference mappings to the current live set. Regression guard: perplexity-web.test.ts. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(providers): update Gemini Web cookies and models (#6095) Refresh Gemini Web cookie handling + model catalog. Regression guard: gemini-web.test.ts. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(models): normalize GLM-5.2 provider context (#6091) Hosted GLM-5.2 provider aliases now respect their declared context caps instead of inheriting the native 1M; native/bare + verified OpenCode/ZenMux routes stay at 1M. Regression guards added. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(combo): prefer known context capacity over unknown (#6088) When a combo filters a target for exceeding a known context limit, prefer remaining known-compatible targets over unknown-metadata ones. Regression guard: combo-context-window-filter.test.ts. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix: keep Claude tool results adjacent (#6035) Reattach OpenAI tool_result adjacent to tool_use before Claude send (#6026). Integrated into release/v3.8.44. * fix(security): persist IP filter config + enforce it in the authz pipeline (#6131) (#6132) Integrated into release/v3.8.44 — IP filter persistence + authz-pipeline enforcement (closes #6131). HARD-neutro: validate-release-green on the merge shows the same 3 pre-existing base-reds as the release baseline (test-masking cycle-wide, unit red-herring, integration batch-E2E env); #6131's own tests + ip-filter/pipeline suites all green. * fix(codex): use access_token.exp instead of id_token.exp for import expiresAt (#6075) (#6084) Prefer access_token.exp over id_token.exp for Codex auth import (#6075). Integrated into release/v3.8.44. * fix(compression): send patch-only to PUT /api/settings/compression in CompressionHub (#6039) (#6077) Send patch-only to PUT /api/settings/compression in CompressionHub (#6039). Integrated into release/v3.8.44. * fix: reqId ReferenceError in safety-net redirect, dead code, filename typo (#6097) Fix reqId ReferenceError in safety-net combo redirect + dead-code + DESING→DESIGN rename. Integrated into release/v3.8.44. * fix(combo): expand fingerprint-based providers into per-fingerprint combo targets (#6082) Expand fingerprint-based providers into per-fingerprint combo targets. Integrated into release/v3.8.44. * fix(auth): persist quota preflight account lockouts (#6090) Persist quota preflight account lockouts until reset window. Integrated into release/v3.8.44. * fix(combos): expand OpenCode/MiMo fingerprint accounts in combo builder (#6087) (#6092) Expand OpenCode/MiMo fingerprint accounts in combo builder (#6087). Integrated into release/v3.8.44. * chore(quality): rebaseline v3.8.44 release-green drift (eslint/cognitive/cyclomatic/file-size) Measured on release tip32e4c906eduring the #6131/#5975 release-green pass: eslintWarnings 4256->4270 (+14), cognitiveComplexity 861->867 (+6), cyclomatic count 2015->2026 (+11), and testFrozen caps for models-catalog-route (1507->1600), perplexity-web (959->999), route-edge-coverage (1234->1241, my #5975 comment +7). Inherited cycle drift (the Quality Ratchet does not run on PR->release fast-gates); compression 'bun not found' is a local-env false and codeql is within baseline, so neither is rebaselined. No production code touched. * fix(accountFallback): persist per-account 429 cascade + classify 'Monthly usage limit. Resets in N days.' (#6061) Persist per-account 429 cascade + classify 'Monthly usage limit. Resets in N days'. Integrated into release/v3.8.44. * feat(build): backend-only fast build (skip the dashboard frontend) (#6119) Backend-only fast build (skip dashboard frontend). Integrated into release/v3.8.44. * fix(provider-limits): clear transient rate-limit state when quota recovers (#6128) Clear transient rate-limit state when quota recovers. Integrated into release/v3.8.44. * docs: Normalize mixed-language documentation content (#6105) Normalize mixed-language documentation to English. Integrated into release/v3.8.44. * chore docs * i18n(zh-CN): translate CHANGELOG entries and section headings (#6043) Adopt zh-CN as a translated locale: translate CHANGELOG + supporting docs. Integrated into release/v3.8.44. * chore(quality): rebaseline residual eslint + file-size drift (v3.8.44) Residual drift on release tip716041223(moving target): eslintWarnings 4270->4279 (+9 as the branch advanced past the prior rebaseline) and testFrozen/frozen file-size caps for providerLimits.ts (955->982), accountFallback.ts (1790->1864) and sse-auth.test.ts (1553->1600). All inherited from parallel-session merges (e.g. #6128); the two production god-files ideally warrant decomposition rather than a bump (tracked as debt). No production code touched. * fix(repo): remove Windows case-conflicting DESIGN duplicate (#6140) Remove stale root DESIGN.md (Windows case-conflict with design.md). Integrated into release/v3.8.44. * fix(provider-limits): close TOCTOU race in quota recovery clear (I2) (#6139) Close TOCTOU race in quota recovery clear via CAS primitive (I2 from #6128). Integrated into release/v3.8.44. * fix(glm): suppress </think> close marker leak in GLM Anthropic transport (#6133) Suppress </think> close-marker leak in GLM Anthropic transport. Integrated into release/v3.8.44. * fix(cli): give setup-claude a fallback profile generator like setup-codex (#6138) Give setup-claude a fallback profile generator like setup-codex. Integrated into release/v3.8.44. * fix(onboarding): route provider-details link by node id, not provider slug (#6145) (#6145) Route onboarding provider-details link by node id (#6145). Integrated into release/v3.8.44. * fix(translator): strip Responses-only truncation field before Chat Completions forwarding (#6109) Strip Responses-only truncation field before Chat Completions forwarding (#2311). Integrated into release/v3.8.44. * fix(mitm): guard against concurrent MITM server starts (#6107) Guard against concurrent MITM server starts (#2316). Integrated into release/v3.8.44. * feat(models): add claude-sonnet-5 to Antigravity catalog (#6103) Add claude-sonnet-5 to Antigravity catalog. Integrated into release/v3.8.44. * fix(providers): strip thinking param for minimax-m2.7 on NVIDIA NIM (#6102) Strip unsupported thinking param for minimax-m2.7 on NVIDIA NIM. Integrated into release/v3.8.44. * feat(providers): add Kenari OpenAI-compatible gateway (#6104) Add Kenari OpenAI-compatible gateway (BYOK). Integrated into release/v3.8.44. * feat(sse): per-request Auto-Combo controls (X-OmniRoute-Mode / X-OmniRoute-Budget) — closes #6023 #6024 #6025 (#6057) Per-request Auto-Combo controls (X-OmniRoute-Mode / X-OmniRoute-Budget). Integrated into release/v3.8.44. * feat(resilience): throttle concurrent upstream quota fetches — closes #6009 (#6058) Throttle concurrent upstream quota fetches (#6009). Integrated into release/v3.8.44. * fix(oauth): graceful 400 for keychain-import-only providers (zed) (#6041) (#6054) Graceful 400 for keychain-import-only providers on OAuth route (zed, #6041). Integrated into release/v3.8.44. * fix(dashboard): resolve broken Card import breaking next build (base-red from #6061) (#6155) * fix(dashboard): resolve broken Card import breaking next build (base-red from #6061) CoolingConnectionsPanel imported `Card` from `@/components/ui/card`, a path that does not exist in this repo (there is no shadcn-style `src/components/ui/`). The PR->release fast-gates do not run `next build`, so the broken import slipped in and `next build` failed with: Module not found: Can't resolve '@/components/ui/card' Fix: the <Card> here was only a styled container, so replace it with a <div> carrying the equivalent Tailwind classes (border/bg/padding + rounded-card shadow-sm). Also normalize the file from CRLF to LF (it shipped with CRLF). Adds a vitest/jsdom regression test (tests/unit/ui/CoolingConnectionsPanel.test.tsx) that fails-without-fix (Vite: 'Failed to resolve import @/components/ui/card') and passes with it, plus renders/empty-state coverage. Rule #18. * fix(dashboard): stop client CoolingConnectionsPanel dragging server DB barrel into browser bundle Second base-red from #6061, surfaced once the broken Card import was fixed: ./node_modules/ioredis/built/connectors/StandaloneConnector.js Module not found: Can't resolve 'net' Import trace: ioredis <- rateLimiter.ts <- apiKeys.ts <- @/lib/localDb <- CoolingConnectionsPanel.tsx (a "use client" component) The client panel imported `formatResetCountdown` from `@/lib/localDb` — the server-side DB re-export barrel — which transitively pulls better-sqlite3/ioredis (node:net) into the browser bundle. That violates the CLAUDE.md rule 'never barrel-import from localDb'. `formatResetCountdown` is a pure date-formatting function, so move its implementation to the client-safe `@/shared/utils/formatting` (alongside formatTime/formatDuration) and re-export it from db/providers/rateLimit.ts for the existing server callers + barrel. The panel now imports it directly from the shared util — no server code in the client bundle. Tests (Rule #18): - tests/unit/format-reset-countdown.test.ts (node:test, blocking test:unit) — pure-function coverage: null/past/invalid, s, m+s, h+m, ISO string. - tests/unit/ui/CoolingConnectionsPanel.test.tsx mock updated to the new module. * fix(release): v3.8.44 Phase-0 pre-flight — base-red sweep + ratchet absorption - fix(models): stop resolveProviderAlias at registered provider ids so oc/ reaches the no-auth opencode provider again (#2901 contract, regressed by #5918's transitive chain; transitivity kept across alias-only hops) - fix(auggie): handle async EPIPE 'error' events on child stdin so a fast-exiting CLI surfaces a sanitized error instead of crashing (both spawn sites); deflakes auggie-executor tests - test: align provider family count 166->167 (Kenari #6104), regenerate translate-path golden on Linux (+kenari), opencode quota scope provider->connection (#6061) - quality(test-masking): add _deletedWithReplacement allowlist support to check-test-masking.mjs (deletion exempt ONLY when the declared replacement test exists in HEAD; 5 new gate unit tests) + reduction allowlist entries for the verified #5958/#6088/#5816 migrations + targetExhaustion-> combo-target-exhaustion replacement (#5976, 21 cases/52 asserts vs 13/37) - quality(file-size): absorb v3.8.44 cycle drift (oauth route 960, providerLimits 998, chat 1662, auth 2426) with justification; #6158 will restore the oauth-route freeze - changelog: bullets for the above + the #6155 cooling-panel build fix * chore(release): v3.8.44 — 2026-07-04 Release reconciliation + close (generate-release Phases 0a/1): - CHANGELOG [3.8.44]: 21 PR refs added to existing bullets, 62 new bullets (incl. restoration of ~10 bullets erased by the stale-branch merge in1f6ec5bc8), 3 Maintenance rollups, #6061/#6130 credit fixes, 🙌 Contributors table (35 external contributors) — coverage 144/153 cycle commits by #ref - 42 docs/i18n CHANGELOG mirrors synced (EN content; i18n workflow translates) - README: What's New refreshed for v3.8.44 highlights - build scope: exclude electron/node_modules + electron/dist-electron + .build from tsconfig (local build-output leak poisoned next build with 8GB OOM — same class as the 2026-06-25 incident; scope 14765→5207, gate green) - quality: cyclomatic baseline 2026→2028 (+2 inherited end-of-cycle drift; verified the release-captain code fixes add 0 new violations) * fix(release): v3.8.44 one-pass release-PR CI sweep - fix(dashboard): /dashboard/system/proxy 500'd on EVERY render — #5918 put useProxyBatchOperations(load) before the const load declaration (TDZ ReferenceError, digest 539380095). Hook block moved after load; SSR renderToString regression test added (the exact crash mode). - fix(server): TRACE/TRACK/CONNECT crashed Next's middleware adapter (undici cannot represent them) into a raw 500 on every route — the raw HTTP method guard now answers 405 + Allow up-front (dast-smoke Schemathesis finding on /api/keys/{id}/devices); guard test added. - fix(api): restore Zod validation on the provider-scoped chat route via a .passthrough() schema preserving #5907's relaxed semantics (t06 gate). - docs(openapi): /api/keys/{id}/devices 401 now refs the management error envelope (Schemathesis schema-conformance). - quality: rebaseline i18nUiCoverage 77.5->76.8 (+~1352 new en.json UI keys from the cycle await the async translation workflow; v3.8.39 precedent). - CodeQL: dismissed 2 incomplete-url-substring FPs on unit-test asserts (v3.8.35 precedent) with Hard Rule #14 justifications. - changelog: bullets for the above + 42 i18n mirrors re-synced * fix(release): round-2 CI findings — LocaleAutoDetect refresh gating + ratchet tighten - fix(i18n): LocaleAutoDetect (#5979) refreshed the router on EVERY cookie-less first visit, even when the detected locale matched the server-rendered <html lang> — re-navigating mid-interaction (flaky e2e 'execution context destroyed' + visible flash for new visitors). Refresh now only fires when the locale actually differs; regression test added. - quality: tighten openapiCoverage.pct 36.9->39.3 (require-tighten gate on the release PR; value measured by the CI Quality Ratchet on00c55afcb) - quality(file-size): shrink the ProxyRegistryManager TDZ note to fit the 1117-line freeze (prettier reflow added a line at commit time) - changelog bullet + 42 i18n mirrors re-synced * test(release): collect the #6082 fingerprint-expansion ghost test check:test-discovery (Lint job, layered behind the round-1 t06 fix) flagged tests/e2e/fingerprint-expansion.test.ts as a NEW orphan — it is a node:test server-boot test that no runner collected, so it had never run. Moved to tests/integration/ (the collector for this shape), fixed the helper import, and verified it actually passes (3/3 on first-ever run). CHANGELOG ref updated. --------- Co-authored-by: Chirag Singhal <76880977+chirag127@users.noreply.github.com> Co-authored-by: Hamsa_M <116961508+hamsa0x7@users.noreply.github.com> Co-authored-by: Chewji <126886556+Chewji9875@users.noreply.github.com> Co-authored-by: Vittor Guilherme Borges de Oliveira <vittoroliveira.dev@gmail.com> Co-authored-by: nickwizard <35692452+nickwizard@users.noreply.github.com> Co-authored-by: Ankit <177378174+anki1kr@users.noreply.github.com> Co-authored-by: Fadhil Yusuf <33994304+yusufrahadika@users.noreply.github.com> Co-authored-by: Giorgos Giakoumettis <giorgos@yiakoumettis.gr> Co-authored-by: KooshaPari <42529354+KooshaPari@users.noreply.github.com> Co-authored-by: KooshaPari <KooshaPari@users.noreply.github.com> Co-authored-by: AgentKiller45 <jamalzzj45@gmail.com> Co-authored-by: Nikolay Alafuzov <alafuzov_nn@rusklimat.ru> Co-authored-by: ricatix <d.enistraju155@gmail.com> Co-authored-by: Muhammad Mugni Hadi <mugni@rukita.co> Co-authored-by: Randi <55005611+rdself@users.noreply.github.com> Co-authored-by: backryun <bakryun0718@proton.me> Co-authored-by: Ngô Tấn Tài <tantai@newnol.io.vn> Co-authored-by: dopaemon <polarisdp@gmail.com> Co-authored-by: yicone <yicone@gmail.com> Co-authored-by: CườngNH <j2.cuong@gmail.com> Co-authored-by: DuyPrX <93126969+DuyPrX@users.noreply.github.com> Co-authored-by: ryanngit <74137224+ryanngit@users.noreply.github.com> Co-authored-by: eng2007 <aleksey.semenov@gmail.com> Co-authored-by: chamdanilukman <16629923+chamdanilukman@users.noreply.github.com> Co-authored-by: Umar Javed <114807145+tn5052@users.noreply.github.com> Co-authored-by: JiangZhuo <jiangzhuo@qiniu.com> Co-authored-by: Delynn Assistant <zhen@dkzhen.org> Co-authored-by: whale9820 <87256750+whale9820@users.noreply.github.com> Co-authored-by: whale <admin@dyntech.cc> Co-authored-by: Rigel Ramadhani Waloni <rigel8911@gmail.com> Co-authored-by: zocomputer <help@zocomputer.com> Co-authored-by: aristorinjuang <aristorinjuang@gmail.com> Co-authored-by: anmingwei <anmingwei@dobest.com> Co-authored-by: janeza2 <49841619+janeza2@users.noreply.github.com> Co-authored-by: zmf963 <19422469+zmf963@users.noreply.github.com> Co-authored-by: Markus Hartung <mail@hartmark.se> Co-authored-by: Koosha Pari <kooshapari@gmail.com> Co-authored-by: hartmark <hartmark@users.noreply.github.com> Co-authored-by: ron <devestacion@gmail.com> Co-authored-by: Ansh7473 <Ansh7473@users.noreply.github.com> Co-authored-by: felssxs <felssxs@users.noreply.github.com> Co-authored-by: Paijo <14921983+oyi77@users.noreply.github.com> Co-authored-by: Arthur Bodera <abodera@gmail.com> Co-authored-by: Semianchuk Vitalii <fix20152@gmail.com> Co-authored-by: PizzaV <103120356+pizzav-xyz@users.noreply.github.com> Co-authored-by: NOXX - Commiter <artur1992123@mail.ru> Co-authored-by: Milan Soni <123074437+Iammilansoni@users.noreply.github.com> Co-authored-by: Devin <studyzy@gmail.com> Co-authored-by: Raxxoor <manker_lol@hotmail.com> Co-authored-by: derhornspieler <15236687+derhornspieler@users.noreply.github.com>
1379 lines
77 KiB
Markdown
1379 lines
77 KiB
Markdown
---
|
||
title: "API Reference"
|
||
version: 3.8.40
|
||
lastUpdated: 2026-06-28
|
||
---
|
||
|
||
# API Reference
|
||
|
||
🌐 **Languages:** 🇺🇸 [English](./API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/in/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md)
|
||
|
||
Complete reference for all OmniRoute API endpoints.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
- [Chat Completions](#chat-completions)
|
||
- [Embeddings](#embeddings)
|
||
- [Image Generation](#image-generation)
|
||
- [List Models](#list-models)
|
||
- [Provider Plugin Manifest](#provider-plugin-manifest)
|
||
- [Compatibility Endpoints](#compatibility-endpoints)
|
||
- [Files API](#files-api)
|
||
- [Batches API](#batches-api)
|
||
- [Search API](#search-api)
|
||
- [WebSocket Streaming](#websocket-streaming)
|
||
- [Quotas & Issues Reporting](#quotas--issues-reporting)
|
||
- [Semantic Cache](#semantic-cache)
|
||
- [Dashboard & Management](#dashboard--management)
|
||
- [Combo Management](#combo-management)
|
||
- [Webhooks](#webhooks)
|
||
- [Registered Keys (Auto-Management)](#registered-keys-auto-management)
|
||
- [Agents Protocol](#agents-protocol)
|
||
- [Management Proxies](#management-proxies)
|
||
- [Resilience (extended)](#resilience-extended)
|
||
- [Skills](#skills)
|
||
- [Memory](#memory)
|
||
- [MCP Server](#mcp-server)
|
||
- [A2A Server](#a2a-server)
|
||
- [Cloud, Evals & Assess](#cloud-evals--assess)
|
||
- [Request Processing](#request-processing)
|
||
- [Authentication](#authentication)
|
||
|
||
---
|
||
|
||
## Chat Completions
|
||
|
||
```bash
|
||
POST /v1/chat/completions
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"model": "cc/claude-opus-4-6",
|
||
"messages": [
|
||
{"role": "user", "content": "Write a function to..."}
|
||
],
|
||
"stream": true
|
||
}
|
||
```
|
||
|
||
### Custom Headers
|
||
|
||
| Header | Direction | Description |
|
||
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||
| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache |
|
||
| `x-omniroute-no-memory` | Request | Set to `true` to skip memory + skills injection for this request (mirrors no-cache; avoids the per-call token/cost overhead) |
|
||
| `X-OmniRoute-Progress` | Request | Set to `true` for progress events |
|
||
| `X-Session-Id` | Request | Sticky session key for external session affinity |
|
||
| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) |
|
||
| `Idempotency-Key` | Request | Dedup key (5s window) |
|
||
| `X-Request-Id` | Request | Alternative dedup key |
|
||
| `X-OmniRoute-Cache` | Response | `HIT` or `MISS` (non-streaming) |
|
||
| `X-OmniRoute-Idempotent` | Response | `true` if deduplicated |
|
||
| `X-OmniRoute-Progress` | Response | `enabled` if progress tracking on |
|
||
| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute |
|
||
| `X-OmniRoute-Request-Id` | Response | Request correlation id (when known) |
|
||
| `X-OmniRoute-Version` | Response | OmniRoute build version (always present) |
|
||
| `X-OmniRoute-Cost-Saved` | Response | USD the cache avoided on a HIT (cache hits only) |
|
||
|
||
> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`.
|
||
|
||
> **Cost telemetry headers:** non-streaming success responses also carry the `X-OmniRoute-*` cost-telemetry set — `X-OmniRoute-Response-Cost` (USD, fixed 10 decimals; `0.0000000000` for free/unpriced), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, and `X-OmniRoute-Fallback-Attempts` (only when > 0), plus `X-OmniRoute-Request-Id` and `X-OmniRoute-Version`. These are emitted by chat completions, `/v1/responses`, `/v1/messages`, **and the media endpoints** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, and `/v1/moderations` (always cost `0`). Media cost is computed per modality (per-image, per-second, per-character, per search-unit) when pricing is available, otherwise `0` (fail-open).
|
||
|
||
> **Cache-hit cost semantics:** on a semantic-cache HIT (`X-OmniRoute-Cache-Hit: true`) no upstream call is made, so `X-OmniRoute-Response-Cost` is `0.0000000000` (the **incremental** cost of serving the hit). The original/would-have-been cost is reported separately in `X-OmniRoute-Cost-Saved`. Billing consumers should sum `X-OmniRoute-Response-Cost` (hits cost nothing); cache analytics can aggregate `X-OmniRoute-Cost-Saved`.
|
||
|
||
### `x-omniroute-compression`
|
||
|
||
Per-request override of the compression plan. Highest precedence — beats the routing-combo
|
||
override, the active profile, auto-trigger, and the panel Default. Values:
|
||
|
||
| Value | Effect |
|
||
| ------------- | -------------------------------------------------------------------- |
|
||
| `off` | No compression for this request. |
|
||
| `default` | The panel-derived Default profile (ignores the active profile). |
|
||
| `engine:<id>` | A single engine when enabled, e.g. `engine:rtk`. |
|
||
| `<combo>` | A named combo, matched by name (case-insensitive) first, then by id. |
|
||
|
||
Notes:
|
||
|
||
- Unknown values are ignored (the request is never rejected); resolution falls through to the normal operator precedence.
|
||
- If multiple combos share a name, pass the combo **id** for a deterministic match.
|
||
- A combo whose name is `off` or `default` cannot be selected by name (those keywords are interpreted first); reference such a combo by its id.
|
||
- The master compression switch is a hard gate: when compression is disabled globally, this header cannot enable it.
|
||
|
||
The applied plan is echoed back in the response header:
|
||
|
||
```
|
||
X-OmniRoute-Compression: <mode>; source=<source>
|
||
```
|
||
|
||
where `<source>` is one of `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, or `off`.
|
||
|
||
---
|
||
|
||
## Embeddings
|
||
|
||
```bash
|
||
POST /v1/embeddings
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"model": "nebius/Qwen/Qwen3-Embedding-8B",
|
||
"input": "The food was delicious"
|
||
}
|
||
```
|
||
|
||
Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, **GitHub Models**.
|
||
|
||
```bash
|
||
# List all embedding models
|
||
GET /v1/embeddings
|
||
```
|
||
|
||
---
|
||
|
||
## Image Generation
|
||
|
||
```bash
|
||
POST /v1/images/generations
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"model": "openai/gpt-image-2",
|
||
"prompt": "A beautiful sunset over mountains",
|
||
"size": "1024x1024"
|
||
}
|
||
```
|
||
|
||
Available providers: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
|
||
|
||
```bash
|
||
# List all image models
|
||
GET /v1/images/generations
|
||
```
|
||
|
||
---
|
||
|
||
## List Models
|
||
|
||
```bash
|
||
GET /v1/models
|
||
Authorization: Bearer your-api-key
|
||
|
||
→ Returns all chat, embedding, and image models + combos in OpenAI format
|
||
```
|
||
|
||
### No-thinking model variants
|
||
|
||
For thinking-capable Claude models, `/v1/models` also advertises a **no-thinking** variant whose id is prefixed with `claude-3-omniroute-no-thinking/`:
|
||
|
||
```
|
||
claude-3-omniroute-no-thinking/<provider>/<model>
|
||
```
|
||
|
||
Selecting this id (e.g. in a Claude Code config that always attaches a `thinking` block) resolves back to the real `<provider>/<model>` with reasoning suppressed — `thinking:{type:"disabled"}` on the `/v1/messages` path, or the `reasoning`/`reasoning_effort` fields dropped on the `/v1/chat/completions` path. The variant is only listed for Claude-family models that support thinking **and** honor `disabled` (so e.g. adaptive-only models that reject `disabled` are excluded). Operators can force the variant on or off per model via `ModelSpec.noThinkingAlias`.
|
||
|
||
---
|
||
|
||
## Provider Plugin Manifest
|
||
|
||
```bash
|
||
GET /api/v1/provider-plugin-manifest
|
||
```
|
||
|
||
Returns the JSON-safe provider plugin manifest used by Bifrost, CLIProxyAPI, and
|
||
future sidecar routers. The response is generated from the TypeScript provider
|
||
registry and intentionally excludes OAuth client secrets, runtime environment
|
||
resolution, executor functions, request headers, and account data.
|
||
|
||
Use this endpoint when a sidecar runs out-of-process and cannot import
|
||
`open-sse/config/providerPluginManifestRegistry.ts` directly.
|
||
|
||
---
|
||
|
||
## Compatibility Endpoints
|
||
|
||
| Method | Path | Format |
|
||
| ------ | ----------------------------------------- | -------------------------------- |
|
||
| POST | `/v1/chat/completions` | OpenAI |
|
||
| POST | `/v1/messages` | Anthropic |
|
||
| POST | `/v1/responses` | OpenAI Responses |
|
||
| POST | `/v1/embeddings` | OpenAI |
|
||
| POST | `/v1/images/generations` | OpenAI Images |
|
||
| POST | `/v1/images/edits` | OpenAI Images (edit/inpaint) |
|
||
| POST | `/v1/videos/generations` | OpenAI-style video generation |
|
||
| POST | `/v1/music/generations` | OpenAI-style music generation |
|
||
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
|
||
| POST | `/v1/audio/speech` | OpenAI TTS (returns audio body) |
|
||
| POST | `/v1/rerank` | Cohere/Voyage-style rerank |
|
||
| POST | `/v1/moderations` | OpenAI Moderations |
|
||
| GET | `/v1/models` | OpenAI |
|
||
| POST | `/v1/messages/count_tokens` | Anthropic |
|
||
| GET | `/v1beta/models` | Gemini |
|
||
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
|
||
| POST | `/v1/api/chat` | Ollama |
|
||
| GET | `/api/v1/vscode/{token}/` | OpenAI catalog alias |
|
||
| GET | `/api/v1/vscode/{token}/models` | OpenAI models alias |
|
||
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenized alias |
|
||
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenized alias |
|
||
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenized alias |
|
||
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenized alias |
|
||
|
||
All POST routes follow the same shape: `Bearer your-api-key` + Zod-validated JSON body (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, etc., see `src/shared/validation/schemas.ts`). 4xx is returned on schema failure.
|
||
|
||
For clients that cannot attach `Authorization: Bearer ...`, OmniRoute also accepts API keys in the URL via either query-string compatibility (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) or the dedicated `/api/v1/vscode/{token}/...` endpoints documented below.
|
||
|
||
```bash
|
||
# Rerank
|
||
POST /v1/rerank { "model": "cohere/rerank-3", "query": "...", "documents": ["..."] }
|
||
|
||
# Moderations
|
||
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
|
||
|
||
# TTS — returns audio/mpeg (or requested format) body
|
||
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
|
||
|
||
# Image edit (multipart)
|
||
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
|
||
|
||
# Video / music generation (provider-prefixed model id)
|
||
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
|
||
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
|
||
```
|
||
|
||
### Dedicated Provider Routes
|
||
|
||
```bash
|
||
POST /v1/providers/{provider}/chat/completions
|
||
POST /v1/providers/{provider}/embeddings
|
||
POST /v1/providers/{provider}/images/generations
|
||
```
|
||
|
||
The provider prefix is auto-added if missing. Mismatched models return `400`.
|
||
|
||
---
|
||
|
||
## Files API
|
||
|
||
OpenAI-compatible files endpoint for batch input/output and file-purpose uploads.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/files` | Upload a file (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 MiB max |
|
||
| GET | `/v1/files` | List files for the authenticated API key |
|
||
| GET | `/v1/files/[id]` | Retrieve a file's metadata |
|
||
| DELETE | `/v1/files/[id]` | Delete a file |
|
||
| GET | `/v1/files/[id]/content` | Stream the raw file body back |
|
||
|
||
**Auth:** Bearer API key — files are scoped per-API-key via `getApiKeyRequestScope`.
|
||
|
||
---
|
||
|
||
## Batches API
|
||
|
||
OpenAI-compatible batch processing.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/batches` | Create batch — body validated by `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
|
||
| GET | `/v1/batches` | List batches |
|
||
| GET | `/v1/batches/[id]` | Retrieve batch status + `request_counts` |
|
||
| DELETE | `/v1/batches/[id]` | Delete a finished/failed batch |
|
||
| POST | `/v1/batches/[id]/cancel` | Cancel an in-progress batch |
|
||
|
||
**Auth:** Bearer API key. Batches are scoped per-API-key.
|
||
|
||
---
|
||
|
||
## Search API
|
||
|
||
Web/search provider abstraction (Tavily, Brave, Exa, Serper, etc.).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------- | ------------------------------------------------------------------------------------ |
|
||
| GET | `/v1/search` | List configured search providers + capabilities |
|
||
| POST | `/v1/search` | Run a search query — body validated by `v1SearchSchema`, supports caching/coalescing |
|
||
| GET | `/v1/search/analytics` | Per-provider hit/latency/cache stats |
|
||
|
||
**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`). Search policy enforced via `enforceApiKeyPolicy`.
|
||
|
||
---
|
||
|
||
## WebSocket Streaming
|
||
|
||
```bash
|
||
GET /v1/ws?handshake=1
|
||
```
|
||
|
||
Validates a WebSocket upgrade handshake and returns the wire protocol example messages (`request`, `cancel`). Actual WS frames are handled by the bundled WS server outside the Next.js route table.
|
||
|
||
**Auth:** Bearer API key during handshake.
|
||
|
||
### Responses API over WebSocket (codex only)
|
||
|
||
```bash
|
||
# Same host:port as the HTTP API (default 20128); upgrade the connection:
|
||
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
|
||
# (or: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
|
||
|
||
# First frame MUST be response.create:
|
||
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
|
||
```
|
||
|
||
A Responses-API-over-WebSocket proxy is wired **exclusively to `codex`** (ChatGPT
|
||
backend). It listens on the same port as the API/dashboard at paths `/v1/responses`,
|
||
`/responses`, and `/api/v1/responses`. On the first `response.create` frame it
|
||
authenticates + prepares via the internal `codex-responses-ws` bridge, selects a
|
||
codex OAuth connection, and tunnels to `wss://chatgpt.com/backend-api/codex/responses`
|
||
via the `wreq-js` transport. **Non-codex models are rejected** (`codex_ws_provider_required`).
|
||
For quota-share routing use `model: "qtSd/<group>/codex/<model>"`. Implemented in
|
||
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
|
||
|
||
**Auth:** Bearer API key during handshake. The bundled HTTP server (`server-ws.mjs`)
|
||
must be the active entrypoint (it is, by default, when `app/server-ws.mjs` exists).
|
||
|
||
#### Model id: use the bare ChatGPT id (no `codex/` prefix)
|
||
|
||
The OpenAI **Codex CLI** validates the model name client-side when
|
||
`supports_websockets = true` and **rejects provider-prefixed ids** like
|
||
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
|
||
a ChatGPT account`). Send the **bare** id (e.g. `gpt-5.5`). OmniRoute's bridge is
|
||
codex-only, so it re-resolves a bare id as a codex model
|
||
(`resolveCodexWsModelInfo`) before tunneling upstream — even though a bare
|
||
`gpt-5.5` would otherwise route to another provider over HTTP.
|
||
|
||
#### Configuring the OpenAI Codex CLI
|
||
|
||
Point the Codex CLI at OmniRoute by adding a custom provider with WebSocket
|
||
support to `~/.codex/config.toml` (use a separate `CODEX_HOME` to avoid touching
|
||
an existing config):
|
||
|
||
```toml
|
||
model = "gpt-5.5" # bare id — NOT "codex/gpt-5.5"
|
||
model_provider = "omniroute"
|
||
|
||
[model_providers.omniroute]
|
||
name = "OmniRoute (WS)"
|
||
base_url = "http://localhost:20128/v1" # no trailing slash; the WS URL is derived (use https/wss in production)
|
||
wire_api = "responses" # only supported value since Feb 2026
|
||
supports_websockets = true # enables the Responses-over-WS transport
|
||
env_key = "OMNIROUTE_API_KEY" # holds the OmniRoute API key (Bearer)
|
||
```
|
||
|
||
```bash
|
||
export OMNIROUTE_API_KEY=sk-... # an OmniRoute API key (any key if REQUIRE_API_KEY=false)
|
||
codex exec "Responda apenas: PONG"
|
||
```
|
||
|
||
The CLI upgrades `base_url + /responses` to a WebSocket and OmniRoute tunnels it
|
||
to the selected codex OAuth connection. Validated end-to-end against the local
|
||
server: ChatGPT returns `codex.rate_limits` + `response.created` and streams the
|
||
completion.
|
||
|
||
---
|
||
|
||
## Quotas & Issues Reporting
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------- | ------------------------------------------------------------------------------------- |
|
||
| GET | `/v1/quotas/check` | Pre-validate quota for a `provider` + `accountId` before issuing a registered key |
|
||
| POST | `/v1/issues/report` | Report a quota/key issuance failure to GitHub (requires `GITHUB_ISSUES_REPO` + token) |
|
||
|
||
**Auth:** Bearer API key (`isAuthenticated`).
|
||
|
||
---
|
||
|
||
## Semantic Cache
|
||
|
||
```bash
|
||
# Get cache stats
|
||
GET /api/cache/stats
|
||
|
||
# Clear all caches
|
||
DELETE /api/cache/stats
|
||
```
|
||
|
||
Response example:
|
||
|
||
```json
|
||
{
|
||
"semanticCache": {
|
||
"memorySize": 42,
|
||
"memoryMaxSize": 500,
|
||
"dbSize": 128,
|
||
"hitRate": 0.65
|
||
},
|
||
"idempotency": {
|
||
"activeKeys": 3,
|
||
"windowMs": 5000
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Dashboard & Management
|
||
|
||
### Authentication
|
||
|
||
| Endpoint | Method | Description |
|
||
| ----------------------------- | ------- | --------------------- |
|
||
| `/api/auth/login` | POST | Login |
|
||
| `/api/auth/logout` | POST | Logout |
|
||
| `/api/settings/require-login` | GET/PUT | Toggle login required |
|
||
|
||
### Provider Management
|
||
|
||
| Endpoint | Method | Description |
|
||
| ---------------------------- | --------------------- | ---------------------------------------------- |
|
||
| `/api/providers` | GET/POST | List / create providers |
|
||
| `/api/providers/[id]` | GET/PUT/DELETE | Manage a provider |
|
||
| `/api/providers/[id]/test` | POST | Test provider connection |
|
||
| `/api/providers/[id]/models` | GET | List provider models |
|
||
| `/api/providers/validate` | POST | Validate provider config |
|
||
| `/api/provider-nodes*` | Various | Provider node management |
|
||
| `/api/provider-models` | GET/POST/PATCH/DELETE | Custom models (add, update, hide/show, delete) |
|
||
|
||
### OAuth Flows
|
||
|
||
| Endpoint | Method | Description |
|
||
| -------------------------------- | ------- | ----------------------- |
|
||
| `/api/oauth/[provider]/[action]` | Various | Provider-specific OAuth |
|
||
|
||
### Routing & Config
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------------- | -------- | ----------------------------- |
|
||
| `/api/models/alias` | GET/POST | Model aliases |
|
||
| `/api/models/catalog` | GET | All models by provider + type |
|
||
| `/api/combos*` | Various | Combo management |
|
||
| `/api/keys*` | Various | API key management |
|
||
| `/api/pricing` | GET | Model pricing |
|
||
|
||
### Usage & Analytics
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------------------- | --------------- | ------------------------------- |
|
||
| `/api/usage/history` | GET | Usage history |
|
||
| `/api/usage/logs` | GET | Usage logs |
|
||
| `/api/usage/request-logs` | GET | Request-level logs |
|
||
| `/api/usage/[connectionId]` | GET | Per-connection usage |
|
||
| `/api/usage/token-limits` | GET/POST/DELETE | Per-API-key token-limit budgets |
|
||
|
||
### Settings
|
||
|
||
| Endpoint | Method | Description |
|
||
| ------------------------------------- | ------------- | --------------------------------------------------- |
|
||
| `/api/settings` | GET/PUT/PATCH | General settings |
|
||
| `/api/settings/proxy` | GET/PUT | Network proxy config |
|
||
| `/api/settings/proxy/test` | POST | Test proxy connection |
|
||
| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist |
|
||
| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget |
|
||
| `/api/settings/system-prompt` | GET/PUT | Global system prompt |
|
||
| `/api/settings/compression` | GET/PUT | Global compression config |
|
||
| `/api/settings/purge-request-history` | POST | Clear request log rows and local call-log artifacts |
|
||
|
||
### Context & Compression
|
||
|
||
| Endpoint | Method | Description |
|
||
| -------------------------------------- | -------------- | ------------------------------------------------------------------------ |
|
||
| `/api/compression/preview` | POST | Preview off/lite/standard/aggressive/ultra/RTK/stacked compression |
|
||
| `/api/compression/language-packs` | GET | List available Caveman language packs |
|
||
| `/api/compression/rules` | GET | List Caveman rule metadata |
|
||
| `/api/context/caveman/config` | GET/PUT | Caveman-specific settings alias |
|
||
| `/api/context/rtk/config` | GET/PUT | RTK-specific settings, including custom filters and raw-output retention |
|
||
| `/api/context/rtk/filters` | GET | RTK filter catalog and custom-filter diagnostics |
|
||
| `/api/context/rtk/test` | POST | Run RTK preview/test against a text payload |
|
||
| `/api/context/rtk/raw-output/[id]` | GET | Read retained redacted raw output by pointer id |
|
||
| `/api/context/combos` | GET/POST | Compression combo list/create |
|
||
| `/api/context/combos/[id]` | GET/PUT/DELETE | Compression combo detail/update/delete |
|
||
| `/api/context/combos/[id]/assignments` | GET/PUT | Assign compression combos to routing combos |
|
||
| `/api/context/analytics` | GET | Compression analytics alias |
|
||
|
||
### Monitoring
|
||
|
||
| Endpoint | Method | Description |
|
||
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||
| `/api/sessions` | GET | Active session tracking |
|
||
| `/api/rate-limits` | GET | Per-account rate limits |
|
||
| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
|
||
| `/api/cache/stats` | GET/DELETE | Cache stats / clear |
|
||
|
||
### Backup & Export/Import
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------------------- | ------ | --------------------------------------- |
|
||
| `/api/db-backups` | GET | List available backups |
|
||
| `/api/db-backups` | PUT | Create a manual backup |
|
||
| `/api/db-backups` | POST | Restore from a specific backup |
|
||
| `/api/db-backups/export` | GET | Download database as .sqlite file |
|
||
| `/api/db-backups/import` | POST | Upload .sqlite file to replace database |
|
||
| `/api/db-backups/exportAll` | GET | Download full backup as .tar.gz archive |
|
||
|
||
### Cloud Sync
|
||
|
||
| Endpoint | Method | Description |
|
||
| ---------------------- | ------- | --------------------- |
|
||
| `/api/sync/cloud` | Various | Cloud sync operations |
|
||
| `/api/sync/initialize` | POST | Initialize sync |
|
||
| `/api/cloud/*` | Various | Cloud management |
|
||
|
||
### Tunnels
|
||
|
||
| Endpoint | Method | Description |
|
||
| -------------------------- | ------ | ----------------------------------------------------------------------- |
|
||
| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard |
|
||
| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) |
|
||
| `/api/tunnels/ngrok` | GET | Read ngrok Tunnel runtime status for the dashboard |
|
||
| `/api/tunnels/ngrok` | POST | Enable or disable the ngrok Tunnel (`action=enable/disable`) |
|
||
|
||
### CLI Tools
|
||
|
||
| Endpoint | Method | Description |
|
||
| ---------------------------------- | ------ | ------------------- |
|
||
| `/api/cli-tools/claude-settings` | GET | Claude CLI status |
|
||
| `/api/cli-tools/codex-settings` | GET | Codex CLI status |
|
||
| `/api/cli-tools/droid-settings` | GET | Droid CLI status |
|
||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI status |
|
||
| `/api/cli-tools/runtime/[toolId]` | GET | Generic CLI runtime |
|
||
|
||
CLI responses include: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
|
||
|
||
### ACP Agents
|
||
|
||
| Endpoint | Method | Description |
|
||
| ----------------- | ------ | -------------------------------------------------------- |
|
||
| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status |
|
||
| `/api/acp/agents` | POST | Add custom agent or refresh detection cache |
|
||
| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param |
|
||
|
||
GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom).
|
||
|
||
### Resilience & Rate Limits
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------------------------- | --------- | ------------------------------------------------------------------------------------ |
|
||
| `/api/resilience` | GET/PATCH | Get/update request queue, connection cooldown, provider breaker, and wait settings |
|
||
| `/api/resilience/reset` | POST | Reset provider circuit breakers |
|
||
| `/api/resilience/model-cooldowns` | GET | List active per-(provider, connection, model) lockouts, sorted by remaining time |
|
||
| `/api/resilience/model-cooldowns` | DELETE | Clear a model lockout — body `{provider, model}` or `{all: true}` to wipe everything |
|
||
| `/api/rate-limits` | GET | Per-account rate limit status |
|
||
| `/api/rate-limit` | GET | Global rate limit configuration |
|
||
|
||
> All four `/api/resilience/*` routes require **management auth** (`requireManagementAuth`). See [Resilience (extended)](#resilience-extended) for a full breakdown of provider breaker vs connection cooldown vs model lockout.
|
||
|
||
### Evals
|
||
|
||
| Endpoint | Method | Description |
|
||
| ------------ | -------- | --------------------------------- |
|
||
| `/api/evals` | GET/POST | List eval suites / run evaluation |
|
||
|
||
### Policies
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------- | --------------- | ----------------------- |
|
||
| `/api/policies` | GET/POST/DELETE | Manage routing policies |
|
||
|
||
### Compliance
|
||
|
||
| Endpoint | Method | Description |
|
||
| --------------------------- | ------ | ----------------------------- |
|
||
| `/api/compliance/audit-log` | GET | Compliance audit log (last N) |
|
||
|
||
### v1beta (Gemini-Compatible)
|
||
|
||
| Endpoint | Method | Description |
|
||
| -------------------------- | ------ | --------------------------------- |
|
||
| `/v1beta/models` | GET | List models in Gemini format |
|
||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
|
||
|
||
These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.
|
||
|
||
### Internal / System APIs
|
||
|
||
| Endpoint | Method | Description |
|
||
| ------------------------ | ------ | ---------------------------------------------------- |
|
||
| `/api/init` | GET | Application initialization check (used on first run) |
|
||
| `/api/tags` | GET | Ollama-compatible model tags (for Ollama clients) |
|
||
| `/api/restart` | POST | Trigger graceful server restart |
|
||
| `/api/shutdown` | POST | Trigger graceful server shutdown |
|
||
| `/api/system/env/repair` | POST | Repair OAuth provider environment variables |
|
||
|
||
> **Note:** These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.
|
||
|
||
### OAuth Environment Repair _(v3.6.1+)_
|
||
|
||
```bash
|
||
POST /api/system/env/repair
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"provider": "claude-code"
|
||
}
|
||
```
|
||
|
||
Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
|
||
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Audio Transcription
|
||
|
||
```bash
|
||
POST /v1/audio/transcriptions
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
Transcribe audio files using Deepgram or AssemblyAI.
|
||
|
||
**Request:**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||
-H "Authorization: Bearer your-api-key" \
|
||
-F "file=@recording.mp3" \
|
||
-F "model=deepgram/nova-3"
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"text": "Hello, this is the transcribed audio content.",
|
||
"task": "transcribe",
|
||
"language": "en",
|
||
"duration": 12.5
|
||
}
|
||
```
|
||
|
||
**Supported providers:** `deepgram/nova-3`, `assemblyai/best`.
|
||
|
||
**Supported formats:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
|
||
|
||
---
|
||
|
||
## Ollama Compatibility
|
||
|
||
For clients that use Ollama's API format:
|
||
|
||
```bash
|
||
# Chat endpoint (Ollama format)
|
||
POST /v1/api/chat
|
||
|
||
# Model listing (Ollama format)
|
||
GET /api/tags
|
||
```
|
||
|
||
Requests are automatically translated between Ollama and internal formats.
|
||
|
||
## Tokenized VS Code / Headerless Aliases
|
||
|
||
Use these aliases when an integration cannot inject an `Authorization` header and needs the API key embedded in the base URL.
|
||
|
||
```bash
|
||
# OpenAI-style catalog alias
|
||
GET /api/v1/vscode/{token}/
|
||
GET /api/v1/vscode/{token}/models
|
||
|
||
# OpenAI-style chat aliases
|
||
POST /api/v1/vscode/{token}/chat/completions
|
||
POST /api/v1/vscode/{token}/responses
|
||
|
||
# Ollama-style aliases
|
||
POST /api/v1/vscode/{token}/api/chat
|
||
GET /api/v1/vscode/{token}/api/tags
|
||
```
|
||
|
||
Example:
|
||
|
||
```bash
|
||
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
|
||
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
|
||
```
|
||
|
||
Notes:
|
||
|
||
- The tokenized aliases reuse the same handlers as `/v1/*` and `/api/tags`; response shapes stay identical.
|
||
- Prefer `Authorization: Bearer ...` whenever the client supports custom headers.
|
||
- URL-based tokens may appear in reverse-proxy logs, browser history, and telemetry outside OmniRoute. Treat them as a compatibility option, not the default authentication mode.
|
||
|
||
---
|
||
|
||
## Telemetry
|
||
|
||
```bash
|
||
# Get latency telemetry summary (p50/p95/p99 per provider)
|
||
GET /api/telemetry/summary
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
|
||
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Budget
|
||
|
||
```bash
|
||
# Get budget status for all API keys
|
||
GET /api/usage/budget
|
||
|
||
# Set or update a budget
|
||
POST /api/usage/budget
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"apiKeyId": "key-123",
|
||
"dailyLimitUsd": 5.00,
|
||
"weeklyLimitUsd": 30.00,
|
||
"monthlyLimitUsd": 100.00,
|
||
"warningThreshold": 0.8,
|
||
"resetInterval": "monthly"
|
||
}
|
||
```
|
||
|
||
> **Schema notes** (`setBudgetSchema`): `apiKeyId` is required; at least one of `dailyLimitUsd`, `weeklyLimitUsd`, or `monthlyLimitUsd` must be greater than zero. Optional fields: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). The legacy `{keyId, limit, period}` shape returns `400 Bad Request`.
|
||
|
||
## Token Limits
|
||
|
||
Per-API-key **token** budgets (distinct from the USD-based Budget above). Enforced inline on the request path: when a key's current window usage reaches its limit, requests are rejected with `429 Too Many Requests`. Limits can be scoped to a specific `model`, a `provider`, or applied `global`ly across the key; when several limits match a request, the most restrictive one wins.
|
||
|
||
```bash
|
||
# List a key's token limits (includes live window usage)
|
||
GET /api/usage/token-limits?apiKeyId=key-123
|
||
|
||
# Create or update a token limit
|
||
POST /api/usage/token-limits
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"apiKeyId": "key-123",
|
||
"scopeType": "model",
|
||
"scopeValue": "openai/gpt-4o",
|
||
"tokenLimit": 1000000,
|
||
"resetInterval": "monthly",
|
||
"enabled": true
|
||
}
|
||
|
||
# Delete a token limit by id
|
||
DELETE /api/usage/token-limits?id=tl-abc
|
||
```
|
||
|
||
> **Schema notes** (`setTokenLimitSchema`): `apiKeyId` and `scopeType` (`model` | `provider` | `global`) are required. `scopeValue` is required unless `scopeType` is `global` (e.g. a model id for `model` scope, a provider id for `provider` scope). `tokenLimit` must be a positive integer (coerced from string). Optional: `id` (omit to create, supply to update), `resetInterval` (`daily` | `weekly` | `monthly`, default `monthly`), `resetTime` (`HH:MM`), `enabled` (default `true`). `GET` responses enrich each limit with `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, and `nextResetAt`. This is a management-class endpoint (auth enforced centrally by the authz pipeline).
|
||
|
||
## Request Processing
|
||
|
||
1. Client sends request to `/v1/*`
|
||
2. Route handler calls `handleChat`, `handleEmbedding`, `handleAudioTranscription`, or `handleImageGeneration`
|
||
3. Model is resolved (direct provider/model or alias/combo)
|
||
4. Credentials selected from local DB with account availability filtering
|
||
5. For chat: `handleChatCore` checks semantic/signature cache and resolves combo compression settings
|
||
6. Proactive compression runs before provider translation when enabled (`lite`, Caveman, RTK, or stacked)
|
||
7. Provider executor sends upstream request
|
||
8. Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
|
||
9. Usage, compression analytics, and request logs are recorded
|
||
10. Fallback applies on errors according to combo rules
|
||
|
||
Full architecture reference: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
|
||
|
||
---
|
||
|
||
## Combo Management
|
||
|
||
Higher-level routing combos (already summarized under `/api/combos*`) can also be mapped 1:1 from a model id pattern, allowing transparent redirection of an OpenAI-style model id to a combo.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
|
||
| GET | `/api/model-combo-mappings` | List all model→combo mappings |
|
||
| POST | `/api/model-combo-mappings` | Create mapping — body: `{pattern, comboId, priority?, enabled?, description?}` |
|
||
| GET | `/api/model-combo-mappings/[id]` | Retrieve a single mapping |
|
||
| PUT | `/api/model-combo-mappings/[id]` | Update fields of an existing mapping |
|
||
| DELETE | `/api/model-combo-mappings/[id]` | Remove a mapping |
|
||
|
||
**Auth:** management session/API key (`requireManagementAuth`).
|
||
|
||
---
|
||
|
||
## Webhooks
|
||
|
||
Outbound webhook subscriptions for OmniRoute events (request completion, quota exhaustion, key rotation, etc.).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------- | --------------------------------------------------------------------- |
|
||
| GET | `/api/webhooks` | List webhooks (secrets are masked to `<prefix>...`) |
|
||
| POST | `/api/webhooks` | Create webhook — body: `{url, events?: ["*"], secret?, description?}` |
|
||
| GET | `/api/webhooks/[id]` | Retrieve a webhook |
|
||
| PUT | `/api/webhooks/[id]` | Update url/events/secret/description |
|
||
| DELETE | `/api/webhooks/[id]` | Remove a webhook |
|
||
| POST | `/api/webhooks/[id]/test` | Send a test payload to the webhook URL and return delivery status |
|
||
|
||
**Auth:** management session/API key (`requireManagementAuth`).
|
||
|
||
---
|
||
|
||
## Registered Keys (Auto-Management)
|
||
|
||
Used by the auto-key management subsystem to issue and rotate API keys against a backing provider/account, with daily/hourly quotas.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/v1/registered-keys` | List registered keys (masked prefix only) |
|
||
| POST | `/api/v1/registered-keys` | Issue a new registered key — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Returns the raw key **once**. Returns `429` on quota refusal. |
|
||
| GET | `/api/v1/registered-keys/[id]` | Retrieve a registered key's metadata (no raw material) |
|
||
| DELETE | `/api/v1/registered-keys/[id]` | Revoke a registered key |
|
||
| POST | `/api/v1/registered-keys/[id]/revoke` | Explicit revoke endpoint (same effect as DELETE) |
|
||
|
||
**Auth:** Bearer API key (`isAuthenticated`). See also `/v1/quotas/check` and `/v1/issues/report`.
|
||
|
||
---
|
||
|
||
## Agents Protocol
|
||
|
||
Cloud agent tasks (Claude Code, Codex Cloud, OpenHands, etc.) executed remotely on behalf of OmniRoute users.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/v1/agents/tasks` | List tasks — optional `?provider=`, `?status=`, `?limit=` (1–500, default 50) |
|
||
| POST | `/api/v1/agents/tasks` | Create task — body validated by `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Returns `201` with task envelope |
|
||
| DELETE | `/api/v1/agents/tasks?id=...` | Delete a task |
|
||
| GET | `/api/v1/agents/tasks/[id]` | Read task — synchronously refreshes status from the upstream cloud agent when an `external_id` is set |
|
||
| POST | `/api/v1/agents/tasks/[id]` | Discriminated action: `{action: "approve"}`, `{action: "message", message}`, or `{action: "cancel"}` |
|
||
| DELETE | `/api/v1/agents/tasks/[id]` | Delete a specific task by id |
|
||
|
||
> **Auth:** management auth required on every method (`requireCloudAgentManagementAuth`). Prior to v3.8.0 these were unauthenticated — see commit `588a0333` for the breaking change.
|
||
|
||
```bash
|
||
# Create a Claude Code cloud task
|
||
curl -X POST http://localhost:20128/api/v1/agents/tasks \
|
||
-H "Authorization: Bearer your-management-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
|
||
```
|
||
|
||
---
|
||
|
||
## Management Proxies
|
||
|
||
Outbound HTTP(S)/SOCKS proxies that can be assigned to providers, accounts, or globally.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/v1/management/proxies` | List proxies (with `?id=` returns one; with `?id=&where_used=1` returns the assignment graph) |
|
||
| POST | `/api/v1/management/proxies` | Create proxy — body validated by `createProxyRegistrySchema` |
|
||
| PATCH | `/api/v1/management/proxies` | Update proxy — body validated by `updateProxyRegistrySchema` (requires `id`) |
|
||
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Delete proxy (use `force=1` to detach assignments) |
|
||
| GET | `/api/v1/management/proxies/assignments` | List assignments — filterable by `proxy_id`, `scope`, `scope_id`; pass `resolve_connection_id=<id>` to resolve the active proxy for a connection |
|
||
| PUT | `/api/v1/management/proxies/assignments` | Assign — body validated by `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Clears dispatcher cache |
|
||
| PUT | `/api/v1/management/proxies/bulk-assign` | Bulk-assign — body validated by `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
|
||
| GET | `/api/v1/management/proxies/health?hours=24` | Aggregate proxy health (success/fail counts, latency) over a window |
|
||
|
||
**Auth:** management session/API key on every route (`requireManagementAuth`).
|
||
|
||
> The task description's `POST /api/v1/management/proxies/[id]/assignments` and `POST /api/v1/management/proxies/[id]/health` are served by the flat `/assignments` and `/health` routes shown above — there are no per-id subroutes in the codebase.
|
||
|
||
---
|
||
|
||
## Resilience (extended)
|
||
|
||
OmniRoute exposes three independent temporary-failure mechanisms; the management endpoints below let operators read and override them:
|
||
|
||
| Scope | State storage | Read | Reset / clear |
|
||
| ------------------- | ------------------------------------------ | ----------------------------------------- | ------------------------------------------- |
|
||
| Provider breaker | `domain_circuit_breakers` + in-memory | `/api/monitoring/health` | `POST /api/resilience/reset` |
|
||
| Connection cooldown | `rateLimitedUntil` on provider connections | `/api/rate-limits`, `/api/providers/[id]` | (re-enables lazily; clear via provider PUT) |
|
||
| Model lockout | In-memory model-availability registry | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
|
||
|
||
`PATCH /api/resilience` accepts provider breaker overrides under `providerBreaker.oauth` and `providerBreaker.apikey`. Each profile supports `degradationThreshold`, `failureThreshold`, and `resetTimeoutMs`; the same fields are exposed in Dashboard → Settings → Resilience.
|
||
|
||
```bash
|
||
# Clear a single model lockout
|
||
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
|
||
-H "Cookie: auth_token=..." \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"provider":"openai","model":"gpt-4o-mini"}'
|
||
|
||
# Wipe every lockout
|
||
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
|
||
-H "Cookie: auth_token=..." \
|
||
-d '{"all":true}'
|
||
```
|
||
|
||
Full conceptual reference and breaker defaults: see [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".
|
||
|
||
---
|
||
|
||
## Skills
|
||
|
||
Skill framework for extending OmniRoute with custom executable handlers, plus marketplace integrations.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/skills` | List installed skills — filterable by `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, paginated |
|
||
| GET | `/api/skills/[id]` | Retrieve one skill |
|
||
| PUT | `/api/skills/[id]` | Update skill (name, description, mode, schema, handler, tags) |
|
||
| DELETE | `/api/skills/[id]` | Uninstall a skill |
|
||
| POST | `/api/skills/install` | Install a skill from a raw manifest — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
|
||
| GET | `/api/skills/executions` | List recent skill executions (audit trail with inputs/outputs/duration) |
|
||
| GET | `/api/skills/marketplace?q=...` | Search/popular list from the SkillsMP marketplace (requires `skillsmpApiKey` setting) |
|
||
| POST | `/api/skills/marketplace/install` | Install a skill by id from SkillsMP |
|
||
| GET | `/api/skills/skillssh?q=&limit=` | Search the skills.sh registry |
|
||
| POST | `/api/skills/skillssh/install` | Install a skill by id from skills.sh |
|
||
|
||
**Auth:** management session/API key. Marketplace search routes accept either management auth or a Bearer API key (`isAuthenticated`).
|
||
|
||
---
|
||
|
||
## Memory
|
||
|
||
Persistent conversational/factual memory store, scoped per API key / session.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/memory` | List memories — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, with `offset/limit` or `page/limit` pagination |
|
||
| POST | `/api/memory` | Create memory — body validated by Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
|
||
| GET | `/api/memory/[id]` | Retrieve one memory |
|
||
| DELETE | `/api/memory/[id]` | Delete a memory |
|
||
| GET | `/api/memory/health` | Memory subsystem health (DB connectivity, embeddings backend, vector index status) |
|
||
|
||
**Auth:** management session/API key (`requireManagementAuth`). `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (see `MemoryType` in `src/lib/memory/types.ts`).
|
||
|
||
---
|
||
|
||
## MCP Server
|
||
|
||
OmniRoute ships an embedded Model Context Protocol server with 3 transports (stdio, SSE, streamable-http) and scoped tools. The dashboard endpoints below read status/audit data and proxy the HTTP transports.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
|
||
| GET | `/api/mcp/status` | Heartbeat, transport, online state, last call, top tools, 24h success rate |
|
||
| GET | `/api/mcp/tools` | List of MCP tools with `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
|
||
| GET | `/api/mcp/sse` | Open SSE stream for the SSE transport (returns `503` if MCP disabled or transport mismatch) |
|
||
| POST | `/api/mcp/sse` | Send JSON-RPC frame on the SSE transport |
|
||
| GET | `/api/mcp/stream` | Open SSE side of the Streamable HTTP transport (server-initiated messages) |
|
||
| POST | `/api/mcp/stream` | Send JSON-RPC frame on the Streamable HTTP transport |
|
||
| DELETE | `/api/mcp/stream` | End a Streamable HTTP session |
|
||
| GET | `/api/mcp/audit` | Query audit log — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
|
||
| GET | `/api/mcp/audit/stats` | Aggregate audit stats (totals, success rate, avg duration, top tools) |
|
||
|
||
**Auth:** the `sse`/`stream` transports honor the MCP-specific auth surface (Bearer API key with `mcp` scope); the `status`/`tools`/`audit*` routes are readable from the dashboard (no extra auth required beyond reaching the dashboard host).
|
||
|
||
> Both HTTP transports are gated by `settings.mcpEnabled` and `settings.mcpTransport` — a transport mismatch returns `400`, an MCP disabled state returns `503`.
|
||
|
||
---
|
||
|
||
## A2A Server
|
||
|
||
OmniRoute exposes an A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint plus a REST wrapper for inspection/dashboard use.
|
||
|
||
### JSON-RPC
|
||
|
||
```bash
|
||
POST /a2a
|
||
Authorization: Bearer your-api-key # optional unless OMNIROUTE_API_KEY is set
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "message/send",
|
||
"params": {
|
||
"skill": "smart-routing",
|
||
"messages": [{"role": "user", "content": "Route this coding task"}]
|
||
}
|
||
}
|
||
```
|
||
|
||
Supported methods (all gated on `settings.a2aEnabled`):
|
||
|
||
| Method | Description |
|
||
| ---------------- | ------------------------------------------------------------------ |
|
||
| `message/send` | Synchronous skill execution; returns `{task, artifacts, metadata}` |
|
||
| `message/stream` | Streaming SSE execution of the same skill set |
|
||
| `tasks/get` | Fetch a task by `taskId` |
|
||
| `tasks/cancel` | Cancel a task by `taskId` |
|
||
|
||
Built-in skills: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
|
||
|
||
### Agent Card
|
||
|
||
```bash
|
||
GET /.well-known/agent.json
|
||
```
|
||
|
||
Returns the public A2A agent card (name, description, capabilities, skill catalog, auth scheme) — cached publicly for 1h. No auth required.
|
||
|
||
### REST helpers
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/a2a/status` | A2A enabled + task stats + cached agent card summary |
|
||
| GET | `/api/a2a/tasks` | List tasks — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
|
||
| POST | `/api/a2a/tasks` | (Not implemented as a REST helper — create via JSON-RPC `message/send`) |
|
||
| GET | `/api/a2a/tasks/[id]` | Retrieve one task |
|
||
| POST | `/api/a2a/tasks/[id]/cancel` | Cancel a task |
|
||
|
||
**Auth:** the REST helpers run without management auth (dashboard-readable); the JSON-RPC `/a2a` route uses Bearer `OMNIROUTE_API_KEY` if configured.
|
||
|
||
---
|
||
|
||
## Cloud, Evals & Assess
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
|
||
| POST | `/api/cloud/auth` | Verify a Bearer key and return masked provider connections + model aliases for cloud sync clients |
|
||
| POST | `/api/cloud/credentials/update` | Update encrypted credentials for a cloud-synced provider |
|
||
| POST | `/api/cloud/model/resolve` | Resolve a logical model id to a concrete provider/model using the local routing table |
|
||
| GET | `/api/cloud/models/alias` | List model aliases as exposed to cloud sync |
|
||
| GET | `/api/assess` | Read latest assessment categorizations (per-provider/model) |
|
||
| POST | `/api/assess` | Run an assessment — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
|
||
| GET | `/api/evals` | List built-in eval suites + most recent runs |
|
||
| POST | `/api/evals` | Trigger an eval run |
|
||
| POST | `/api/evals/suites` | Create a custom eval suite — body validated by `evalSuiteSaveSchema` |
|
||
| GET | `/api/evals/suites/[id]` | Retrieve a custom eval suite |
|
||
|
||
**Auth:** `/api/cloud/auth` validates a Bearer key directly; the other `/api/cloud/*`, `/api/evals/*`, and `/api/assess` routes require management session/API key. `/api/assess` POST uses `validateBody` with a discriminated-union scope schema.
|
||
|
||
---
|
||
|
||
## ACP (Agent Client Protocol) Management
|
||
|
||
as child processes. These endpoints manage ACP agent detection and custom agent
|
||
registration.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/acp/agents` | List all known CLI agents (built-in + custom) with installation status, version, binary |
|
||
| POST | `/api/acp/agents` | Register a custom ACP agent or refresh cache — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` or `{action: "refresh"}` |
|
||
| DELETE | `/api/acp/agents` | Remove a custom ACP agent — query param: `?id=<agentId>` |
|
||
|
||
**Response example** (`GET /api/acp/agents`):
|
||
|
||
```json
|
||
{
|
||
"agents": [
|
||
{
|
||
"id": "claude",
|
||
"name": "Claude Code CLI",
|
||
"binary": "claude",
|
||
"version": "1.0.45",
|
||
"installed": true,
|
||
"protocol": "stdio",
|
||
"providerAlias": "claude",
|
||
"isCustom": false
|
||
},
|
||
{
|
||
"id": "my-custom-cli",
|
||
"name": "My Custom CLI",
|
||
"installed": false,
|
||
"protocol": "stdio",
|
||
"providerAlias": "my-provider",
|
||
"isCustom": true
|
||
}
|
||
],
|
||
"cacheTtlMs": 60000,
|
||
"cacheAge": 1234
|
||
}
|
||
```
|
||
|
||
**Auth:** Requires management session (dashboard `auth_token` cookie) or a
|
||
management-scoped API key.
|
||
|
||
See [ACP Framework](../frameworks/ACP.md) for full details.
|
||
|
||
---
|
||
|
||
## Analytics & Observability
|
||
|
||
Real-time analytics endpoints for monitoring routing, compression, and provider
|
||
diversity. These power the `/dashboard/analytics/*` pages.
|
||
|
||
### Auto-routing analytics
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/auto-routing` | Aggregate auto-routing stats: total calls, strategy distribution, tier distribution, top providers |
|
||
| GET | `/api/analytics/auto-routing?days=7` | Time-windowed stats (default 24h) |
|
||
|
||
**Response example**:
|
||
|
||
```json
|
||
{
|
||
"window": "24h",
|
||
"totalCalls": 1234,
|
||
"strategyBreakdown": {
|
||
"rules": 800,
|
||
"cost": 200,
|
||
"latency": 150,
|
||
"sla-aware": 50,
|
||
"lkgp": 34
|
||
},
|
||
"tierBreakdown": {
|
||
"ultra": 100,
|
||
"pro": 500,
|
||
"standard": 400,
|
||
"free": 234
|
||
},
|
||
"topProviders": [
|
||
{ "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
|
||
{ "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
|
||
]
|
||
}
|
||
```
|
||
|
||
### Compression analytics
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------------- | ------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/compression` | Aggregate compression stats: tokens saved, savings %, mode distribution, engine usage |
|
||
|
||
**Response example**:
|
||
|
||
```json
|
||
{
|
||
"window": "24h",
|
||
"totalOriginalTokens": 5000000,
|
||
"totalCompressedTokens": 3500000,
|
||
"totalSavings": 1500000,
|
||
"savingsPct": 30.0,
|
||
"modeBreakdown": {
|
||
"lite": 400,
|
||
"standard": 600,
|
||
"aggressive": 100,
|
||
"ultra": 50,
|
||
"rtk": 84
|
||
},
|
||
"engineBreakdown": {
|
||
"caveman": 800,
|
||
"rtk": 434
|
||
}
|
||
}
|
||
```
|
||
|
||
### Provider diversity tracking
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/diversity` | Shannon entropy-based diversity tracking: prevents single points of failure by measuring provider spread |
|
||
|
||
**Response example**:
|
||
|
||
```json
|
||
{
|
||
"window": "24h",
|
||
"shannonEntropy": 2.45,
|
||
"maxEntropy": 3.17,
|
||
"diversityRatio": 0.77,
|
||
"providerUsage": {
|
||
"openai": 0.4,
|
||
"anthropic": 0.25,
|
||
"google": 0.2,
|
||
"kiro": 0.15
|
||
},
|
||
"warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
|
||
}
|
||
```
|
||
|
||
**Auth:** Requires management session or management-scoped API key.
|
||
|
||
---
|
||
|
||
## Admin Operations
|
||
|
||
Admin-only endpoints for operational management.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/admin/concurrency` | Read current concurrency limits (global + per-provider) |
|
||
| POST | `/api/admin/concurrency` | Update concurrency limits — body: `{global?: number, perProvider?: Record<string, number>}` |
|
||
|
||
**Auth:** Requires management session with admin scope.
|
||
|
||
---
|
||
|
||
## CLI Tools Management
|
||
|
||
Manage CLI tools that integrate with OmniRoute (antigravity, chipotle, commandCode,
|
||
devin-cli, etc.). See [Provider Reference](./PROVIDER_REFERENCE.md) for the full list.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/cli-tools/all-statuses` | Status of all CLI tools (installed, version, last seen) |
|
||
| GET | `/api/cli-tools/[id]/status` | Status of a specific CLI tool (id can be: antigravity, chipotle, commandCode, devin-cli, etc.) |
|
||
| POST | `/api/cli-tools/apply` | Apply a CLI tool configuration to a provider connection |
|
||
| GET | `/api/cli-tools/backups` | List CLI tool configuration backups |
|
||
| POST | `/api/cli-tools/backups` | Create a backup of all CLI tool configurations |
|
||
| POST | `/api/cli-tools/[id]/restore` | Restore a CLI tool from a backup |
|
||
| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM proxy status (the "antigravity-mitm" CLI tool) |
|
||
| POST | `/api/cli-tools/antigravity-mitm/alias` | Configure antigravity-mitm aliases |
|
||
|
||
**Auth:** Requires management session.
|
||
|
||
---
|
||
|
||
## Agent Skills
|
||
|
||
Manage AI agent skills (similar to OpenAI's custom GPTs but for agents).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------------- | --------------------------------------------------------------------------------------- |
|
||
| GET | `/api/agent-skills` | List all agent skills (built-in + custom) |
|
||
| GET | `/api/agent-skills/[id]` | Get a specific agent skill |
|
||
| POST | `/api/agent-skills` | Create a custom agent skill — body: `{name, description, prompt, model?, temperature?}` |
|
||
| PUT | `/api/agent-skills/[id]` | Update a custom agent skill |
|
||
| DELETE | `/api/agent-skills/[id]` | Delete a custom agent skill |
|
||
| GET | `/api/agent-skills/[id]/raw` | Get raw prompt + metadata (no execution) |
|
||
| POST | `/api/agent-skills/generate` | AI-generate a new skill from a natural language description |
|
||
|
||
**Auth:** Requires management session or management-scoped API key.
|
||
|
||
---
|
||
|
||
## Cache Management
|
||
|
||
Manage the semantic cache and reasoning cache.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/cache` | Cache overview: total entries, hit rate, size on disk |
|
||
| GET | `/api/cache/entries` | List cached entries (with pagination) |
|
||
| DELETE | `/api/cache/entries` | Delete cache entries (filter by query parameters) |
|
||
| GET | `/api/cache/stats` | Detailed cache statistics (per-provider, per-model) |
|
||
| GET | `/api/cache/reasoning` | Reasoning cache status (for reasoning replay) |
|
||
| DELETE | `/api/cache/reasoning` | Clear reasoning cache — query params: `?toolCallId=<id>` (single) or `?provider=<p>` or no params (all) |
|
||
|
||
**Auth:** Requires management session.
|
||
|
||
---
|
||
|
||
## Memory System
|
||
|
||
Manage persistent memory (FTS5 + vector embeddings).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------- | --------------------------------------------------------------------- |
|
||
| GET | `/api/memory` | List memory entries (filter by scope, type, search query) |
|
||
| POST | `/api/memory` | Create a new memory entry — body: `{scope, type, content, metadata?}` |
|
||
| GET | `/api/memory/[id]` | Get a specific memory entry |
|
||
| PUT | `/api/memory/[id]` | Update a memory entry |
|
||
| DELETE | `/api/memory/[id]` | Delete a memory entry |
|
||
| GET | `/api/memory/search` | Search memory (FTS5 + vector) |
|
||
| POST | `/api/memory/clear` | Clear memory entries (with filters) |
|
||
| GET | `/api/memory/stats` | Memory statistics (total entries, embedding coverage, etc.) |
|
||
|
||
**Auth:** Requires management session or management-scoped API key.
|
||
|
||
---
|
||
|
||
## Webhooks
|
||
|
||
Manage webhook subscriptions for events.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------------- | ------------------------------------------------------------------------- |
|
||
| GET | `/api/webhooks` | List all webhook subscriptions |
|
||
| POST | `/api/webhooks` | Create a webhook subscription — body: `{url, events[], secret?, active?}` |
|
||
| GET | `/api/webhooks/[id]` | Get a specific webhook subscription |
|
||
| PUT | `/api/webhooks/[id]` | Update a webhook subscription |
|
||
| DELETE | `/api/webhooks/[id]` | Delete a webhook subscription |
|
||
| GET | `/api/webhooks/events` | List all available webhook event types |
|
||
| GET | `/api/webhooks/[id]/deliveries` | List delivery history for a webhook (success/failure log) |
|
||
| POST | `/api/webhooks/[id]/test` | Send a test event to a webhook |
|
||
|
||
**Auth:** Requires management session.
|
||
|
||
See [Webhooks Framework](../frameworks/WEBHOOKS.md) for full event types.
|
||
|
||
---
|
||
|
||
## Skills Framework
|
||
|
||
Manage Skills (the agentic extensions framework).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ------------------------ | --------------------------------------------------------------------------------------- |
|
||
| GET | `/api/skills` | List all installed skills (built-in + custom) |
|
||
| POST | `/api/skills/install` | Install a skill from a local path or URL |
|
||
| DELETE | `/api/skills/[id]` | Uninstall a skill |
|
||
| PUT | `/api/skills/[id]` | Enable or disable a skill — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
|
||
| POST | `/api/skills/executions` | Execute a skill — body: `{skillName, apiKeyId, input?, sessionId?}` |
|
||
| GET | `/api/skills/executions` | List execution history for all skills (filter by `?apiKeyId=`) |
|
||
|
||
**Auth:** Requires management session or management-scoped API key.
|
||
|
||
See [Skills Framework](../frameworks/SKILLS.md) for full details.
|
||
|
||
---
|
||
|
||
## Plugins
|
||
|
||
Manage OmniRoute plugins (third-party extensions).
|
||
|
||
| Method | Path | Description |
|
||
| ------ | -------------------------------- | ----------------------------------------- |
|
||
| GET | `/api/plugins` | List installed plugins |
|
||
| POST | `/api/plugins/install` | Install a plugin from a local path or URL |
|
||
| DELETE | `/api/plugins/[name]` | Uninstall a plugin |
|
||
| POST | `/api/plugins/[name]/activate` | Activate a plugin |
|
||
| POST | `/api/plugins/[name]/deactivate` | Deactivate a plugin |
|
||
| GET | `/api/plugins/[name]/config` | Get plugin configuration |
|
||
| PUT | `/api/plugins/[name]/config` | Update plugin configuration |
|
||
|
||
**Auth:** Requires management session.
|
||
|
||
See [Plugins Framework](../frameworks/PLUGIN_SDK.md) for full details.
|
||
|
||
---
|
||
|
||
## Shadow Routing
|
||
|
||
Shadow / A-B comparison of providers is **not a standalone REST surface** — it is configured through combo routing (see [Auto-Combo](../routing/AUTO-COMBO.md)). Per-combo comparison metrics are served by `GET /api/combos/metrics`.
|
||
|
||
---
|
||
|
||
## Guardrails
|
||
|
||
Inspect the runtime guardrails (PII detection, prompt injection detection, vision bridging). Guardrails run on every request; per-call opt-out is via the `x-omniroute-disabled-guardrails` request header — there is no persisted enable/disable surface.
|
||
|
||
| Method | Path | Description |
|
||
| ------ | ---------------------- | ---------------------------------------------------------------------------------------- |
|
||
| GET | `/api/guardrails` | List the registered guardrails and their status (name / enabled / priority) |
|
||
| POST | `/api/guardrails/test` | Dry-run the pre-call pipeline over a sample input — body: `{input, disabledGuardrails?}` |
|
||
|
||
**Auth:** Requires management session.
|
||
|
||
See [Security > Guardrails](../security/GUARDRAILS.md) for full details.
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## Authentication
|
||
|
||
- Dashboard routes (`/dashboard/*`) use `auth_token` cookie
|
||
- Login uses saved password hash; fallback to `INITIAL_PASSWORD`
|
||
- `requireLogin` toggleable via `/api/settings/require-login`
|
||
- `/v1/*` routes optionally require Bearer API key when `REQUIRE_API_KEY=true`
|
||
|
||
> **Breaking change (v3.8.0)** — `/api/v1/agents/tasks/*` and the cooldown management endpoints now require **management auth** (dashboard `auth_token` cookie or a management-scoped API key). Clients that previously called these routes unauthenticated will receive `401 Unauthorized`. See commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
|