mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-20 22:22:57 +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>
1338 lines
78 KiB
Markdown
1338 lines
78 KiB
Markdown
---
|
||
title: "API Reference"
|
||
version: 3.8.40
|
||
lastUpdated: 2026-06-28
|
||
---
|
||
|
||
# API 参考
|
||
|
||
🌐 **Languages:** 🇺🇸 [English](../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../../pt-BR/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../../es/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../../fr/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../../it/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../../ru/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../../zh-CN/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../../de/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../../in/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../../th/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../../uk-UA/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../../ar/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../../ja/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../../vi/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../../bg/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../../da/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../../fi/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../../he/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../../hu/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../../id/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../../ko/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../../ms/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../../nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../../no/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../../pt/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../../ro/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../../pl/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../../sk/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../../sv/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../../phi/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../../cs/docs/reference/API_REFERENCE.md)
|
||
|
||
OmniRoute 所有 API 端点的完整参考。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [Chat Completions](#chat-completions)
|
||
- [Embeddings](#embeddings)
|
||
- [图像生成](#图像生成)
|
||
- [模型列表](#模型列表)
|
||
- [兼容性端点](#兼容性端点)
|
||
- [Files API](#files-api)
|
||
- [Batches API](#batches-api)
|
||
- [Search API](#search-api)
|
||
- [WebSocket 流式传输](#websocket-流式传输)
|
||
- [配额与问题报告](#配额与问题报告)
|
||
- [语义缓存](#语义缓存)
|
||
- [Dashboard 与管理](#dashboard-与管理)
|
||
- [Combo 管理](#combo-管理)
|
||
- [Webhooks](#webhooks)
|
||
- [注册 Key（自动管理）](#注册-key自动管理)
|
||
- [Agents 协议](#agents-协议)
|
||
- [管理代理](#管理代理)
|
||
- [容灾（扩展）](#容灾扩展)
|
||
- [Skills](#skills)
|
||
- [Memory](#memory)
|
||
- [MCP Server](#mcp-server)
|
||
- [A2A Server](#a2a-server)
|
||
- [Cloud、评估与诊断](#cloud评估与诊断)
|
||
- [请求处理](#请求处理)
|
||
- [认证](#认证)
|
||
|
||
---
|
||
|
||
## 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
|
||
}
|
||
```
|
||
|
||
### 自定义请求头
|
||
|
||
| 请求头 | 方向 | 说明 |
|
||
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `X-OmniRoute-No-Cache` | 请求 | 设为 `true` 以绕过缓存 |
|
||
| `x-omniroute-no-memory` | 请求 | 设为 `true` 以跳过本请求的记忆 + 技能注入（与 no-cache 镜像；避免每次调用的 Token/成本开销） |
|
||
| `X-OmniRoute-Progress` | 请求 | 设为 `true` 以接收进度事件 |
|
||
| `X-Session-Id` | 请求 | 粘性会话 Key，用于外部会话绑定 |
|
||
| `x_session_id` | 请求 | 下划线变体同样接受（直接 HTTP） |
|
||
| `Idempotency-Key` | 请求 | 去重 Key（5 秒窗口） |
|
||
| `X-Request-Id` | 请求 | 备用去重 Key |
|
||
| `X-OmniRoute-Cache` | 响应 | 缓存 `HIT` 或 `MISS`（非流式） |
|
||
| `X-OmniRoute-Idempotent` | 响应 | 去重命中时为 `true` |
|
||
| `X-OmniRoute-Progress` | 响应 | 进度跟踪开启时为 `enabled` |
|
||
| `X-OmniRoute-Session-Id` | 响应 | OmniRoute 使用的有效会话 ID |
|
||
| `X-OmniRoute-Request-Id` | 响应 | 请求关联 ID（已知时） |
|
||
| `X-OmniRoute-Version` | 响应 | OmniRoute 构建版本号（始终返回） |
|
||
| `X-OmniRoute-Cost-Saved` | 响应 | 缓存命中时节省的 USD 金额（仅缓存命中时） |
|
||
|
||
> Nginx 提示：如果依赖下划线请求头（如 `x_session_id`），请启用 `underscores_in_headers on;`。
|
||
|
||
> **成本遥测请求头：** 非流式成功响应还会携带 `X-OmniRoute-*` 成本遥测系列 — `X-OmniRoute-Response-Cost`（USD，固定 10 位小数；免费/无定价时为 `0.0000000000`）、`X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`、`X-OmniRoute-Model`、`X-OmniRoute-Provider`、`X-OmniRoute-Latency-Ms`、`X-OmniRoute-Cache-Hit` 以及 `X-OmniRoute-Fallback-Attempts`（仅在 >0 时返回），外加 `X-OmniRoute-Request-Id` 和 `X-OmniRoute-Version`。这些请求头由 chat completions、`/v1/responses`、`/v1/messages` **以及媒体端点**发出 — `/v1/embeddings`、`/v1/images/generations`、`/v1/audio/speech`、`/v1/audio/transcriptions`、`/v1/rerank`、`/v1/videos/generations`、`/v1/music/generations` 和 `/v1/moderations`（成本始终为 `0`）。媒体成本按模态计算（按图片、按秒、按字符、按搜索单元），仅在定价可用时计算，否则为 `0`（fail-open）。
|
||
|
||
> **缓存命中成本语义：** 语义缓存命中时（`X-OmniRoute-Cache-Hit: true`），不会发起上游调用，因此 `X-OmniRoute-Response-Cost` 为 `0.0000000000`（即命中的**增量**成本）。原始/本应产生的成本单独在 `X-OmniRoute-Cost-Saved` 中报告。计费消费者应累加 `X-OmniRoute-Response-Cost`（命中成本为零）；缓存分析可聚合 `X-OmniRoute-Cost-Saved`。
|
||
|
||
### `x-omniroute-compression`
|
||
|
||
按请求覆盖压缩计划。优先级最高 — 高于路由 Combo 覆盖、活动配置、自动触发和面板 Default。取值：
|
||
|
||
| 值 | 效果 |
|
||
| ------------- | -------------------------------------------------------- |
|
||
| `off` | 本请求不压缩。 |
|
||
| `default` | 面板生成的 Default 配置（忽略活动配置）。 |
|
||
| `engine:<id>` | 启用时的单个引擎，如 `engine:rtk`。 |
|
||
| `<combo>` | 按名称匹配的命名 Combo（不区分大小写），其次按 id 匹配。 |
|
||
|
||
说明：
|
||
|
||
- 未知值将被忽略（绝不会因此拒绝请求）；解析回退到常规优先级顺序。
|
||
- 若多个 Combo 共享同一名称，请传入 Combo **id** 以获得确定性匹配。
|
||
- 名称为 `off` 或 `default` 的 Combo 无法按名称选择（这些关键词优先解释）；请通过 id 引用此类 Combo。
|
||
- 主压缩开关是硬门控：全局禁用压缩时，本请求头无法启用。
|
||
|
||
应用的计划会回显在响应请求头中：
|
||
|
||
```
|
||
X-OmniRoute-Compression: <mode>; source=<source>
|
||
```
|
||
|
||
其中 `<source>` 为以下之一：`request-header`、`routing-override`、`active-profile`、`auto-trigger`、`default` 或 `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"
|
||
}
|
||
```
|
||
|
||
可用服务商：Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、**OpenRouter**、**GitHub Models**。
|
||
|
||
```bash
|
||
# 列出所有嵌入模型
|
||
GET /v1/embeddings
|
||
```
|
||
|
||
---
|
||
|
||
## 图像生成
|
||
|
||
```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"
|
||
}
|
||
```
|
||
|
||
可用服务商：OpenAI (GPT Image 2)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI、Nebius (FLUX)、Hyperbolic、NanoBanana、**OpenRouter**、SD WebUI (本地)、ComfyUI (本地)。
|
||
|
||
```bash
|
||
# 列出所有图像模型
|
||
GET /v1/images/generations
|
||
```
|
||
|
||
---
|
||
|
||
## 模型列表
|
||
|
||
```bash
|
||
GET /v1/models
|
||
Authorization: Bearer your-api-key
|
||
|
||
→ 以 OpenAI 格式返回所有 chat、embedding 和 image 模型 + Combo
|
||
```
|
||
|
||
### No-thinking 模型变体
|
||
|
||
对于支持 thinking 的 Claude 模型，`/v1/models` 还会列出一个 **no-thinking** 变体，其 id 前缀为 `claude-3-omniroute-no-thinking/`：
|
||
|
||
```
|
||
claude-3-omniroute-no-thinking/<provider>/<model>
|
||
```
|
||
|
||
选择此 id（例如在始终附加 `thinking` 块的 Claude Code 配置中）会解析回真实的 `<provider>/<model>`，并抑制推理功能 — 在 `/v1/messages` 路径上使用 `thinking:{type:"disabled"}`，或在 `/v1/chat/completions` 路径上丢弃 `reasoning`/`reasoning_effort` 字段。此变体仅列出给支持 thinking **且**接受 `disabled` 的 Claude 系列模型（因此，仅支持 adaptive 模式且拒绝 `disabled` 的模型不会被列出）。管理员可通过 `ModelSpec.noThinkingAlias` 按模型强制开启或关闭此变体。
|
||
|
||
---
|
||
|
||
## 兼容性端点
|
||
|
||
| 方法 | 路径 | 格式 |
|
||
| ----- | ------------------------------------------- | -------------------------------- |
|
||
| 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 (编辑/修补) |
|
||
| POST | `/v1/videos/generations` | OpenAI 风格视频生成 |
|
||
| POST | `/v1/music/generations` | OpenAI 风格音乐生成 |
|
||
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
|
||
| POST | `/v1/audio/speech` | OpenAI TTS (返回音频内容) |
|
||
| POST | `/v1/rerank` | Cohere/Voyage 风格重排序 |
|
||
| 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 目录别名 |
|
||
| GET | `/api/v1/vscode/{token}/models` | OpenAI 模型别名 |
|
||
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI Token 化别名 |
|
||
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses Token 化别名 |
|
||
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama Token 化别名 |
|
||
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama 标签 Token 化别名 |
|
||
|
||
所有 POST 路由遵循同一模式：`Bearer your-api-key` + 经 Zod 校验的 JSON 请求体（`v1RerankSchema`、`v1ModerationSchema`、`v1AudioSpeechSchema` 等，参见 `src/shared/validation/schemas.ts`）。Schema 校验失败返回 4xx。
|
||
|
||
对于无法附加 `Authorization: Bearer ...` 的客户端，OmniRoute 也接受通过 URL 传入 API Key：查询字符串兼容方式（`?token=...`、`?apiKey=...`、`?api_key=...`、`?key=...`）或下文介绍的专用 `/api/v1/vscode/{token}/...` 端点。
|
||
|
||
```bash
|
||
# 重排序
|
||
POST /v1/rerank { "model": "cohere/rerank-3", "query": "...", "documents": ["..."] }
|
||
|
||
# 内容审核
|
||
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
|
||
|
||
# TTS — 返回 audio/mpeg（或指定格式）内容
|
||
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
|
||
|
||
# 图像编辑 (multipart)
|
||
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
|
||
|
||
# 视频 / 音乐生成 (带服务商前缀的模型 id)
|
||
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
|
||
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
|
||
```
|
||
|
||
### 专用服务商路由
|
||
|
||
```bash
|
||
POST /v1/providers/{provider}/chat/completions
|
||
POST /v1/providers/{provider}/embeddings
|
||
POST /v1/providers/{provider}/images/generations
|
||
```
|
||
|
||
服务商前缀缺少时会自动添加。模型不匹配时返回 `400`。
|
||
|
||
---
|
||
|
||
## Files API
|
||
|
||
OpenAI 兼容的文件端点，用于批量输入/输出和按用途上传文件。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/files` | 上传文件（multipart: `file`、`purpose`、`expires_after[anchor]`、`expires_after[seconds]`）— 最大 512 MiB |
|
||
| GET | `/v1/files` | 列出当前认证 API Key 下的文件 |
|
||
| GET | `/v1/files/[id]` | 查询文件元数据 |
|
||
| DELETE | `/v1/files/[id]` | 删除文件 |
|
||
| GET | `/v1/files/[id]/content` | 流式返回原始文件内容 |
|
||
|
||
**认证：** Bearer API Key — 文件通过 `getApiKeyRequestScope` 按 API Key 隔离。
|
||
|
||
---
|
||
|
||
## Batches API
|
||
|
||
OpenAI 兼容的批量处理。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | --------------------------- | ------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/batches` | 创建批次 — 请求体经 `v1BatchCreateSchema` 校验（`input_file_id`、`endpoint`、`completion_window`） |
|
||
| GET | `/v1/batches` | 列出批次 |
|
||
| GET | `/v1/batches/[id]` | 查询批次状态 + `request_counts` |
|
||
| DELETE | `/v1/batches/[id]` | 删除已完成/已失败的批次 |
|
||
| POST | `/v1/batches/[id]/cancel` | 取消进行中的批次 |
|
||
|
||
**认证：** Bearer API Key。批次按 API Key 隔离。
|
||
|
||
---
|
||
|
||
## Search API
|
||
|
||
Web/搜索服务商抽象层（Tavily、Brave、Exa、Serper 等）。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ------------------------ | ------------------------------------------------------------------------------ |
|
||
| GET | `/v1/search` | 列出已配置的搜索服务商 + 能力信息 |
|
||
| POST | `/v1/search` | 执行搜索查询 — 请求体经 `v1SearchSchema` 校验，支持缓存/合并 |
|
||
| GET | `/v1/search/analytics` | 按服务商的命中/延迟/缓存统计数据 |
|
||
|
||
**认证：** Bearer API Key（`extractApiKey` + `isValidApiKey`）。搜索策略通过 `enforceApiKeyPolicy` 强制执行。
|
||
|
||
---
|
||
|
||
## WebSocket 流式传输
|
||
|
||
```bash
|
||
GET /v1/ws?handshake=1
|
||
```
|
||
|
||
验证 WebSocket 升级握手并返回协议示例消息（`request`、`cancel`）。实际 WS 帧由内建的 WS 服务器在 Next.js 路由表之外处理。
|
||
|
||
**认证：** 握手期间使用 Bearer API Key。
|
||
|
||
### 通过 WebSocket 的 Responses API（仅限 codex）
|
||
|
||
```bash
|
||
# 与 HTTP API 相同的主机:端口（默认 20128）；升级连接：
|
||
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
|
||
# (或： -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
|
||
|
||
# 第一帧必须是 response.create：
|
||
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
|
||
```
|
||
|
||
Responses-API-over-WebSocket 代理**仅绑定到 `codex`**（ChatGPT 后端）。它监听与 API/dashboard 相同的端口，路径包括 `/v1/responses`、`/responses` 和 `/api/v1/responses`。在收到首个 `response.create` 帧后，通过内部 `codex-responses-ws` 桥接进行认证和准备，选择一个 codex OAuth 连接，并通过 `wreq-js` 传输隧道化至 `wss://chatgpt.com/backend-api/codex/responses`。**非 codex 模型将被拒绝**（`codex_ws_provider_required`）。如需配额共享路由，使用 `model: "qtSd/<group>/codex/<model>"`。实现在 `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`。
|
||
|
||
**认证：** 握手期间使用 Bearer API Key。内建的 HTTP 服务器（`server-ws.mjs`）必须是活动入口（当 `app/server-ws.mjs` 存在时默认为此入口）。
|
||
|
||
#### 模型 id：使用裸 ChatGPT id（不用 `codex/` 前缀）
|
||
|
||
OpenAI **Codex CLI** 在 `supports_websockets = true` 时会在客户端侧校验模型名称，并**拒绝带服务商前缀的 id**，如 `codex/gpt-5.5`（`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`）。请发送**裸** id（如 `gpt-5.5`）。OmniRoute 的桥接仅限 codex，因此会通过 `resolveCodexWsModelInfo` 将裸 id 重新解析为 codex 模型后隧道化到上游 — 尽管裸的 `gpt-5.5` 在 HTTP 下会路由到其他服务商。
|
||
|
||
#### 配置 OpenAI Codex CLI
|
||
|
||
通过在 `~/.codex/config.toml` 中添加支持 WebSocket 的自定义服务商，将 Codex CLI 指向 OmniRoute（使用单独的 `CODEX_HOME` 以避免覆盖已有配置）：
|
||
|
||
```toml
|
||
model = "gpt-5.5" # 裸 id — 不要用 "codex/gpt-5.5"
|
||
model_provider = "omniroute"
|
||
|
||
[model_providers.omniroute]
|
||
name = "OmniRoute (WS)"
|
||
base_url = "http://localhost:20128/v1" # 不要加尾部斜杠；WS URL 由此派生（生产环境使用 https/wss）
|
||
wire_api = "responses" # 自 2026 年 2 月起仅支持该值
|
||
supports_websockets = true # 启用 Responses-over-WS 传输
|
||
env_key = "OMNIROUTE_API_KEY" # 持有 OmniRoute API Key（Bearer）
|
||
```
|
||
|
||
```bash
|
||
export OMNIROUTE_API_KEY=sk-... # 一个 OmniRoute API Key（若 REQUIRE_API_KEY=false 则任意 Key）
|
||
codex exec "Responda apenas: PONG"
|
||
```
|
||
|
||
CLI 将 `base_url + /responses` 升级为 WebSocket，OmniRoute 将其隧道化到选定的 codex OAuth 连接。已对本地服务器完成端到端验证：ChatGPT 返回 `codex.rate_limits` + `response.created` 并流式传输补全结果。
|
||
|
||
---
|
||
|
||
## 配额与问题报告
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | --------------------- | ----------------------------------------------------------------------------- |
|
||
| GET | `/v1/quotas/check` | 在发放注册 Key 之前预先校验指定 `provider` + `accountId` 的配额 |
|
||
| POST | `/v1/issues/report` | 向 GitHub 报告配额/Key 发放失败（需要 `GITHUB_ISSUES_REPO` + Token） |
|
||
|
||
**认证：** Bearer API Key（`isAuthenticated`）。
|
||
|
||
---
|
||
|
||
## 语义缓存
|
||
|
||
```bash
|
||
# 获取缓存统计
|
||
GET /api/cache/stats
|
||
|
||
# 清空所有缓存
|
||
DELETE /api/cache/stats
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"semanticCache": {
|
||
"memorySize": 42,
|
||
"memoryMaxSize": 500,
|
||
"dbSize": 128,
|
||
"hitRate": 0.65
|
||
},
|
||
"idempotency": {
|
||
"activeKeys": 3,
|
||
"windowMs": 5000
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Dashboard 与管理
|
||
|
||
### 认证
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ------------------------------- | ------- | ------------------ |
|
||
| `/api/auth/login` | POST | 登录 |
|
||
| `/api/auth/logout` | POST | 登出 |
|
||
| `/api/settings/require-login` | GET/PUT | 切换登录要求 |
|
||
|
||
### 服务商管理
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------------- | --------------------- | ------------------------------------ |
|
||
| `/api/providers` | GET/POST | 列出 / 创建服务商 |
|
||
| `/api/providers/[id]` | GET/PUT/DELETE | 管理服务商 |
|
||
| `/api/providers/[id]/test` | POST | 测试服务商连接 |
|
||
| `/api/providers/[id]/models` | GET | 列出服务商模型 |
|
||
| `/api/providers/validate` | POST | 校验服务商配置 |
|
||
| `/api/provider-nodes*` | Various | 服务商节点管理 |
|
||
| `/api/provider-models` | GET/POST/PATCH/DELETE | 自定义模型（添加、更新、隐藏/显示、删除） |
|
||
|
||
### OAuth 流程
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------------------- | ------- | ---------------------- |
|
||
| `/api/oauth/[provider]/[action]` | Various | 服务商特定的 OAuth |
|
||
|
||
### 路由与配置
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ------------------- | --------- | -------------------------------- |
|
||
| `/api/models/alias` | GET/POST | 模型别名 |
|
||
| `/api/models/catalog` | GET | 按服务商+类型列出所有模型 |
|
||
| `/api/combos*` | Various | Combo 管理 |
|
||
| `/api/keys*` | Various | API Key 管理 |
|
||
| `/api/pricing` | GET | 模型定价 |
|
||
|
||
### 用量与分析
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| --------------------------- | --------------- | -------------------------------- |
|
||
| `/api/usage/history` | GET | 用量历史 |
|
||
| `/api/usage/logs` | GET | 用量日志 |
|
||
| `/api/usage/request-logs` | GET | 请求级日志 |
|
||
| `/api/usage/[connectionId]` | GET | 按连接的用量 |
|
||
| `/api/usage/token-limits` | GET/POST/DELETE | 按 API Key 的 Token 额度预算 |
|
||
|
||
### 设置
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ------------------------------------- | ------------- | -------------------------------------- |
|
||
| `/api/settings` | GET/PUT/PATCH | 通用设置 |
|
||
| `/api/settings/proxy` | GET/PUT | 网络代理配置 |
|
||
| `/api/settings/proxy/test` | POST | 测试代理连接 |
|
||
| `/api/settings/ip-filter` | GET/PUT | IP 允许/阻止列表 |
|
||
| `/api/settings/thinking-budget` | GET/PUT | 推理 Token 预算 |
|
||
| `/api/settings/system-prompt` | GET/PUT | 全局系统提示 |
|
||
| `/api/settings/compression` | GET/PUT | 全局压缩配置 |
|
||
| `/api/settings/purge-request-history` | POST | 清除请求日志行及本地调用日志产物 |
|
||
|
||
### 上下文与压缩
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------------------------- | -------------- | ----------------------------------------------------------------------- |
|
||
| `/api/compression/preview` | POST | 预览 off/lite/standard/aggressive/ultra/RTK/stacked 压缩效果 |
|
||
| `/api/compression/language-packs` | GET | 列出可用的 Caveman 语言包 |
|
||
| `/api/compression/rules` | GET | 列出 Caveman 规则元数据 |
|
||
| `/api/context/caveman/config` | GET/PUT | Caveman 特定设置别名 |
|
||
| `/api/context/rtk/config` | GET/PUT | RTK 特定设置，包括自定义过滤器和原始输出保留 |
|
||
| `/api/context/rtk/filters` | GET | RTK 过滤器目录和自定义过滤器诊断 |
|
||
| `/api/context/rtk/test` | POST | 对文本载荷运行 RTK 预览/测试 |
|
||
| `/api/context/rtk/raw-output/[id]` | GET | 按指针 id 读取保存的脱敏原始输出 |
|
||
| `/api/context/combos` | GET/POST | 压缩 Combo 列表/创建 |
|
||
| `/api/context/combos/[id]` | GET/PUT/DELETE | 压缩 Combo 详情/更新/删除 |
|
||
| `/api/context/combos/[id]/assignments` | GET/PUT | 将压缩 Combo 分配给路由 Combo |
|
||
| `/api/context/analytics` | GET | 压缩分析别名 |
|
||
|
||
### 监控
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
|
||
| `/api/sessions` | GET | 活跃会话跟踪 |
|
||
| `/api/rate-limits` | GET | 按账户的速率限制 |
|
||
| `/api/monitoring/health` | GET | 健康检查 + 服务商摘要（`catalogCount`、`configuredCount`、`activeCount`、`monitoredCount`） |
|
||
| `/api/cache/stats` | GET/DELETE | 缓存统计 / 清空 |
|
||
|
||
### 备份与导出/导入
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ----------------------------- | ---- | -------------------------------------- |
|
||
| `/api/db-backups` | GET | 列出可用的备份 |
|
||
| `/api/db-backups` | PUT | 创建手动备份 |
|
||
| `/api/db-backups` | POST | 从指定备份恢复 |
|
||
| `/api/db-backups/export` | GET | 下载数据库 .sqlite 文件 |
|
||
| `/api/db-backups/import` | POST | 上传 .sqlite 文件替换数据库 |
|
||
| `/api/db-backups/exportAll` | GET | 下载完整备份 .tar.gz 归档 |
|
||
|
||
### 云同步
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------- | ------- | ------------------ |
|
||
| `/api/sync/cloud` | Various | 云同步操作 |
|
||
| `/api/sync/initialize` | POST | 初始化同步 |
|
||
| `/api/cloud/*` | Various | 云管理 |
|
||
|
||
### 隧道
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------------- | ---- | ---------------------------------------------------------- |
|
||
| `/api/tunnels/cloudflared` | GET | 读取 Cloudflare Quick Tunnel 安装/运行状态（供 dashboard） |
|
||
| `/api/tunnels/cloudflared` | POST | 启用或禁用 Cloudflare Quick Tunnel（`action=enable/disable`）|
|
||
| `/api/tunnels/ngrok` | GET | 读取 ngrok Tunnel 运行状态（供 dashboard） |
|
||
| `/api/tunnels/ngrok` | POST | 启用或禁用 ngrok Tunnel（`action=enable/disable`） |
|
||
|
||
### CLI 工具
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ------------------------------------ | ---- | ------------------- |
|
||
| `/api/cli-tools/claude-settings` | GET | Claude CLI 状态 |
|
||
| `/api/cli-tools/codex-settings` | GET | Codex CLI 状态 |
|
||
| `/api/cli-tools/droid-settings` | GET | Droid CLI 状态 |
|
||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI 状态 |
|
||
| `/api/cli-tools/runtime/[toolId]` | GET | 通用 CLI 运行状态 |
|
||
|
||
CLI 响应包括：`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason`。
|
||
|
||
### ACP Agents
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ----------------- | ------ | -------------------------------------------------------------- |
|
||
| `/api/acp/agents` | GET | 列出所有检测到的代理（内置 + 自定义）及其状态 |
|
||
| `/api/acp/agents` | POST | 添加自定义代理或刷新检测缓存 |
|
||
| `/api/acp/agents` | DELETE | 按 `id` 查询参数删除自定义代理 |
|
||
|
||
GET 响应包含 `agents[]`（id、name、binary、version、installed、protocol、isCustom）和 `summary`（total、installed、notFound、builtIn、custom）。
|
||
|
||
### 容灾与速率限制
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------ |
|
||
| `/api/resilience` | GET/PATCH | 获取/更新请求队列、连接冷却、服务商熔断器及等待设置 |
|
||
| `/api/resilience/reset` | POST | 重置服务商熔断器 |
|
||
| `/api/resilience/model-cooldowns` | GET | 列出活跃的按(服务商, 连接, 模型)锁定的状态，按剩余时间排序 |
|
||
| `/api/resilience/model-cooldowns` | DELETE | 清除模型锁定 — 请求体 `{provider, model}` 或 `{all: true}` 以清除全部 |
|
||
| `/api/rate-limits` | GET | 按账户的速率限制状态 |
|
||
| `/api/rate-limit` | GET | 全局速率限制配置 |
|
||
|
||
> 所有四个 `/api/resilience/*` 路由都需要**管理认证**（`requireManagementAuth`）。关于服务商熔断器 vs 连接冷却 vs 模型锁定的完整说明，参阅 [容灾（扩展）](#容灾扩展)。
|
||
|
||
### Evals
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ------------ | --------- | -------------------------------- |
|
||
| `/api/evals` | GET/POST | 列出评估套件 / 运行评估 |
|
||
|
||
### Policies
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| --------------- | --------------- | -------------------- |
|
||
| `/api/policies` | GET/POST/DELETE | 管理路由策略 |
|
||
|
||
### Compliance
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ----------------------------- | ---- | -------------------------- |
|
||
| `/api/compliance/audit-log` | GET | 合规审计日志（最近 N 条） |
|
||
|
||
### v1beta（Gemini 兼容）
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| ---------------------------- | ---- | -------------------------------- |
|
||
| `/v1beta/models` | GET | 以 Gemini 格式列出模型 |
|
||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` 端点 |
|
||
|
||
这些端点镜像 Gemini 的 API 格式，供期望原生 Gemini SDK 兼容的客户端使用。
|
||
|
||
### 内部 / 系统 API
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| -------------------------- | ---- | ------------------------------------------------------ |
|
||
| `/api/init` | GET | 应用初始化检查（用于首次运行） |
|
||
| `/api/tags` | GET | Ollama 兼容的模型标签（供 Ollama 客户端） |
|
||
| `/api/restart` | POST | 触发优雅重启 |
|
||
| `/api/shutdown` | POST | 触发优雅关闭 |
|
||
| `/api/system/env/repair` | POST | 修复 OAuth 服务商环境变量 |
|
||
|
||
> **注意：** 这些端点供系统内部使用或 Ollama 客户端兼容，终端用户通常无需调用。
|
||
|
||
### OAuth 环境修复 _(v3.6.1+)_
|
||
|
||
```bash
|
||
POST /api/system/env/repair
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"provider": "claude-code"
|
||
}
|
||
```
|
||
|
||
修复特定服务商缺失或损坏的 OAuth 环境变量。返回：
|
||
|
||
```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
|
||
```
|
||
|
||
使用 Deepgram 或 AssemblyAI 转录音频文件。
|
||
|
||
**请求：**
|
||
|
||
```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"
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"text": "Hello, this is the transcribed audio content.",
|
||
"task": "transcribe",
|
||
"language": "en",
|
||
"duration": 12.5
|
||
}
|
||
```
|
||
|
||
**支持的服务商：** `deepgram/nova-3`、`assemblyai/best`。
|
||
|
||
**支持的格式：** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。
|
||
|
||
---
|
||
|
||
## Ollama 兼容性
|
||
|
||
适用于使用 Ollama API 格式的客户端：
|
||
|
||
```bash
|
||
# Chat 端点（Ollama 格式）
|
||
POST /v1/api/chat
|
||
|
||
# 模型列表（Ollama 格式）
|
||
GET /api/tags
|
||
```
|
||
|
||
请求在 Ollama 与内部格式之间自动转换。
|
||
|
||
## Token 化 VS Code / 无请求头别名
|
||
|
||
当集成无法注入 `Authorization` 请求头、需要将 API Key 嵌入 base URL 时，请使用这些别名。
|
||
|
||
```bash
|
||
# OpenAI 风格目录别名
|
||
GET /api/v1/vscode/{token}/
|
||
GET /api/v1/vscode/{token}/models
|
||
|
||
# OpenAI 风格 chat 别名
|
||
POST /api/v1/vscode/{token}/chat/completions
|
||
POST /api/v1/vscode/{token}/responses
|
||
|
||
# Ollama 风格别名
|
||
POST /api/v1/vscode/{token}/api/chat
|
||
GET /api/v1/vscode/{token}/api/tags
|
||
```
|
||
|
||
示例：
|
||
|
||
```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"}]}'
|
||
```
|
||
|
||
说明：
|
||
|
||
- Token 化别名复用与 `/v1/*` 和 `/api/tags` 相同的处理器；响应格式保持一致。
|
||
- 只要客户端支持自定义请求头，应优先使用 `Authorization: Bearer ...`。
|
||
- 基于 URL 的 Token 可能出现在反向代理日志、浏览器历史和 OmniRoute 之外的遥测中。将其作为兼容选项而不是默认的认证方式。
|
||
|
||
---
|
||
|
||
## Telemetry
|
||
|
||
```bash
|
||
# 获取延迟遥测摘要（按服务商的 p50/p95/p99）
|
||
GET /api/telemetry/summary
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
|
||
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 预算
|
||
|
||
```bash
|
||
# 获取所有 API Key 的预算状态
|
||
GET /api/usage/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 说明**（`setBudgetSchema`）：`apiKeyId` 为必填字段；`dailyLimitUsd`、`weeklyLimitUsd` 或 `monthlyLimitUsd` 中至少有一项必须大于零。可选字段：`warningThreshold`（0–1）、`resetInterval`（`daily` | `weekly` | `monthly`）、`resetTime`（`HH:MM`）。旧的 `{keyId, limit, period}` 格式将返回 `400 Bad Request`。
|
||
|
||
## Token 限制
|
||
|
||
按 API Key 的 **Token 用量**预算（与上述基于 USD 的预算不同）。在请求路径上内联执行：当某个 Key 当前窗口用量达到限制时，请求将被拒绝并返回 `429 Too Many Requests`。限制可作用于特定 `model`、`provider` 或按 Key 全局（`global`）应用；当多个限制同时匹配时，取最严格的一个。
|
||
|
||
```bash
|
||
# 列出某个 Key 的 Token 限制（含实时窗口用量）
|
||
GET /api/usage/token-limits?apiKeyId=key-123
|
||
|
||
# 创建或更新 Token 限制
|
||
POST /api/usage/token-limits
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"apiKeyId": "key-123",
|
||
"scopeType": "model",
|
||
"scopeValue": "openai/gpt-4o",
|
||
"tokenLimit": 1000000,
|
||
"resetInterval": "monthly",
|
||
"enabled": true
|
||
}
|
||
|
||
# 按 id 删除 Token 限制
|
||
DELETE /api/usage/token-limits?id=tl-abc
|
||
```
|
||
|
||
> **Schema 说明**（`setTokenLimitSchema`）：`apiKeyId` 和 `scopeType`（`model` | `provider` | `global`）为必填字段。`scopeValue` 在 `scopeType` 非 `global` 时为必填（如 `model` 作用域填模型 id，`provider` 作用域填服务商 id）。`tokenLimit` 必须为正整数（从字符串强制转换）。可选字段：`id`（省略为创建，提供为更新）、`resetInterval`（`daily` | `weekly` | `monthly`，默认 `monthly`）、`resetTime`（`HH:MM`）、`enabled`（默认 `true`）。`GET` 响应会为每个限制附加 `tokensUsed`、`remaining`、`windowStart`、`periodStartAt` 和 `nextResetAt`。此为管理级端点（认证由 authz 管道集中执行）。
|
||
|
||
## 请求处理
|
||
|
||
1. 客户端向 `/v1/*` 发送请求
|
||
2. 路由处理器调用 `handleChat`、`handleEmbedding`、`handleAudioTranscription` 或 `handleImageGeneration`
|
||
3. 解析模型（直接指定 服务商/模型 或别名/Combo）
|
||
4. 从本地数据库选择凭证，并过滤账户可用性
|
||
5. 对于 chat：`handleChatCore` 检查语义/签名缓存并解析 Combo 压缩设置
|
||
6. 启用时，在服务商转换前执行主动压缩（`lite`、Caveman、RTK 或 stacked）
|
||
7. 服务商执行器发送上游请求
|
||
8. 响应转换回客户端格式（chat）或原样返回（embeddings/images/audio）
|
||
9. 记录用量、压缩分析和请求日志
|
||
10. 错误时按 Combo 规则应用容灾
|
||
|
||
完整架构参考：[`ARCHITECTURE.md`](../../architecture/ARCHITECTURE.md)
|
||
|
||
---
|
||
|
||
## Combo 管理
|
||
|
||
更高层的路由 Combo（已在 `/api/combos*` 下概述）也可以从模型 id 模式进行 1:1 映射，从而将 OpenAI 风格的模型 id 透明重定向到 Combo。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ---------------------------------- | ---------------------------------------------------------------------------- |
|
||
| GET | `/api/model-combo-mappings` | 列出所有模型→Combo 映射 |
|
||
| POST | `/api/model-combo-mappings` | 创建映射 — 请求体：`{pattern, comboId, priority?, enabled?, description?}` |
|
||
| GET | `/api/model-combo-mappings/[id]` | 查询单个映射 |
|
||
| PUT | `/api/model-combo-mappings/[id]` | 更新已有映射的字段 |
|
||
| DELETE | `/api/model-combo-mappings/[id]` | 删除映射 |
|
||
|
||
**认证：** 管理会话/API Key（`requireManagementAuth`）。
|
||
|
||
---
|
||
|
||
## Webhooks
|
||
|
||
OmniRoute 事件（请求完成、配额耗尽、Key 轮换等）的出站 Webhook 订阅。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | --------------------------- | ------------------------------------------------------------- |
|
||
| GET | `/api/webhooks` | 列出 Webhook（secret 脱敏显示为 `<prefix>...`） |
|
||
| POST | `/api/webhooks` | 创建 Webhook — 请求体：`{url, events?: ["*"], secret?, description?}` |
|
||
| GET | `/api/webhooks/[id]` | 查询 Webhook |
|
||
| PUT | `/api/webhooks/[id]` | 更新 url/events/secret/description |
|
||
| DELETE | `/api/webhooks/[id]` | 删除 Webhook |
|
||
| POST | `/api/webhooks/[id]/test` | 向 Webhook URL 发送测试载荷并返回投递状态 |
|
||
|
||
**认证：** 管理会话/API Key（`requireManagementAuth`）。
|
||
|
||
---
|
||
|
||
## 注册 Key（自动管理）
|
||
|
||
由自动 Key 管理子系统使用，用于向支持的服务商/账户发放和轮换 API Key，并设有每日/每小时配额。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/v1/registered-keys` | 列出注册 Key（仅显示脱敏前缀） |
|
||
| POST | `/api/v1/registered-keys` | 发放新的注册 Key — 请求体：`{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`。**仅返回一次**原始 Key。配额拒绝时返回 `429`。 |
|
||
| GET | `/api/v1/registered-keys/[id]` | 查询注册 Key 的元数据（不含原始密钥） |
|
||
| DELETE | `/api/v1/registered-keys/[id]` | 吊销注册 Key |
|
||
| POST | `/api/v1/registered-keys/[id]/revoke` | 显式吊销端点（与 DELETE 效果相同） |
|
||
|
||
**认证：** Bearer API Key（`isAuthenticated`）。另见 `/v1/quotas/check` 和 `/v1/issues/report`。
|
||
|
||
---
|
||
|
||
## Agents 协议
|
||
|
||
Cloud Agent 任务（Claude Code、Codex Cloud、OpenHands 等）代表 OmniRoute 用户远程执行。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/v1/agents/tasks` | 列出任务 — 可选 `?provider=`、`?status=`、`?limit=`（1–500，默认 50） |
|
||
| POST | `/api/v1/agents/tasks` | 创建任务 — 请求体经 `CreateCloudAgentTaskSchema` 校验（`providerId`、`prompt`、`source`、`options?`）。返回 `201` 和任务信封 |
|
||
| DELETE | `/api/v1/agents/tasks?id=...` | 删除任务 |
|
||
| GET | `/api/v1/agents/tasks/[id]` | 读取任务 — 当 `external_id` 已设置时，同步刷新来自上游云代理的状态 |
|
||
| POST | `/api/v1/agents/tasks/[id]` | 区分动作：`{action: "approve"}`、`{action: "message", message}` 或 `{action: "cancel"}` |
|
||
| DELETE | `/api/v1/agents/tasks/[id]` | 按 id 删除特定任务 |
|
||
|
||
> **认证：** 所有方法都需要管理认证（`requireCloudAgentManagementAuth`）。v3.8.0 之前这些端点未做认证 — 参见 commit `588a0333` 了解重大变更。
|
||
|
||
```bash
|
||
# 创建 Claude Code 云任务
|
||
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":"..."}}'
|
||
```
|
||
|
||
---
|
||
|
||
## 管理代理
|
||
|
||
可分配给服务商、账户或全局的出站 HTTP(S)/SOCKS 代理。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/v1/management/proxies` | 列出代理（加 `?id=` 返回单个；加 `?id=&where_used=1` 返回分配图） |
|
||
| POST | `/api/v1/management/proxies` | 创建代理 — 请求体经 `createProxyRegistrySchema` 校验 |
|
||
| PATCH | `/api/v1/management/proxies` | 更新代理 — 请求体经 `updateProxyRegistrySchema` 校验（需要 `id`） |
|
||
| DELETE | `/api/v1/management/proxies?id=...&force=1` | 删除代理（使用 `force=1` 解除分配） |
|
||
| GET | `/api/v1/management/proxies/assignments` | 列出分配 — 可按 `proxy_id`、`scope`、`scope_id` 过滤；传入 `resolve_connection_id=<id>` 解析连接的活跃代理 |
|
||
| PUT | `/api/v1/management/proxies/assignments` | 分配 — 请求体经 `proxyAssignmentSchema` 校验（`{scope, scopeId?, proxyId?}`）。清除调度器缓存 |
|
||
| PUT | `/api/v1/management/proxies/bulk-assign` | 批量分配 — 请求体经 `bulkProxyAssignmentSchema` 校验（`{scope, scopeIds[], proxyId?}`） |
|
||
| GET | `/api/v1/management/proxies/health?hours=24` | 指定窗口内的聚合代理健康状态（成功/失败次数、延迟） |
|
||
|
||
**认证：** 所有路由均需管理会话/API Key（`requireManagementAuth`）。
|
||
|
||
> 任务描述中的 `POST /api/v1/management/proxies/[id]/assignments` 和 `POST /api/v1/management/proxies/[id]/health` 由上述扁平的 `/assignments` 和 `/health` 路由提供服务 — 代码库中不存在按 id 的子路由。
|
||
|
||
---
|
||
|
||
## 容灾（扩展）
|
||
|
||
OmniRoute 公开三个独立的临时故障机制；以下管理端点允许管理员读取和覆盖它们：
|
||
|
||
| 范围 | 状态存储 | 读取 | 重置 / 清除 |
|
||
| ------------------ | --------------------------------------------- | ----------------------------------------- | ------------------------------------------- |
|
||
| 服务商熔断器 | `domain_circuit_breakers` + 内存 | `/api/monitoring/health` | `POST /api/resilience/reset` |
|
||
| 连接冷却 | 服务商连接的 `rateLimitedUntil` | `/api/rate-limits`、`/api/providers/[id]` | （延迟自动恢复；通过服务商 PUT 清除） |
|
||
| 模型锁定 | 内存中的模型可用性注册表 | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
|
||
|
||
`PATCH /api/resilience` 通过 `providerBreaker.oauth` 和 `providerBreaker.apikey` 接受服务商熔断器覆盖。每种配置支持 `degradationThreshold`、`failureThreshold` 和 `resetTimeoutMs`；相同字段在 Dashboard → Settings → Resilience 中可见。
|
||
|
||
```bash
|
||
# 清除单个模型锁定
|
||
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"}'
|
||
|
||
# 清除所有锁定
|
||
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
|
||
-H "Cookie: auth_token=..." \
|
||
-d '{"all":true}'
|
||
```
|
||
|
||
完整概念参考和熔断器默认值：参见 [`CLAUDE.md`](../../../CLAUDE.md) → "Resilience Runtime State"。
|
||
|
||
---
|
||
|
||
## Skills
|
||
|
||
用于通过自定义可执行处理器扩展 OmniRoute 的技能框架，以及市场集成。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/skills` | 列出已安装的技能 — 可按 `?q=`、`?mode=on\|off\|auto`、`?source=skillsmp\|skillssh\|local` 过滤，支持分页 |
|
||
| GET | `/api/skills/[id]` | 查询单个技能 |
|
||
| PUT | `/api/skills/[id]` | 更新技能（name、description、mode、schema、handler、tags） |
|
||
| DELETE | `/api/skills/[id]` | 卸载技能 |
|
||
| POST | `/api/skills/install` | 从原始清单安装技能 — 请求体：`{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
|
||
| GET | `/api/skills/executions` | 列出最近的技能执行记录（审计追踪，含 inputs/outputs/duration） |
|
||
| GET | `/api/skills/marketplace?q=...` | 从 SkillsMP 市场搜索/热门列表（需要 `skillsmpApiKey` 设置） |
|
||
| POST | `/api/skills/marketplace/install` | 从 SkillsMP 按 id 安装技能 |
|
||
| GET | `/api/skills/skillssh?q=&limit=` | 搜索 skills.sh 注册表 |
|
||
| POST | `/api/skills/skillssh/install` | 从 skills.sh 按 id 安装技能 |
|
||
|
||
**认证：** 管理会话/API Key。市场搜索路由接受管理认证或 Bearer API Key（`isAuthenticated`）。
|
||
|
||
---
|
||
|
||
## Memory
|
||
|
||
持久化的会话/事实记忆存储，按 API Key / 会话隔离。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/memory` | 列出记忆 — `?apiKeyId=`、`?type=`、`?sessionId=`、`?q=`，支持 `offset/limit` 或 `page/limit` 分页 |
|
||
| POST | `/api/memory` | 创建记忆 — 请求体经 Zod 校验：`{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
|
||
| GET | `/api/memory/[id]` | 查询单个记忆 |
|
||
| DELETE | `/api/memory/[id]` | 删除记忆 |
|
||
| GET | `/api/memory/health` | 记忆子系统健康状态（数据库连接、embeddings 后端、向量索引状态） |
|
||
|
||
**认证：** 管理会话/API Key（`requireManagementAuth`）。`type` 枚举：`FACTUAL`、`EPISODIC`、`SEMANTIC`、`PROCEDURAL`（参见 `src/lib/memory/types.ts` 中的 `MemoryType`）。
|
||
|
||
---
|
||
|
||
## MCP Server
|
||
|
||
OmniRoute 内置一个 Model Context Protocol 服务器，支持 3 种传输方式（stdio、SSE、streamable-http）及权限域划分的工具。以下 dashboard 端点用于读取状态/审计数据并代理 HTTP 传输。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/mcp/status` | 心跳、传输方式、在线状态、上次调用、Top 工具、24 小时成功率 |
|
||
| GET | `/api/mcp/tools` | MCP 工具列表，含 `name`、`description`、`scopes`、`phase`、`auditLevel`、`sourceEndpoints` |
|
||
| GET | `/api/mcp/sse` | 打开 SSE 传输的 SSE 流（MCP 禁用或传输方式不匹配时返回 `503`） |
|
||
| POST | `/api/mcp/sse` | 在 SSE 传输上发送 JSON-RPC 帧 |
|
||
| GET | `/api/mcp/stream` | 打开 Streamable HTTP 传输的 SSE 侧（服务端发起的消息） |
|
||
| POST | `/api/mcp/stream` | 在 Streamable HTTP 传输上发送 JSON-RPC 帧 |
|
||
| DELETE | `/api/mcp/stream` | 结束 Streamable HTTP 会话 |
|
||
| GET | `/api/mcp/audit` | 查询审计日志 — `?limit=`、`?offset=`、`?tool=`、`?success=true\|false`、`?apiKeyId=` |
|
||
| GET | `/api/mcp/audit/stats` | 聚合审计统计（总数、成功率、平均耗时、Top 工具） |
|
||
|
||
**认证：** `sse`/`stream` 传输遵循 MCP 特定的认证面（Bearer API Key 需包含 `mcp` 权限域）；`status`/`tools`/`audit*` 路由可从 dashboard 读取（无需额外认证，只需能访问 dashboard 主机即可）。
|
||
|
||
> 两种 HTTP 传输均受 `settings.mcpEnabled` 和 `settings.mcpTransport` 限制 — 传输方式不匹配返回 `400`，MCP 禁用状态返回 `503`。
|
||
|
||
---
|
||
|
||
## A2A Server
|
||
|
||
OmniRoute 暴露一个 A2A（Agent-to-Agent）JSON-RPC 2.0 端点，并提供 REST 包装以供检查/dashboard 使用。
|
||
|
||
### JSON-RPC
|
||
|
||
```bash
|
||
POST /a2a
|
||
Authorization: Bearer your-api-key # 可选，除非设置了 OMNIROUTE_API_KEY
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "message/send",
|
||
"params": {
|
||
"skill": "smart-routing",
|
||
"messages": [{"role": "user", "content": "Route this coding task"}]
|
||
}
|
||
}
|
||
```
|
||
|
||
支持的方法（均受 `settings.a2aEnabled` 限制）：
|
||
|
||
| 方法 | 说明 |
|
||
| ---------------- | ---------------------------------------------------------- |
|
||
| `message/send` | 同步技能执行；返回 `{task, artifacts, metadata}` |
|
||
| `message/stream` | 相同技能集的流式 SSE 执行 |
|
||
| `tasks/get` | 按 `taskId` 获取任务 |
|
||
| `tasks/cancel` | 按 `taskId` 取消任务 |
|
||
|
||
内置技能：`smart-routing`、`quota-management`、`provider-discovery`、`cost-analysis`、`health-report`。
|
||
|
||
### Agent Card
|
||
|
||
```bash
|
||
GET /.well-known/agent.json
|
||
```
|
||
|
||
返回公开的 A2A agent card（名称、描述、能力、技能目录、认证方案）— 公开缓存 1 小时。无需认证。
|
||
|
||
### REST 辅助方法
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/a2a/status` | A2A 启用状态 + 任务统计 + 缓存的 agent card 摘要 |
|
||
| GET | `/api/a2a/tasks` | 列出任务 — `?state=submitted\|working\|completed\|failed\|cancelled`、`?skill=`、`?limit=`（≤200）、`?offset=` |
|
||
| POST | `/api/a2a/tasks` | （未作为 REST 辅助方法实现 — 通过 JSON-RPC `message/send` 创建） |
|
||
| GET | `/api/a2a/tasks/[id]` | 查询单个任务 |
|
||
| POST | `/api/a2a/tasks/[id]/cancel` | 取消任务 |
|
||
|
||
**认证：** REST 辅助方法无需管理认证即可运行（dashboard 可读）；JSON-RPC `/a2a` 路由在配置后使用 Bearer `OMNIROUTE_API_KEY`。
|
||
|
||
---
|
||
|
||
## Cloud、评估与诊断
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| POST | `/api/cloud/auth` | 验证 Bearer Key 并返回脱敏的服务商连接 + 模型别名，供云同步客户端使用 |
|
||
| POST | `/api/cloud/credentials/update` | 更新云同步服务商的加密凭证 |
|
||
| POST | `/api/cloud/model/resolve` | 使用本地路由表将逻辑模型 id 解析为具体的服务商/模型 |
|
||
| GET | `/api/cloud/models/alias` | 列出开放给云同步的模型别名 |
|
||
| GET | `/api/assess` | 读取最新诊断分类（按 服务商/模型） |
|
||
| POST | `/api/assess` | 运行诊断 — 请求体：`{scope: {type:"all"} \| {type:"provider", providerId} \| {type:"model", modelId}, trigger?}` |
|
||
| GET | `/api/evals` | 列出内置评估套件 + 最近运行记录 |
|
||
| POST | `/api/evals` | 触发评估运行 |
|
||
| POST | `/api/evals/suites` | 创建自定义评估套件 — 请求体经 `evalSuiteSaveSchema` 校验 |
|
||
| GET | `/api/evals/suites/[id]` | 查询自定义评估套件 |
|
||
|
||
**认证：** `/api/cloud/auth` 直接验证 Bearer Key；其他 `/api/cloud/*`、`/api/evals/*` 和 `/api/assess` 路由需要管理会话/API Key。`/api/assess` POST 使用 `validateBody` 和区分联合的 scope schema。
|
||
|
||
---
|
||
|
||
## ACP（Agent Client Protocol）管理
|
||
|
||
ACP 代理作为子进程运行。以下端点管理 ACP 代理检测和自定义代理注册。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/acp/agents` | 列出所有已知的 CLI 代理（内置 + 自定义），含安装状态、版本、二进制文件 |
|
||
| POST | `/api/acp/agents` | 注册自定义 ACP 代理或刷新缓存 — 请求体：`{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` 或 `{action: "refresh"}` |
|
||
| DELETE | `/api/acp/agents` | 删除自定义 ACP 代理 — 查询参数：`?id=<agentId>` |
|
||
|
||
**响应示例**（`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
|
||
}
|
||
```
|
||
|
||
**认证：** 需要管理会话（dashboard `auth_token` cookie）或管理权限域的 API Key。
|
||
|
||
完整细节参见 [ACP Framework](../frameworks/ACP.md)。
|
||
|
||
---
|
||
|
||
## 分析与可观测性
|
||
|
||
用于监控路由、压缩和服务商多样性的实时分析端点。这些端点驱动 `/dashboard/analytics/*` 页面。
|
||
|
||
### 自动路由分析
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/auto-routing` | 聚合自动路由统计：总调用次数、策略分布、层级分布、Top 服务商 |
|
||
| GET | `/api/analytics/auto-routing?days=7` | 按时间窗口统计（默认 24 小时） |
|
||
|
||
**响应示例**：
|
||
|
||
```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 }
|
||
]
|
||
}
|
||
```
|
||
|
||
### 压缩分析
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ------------------------------ | -------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/compression` | 聚合压缩统计：Token 节省量、节省百分比、模式分布、引擎用量 |
|
||
|
||
**响应示例**：
|
||
|
||
```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
|
||
}
|
||
}
|
||
```
|
||
|
||
### 服务商多样性追踪
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/diversity` | 基于 Shannon 熵的多样性跟踪：通过衡量服务商分布来防止单点故障 |
|
||
|
||
**响应示例**：
|
||
|
||
```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"]
|
||
}
|
||
```
|
||
|
||
**认证：** 需要管理会话或管理权限域的 API Key。
|
||
|
||
---
|
||
|
||
## 管理操作
|
||
|
||
管理员专属端点，用于运营管理。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | -------------------------- | --------------------------------------------------------------------------------------- |
|
||
| GET | `/api/admin/concurrency` | 读取当前并发限制（全局 + 按服务商） |
|
||
| POST | `/api/admin/concurrency` | 更新并发限制 — 请求体：`{global?: number, perProvider?: Record<string, number>}` |
|
||
|
||
**认证：** 需要含 admin 权限域的管理会话。
|
||
|
||
---
|
||
|
||
## CLI 工具管理
|
||
|
||
管理与 OmniRoute 集成的 CLI 工具（antigravity、chipotle、commandCode、devin-cli 等）。完整列表参见 [Provider Reference](./PROVIDER_REFERENCE.md)。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ----------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/cli-tools/all-statuses` | 所有 CLI 工具的状态（已安装、版本、上次检测） |
|
||
| GET | `/api/cli-tools/[id]/status` | 特定 CLI 工具的状态（id 可为：antigravity、chipotle、commandCode、devin-cli 等） |
|
||
| POST | `/api/cli-tools/apply` | 将 CLI 工具配置应用到服务商连接 |
|
||
| GET | `/api/cli-tools/backups` | 列出 CLI 工具配置备份 |
|
||
| POST | `/api/cli-tools/backups` | 创建所有 CLI 工具配置的备份 |
|
||
| POST | `/api/cli-tools/[id]/restore` | 从备份恢复 CLI 工具 |
|
||
| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM 代理状态（"antigravity-mitm" CLI 工具） |
|
||
| POST | `/api/cli-tools/antigravity-mitm/alias` | 配置 antigravity-mitm 别名 |
|
||
|
||
**认证：** 需要管理会话。
|
||
|
||
---
|
||
|
||
## Agent Skills
|
||
|
||
管理 AI 代理技能（类似 OpenAI 的自定义 GPT，但面向代理）。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------------------ | ------------------------------------------------------------------------------ |
|
||
| GET | `/api/agent-skills` | 列出所有代理技能（内置 + 自定义） |
|
||
| GET | `/api/agent-skills/[id]` | 获取特定代理技能 |
|
||
| POST | `/api/agent-skills` | 创建自定义代理技能 — 请求体：`{name, description, prompt, model?, temperature?}` |
|
||
| PUT | `/api/agent-skills/[id]` | 更新自定义代理技能 |
|
||
| DELETE | `/api/agent-skills/[id]` | 删除自定义代理技能 |
|
||
| GET | `/api/agent-skills/[id]/raw` | 获取原始提示 + 元数据（不执行） |
|
||
| POST | `/api/agent-skills/generate` | AI 从自然语言描述生成新技能 |
|
||
|
||
**认证：** 需要管理会话或管理权限域的 API Key。
|
||
|
||
---
|
||
|
||
## 缓存管理
|
||
|
||
管理语义缓存和推理缓存。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/cache` | 缓存概览：条目总数、命中率、磁盘占用 |
|
||
| GET | `/api/cache/entries` | 列出缓存条目（支持分页） |
|
||
| DELETE | `/api/cache/entries` | 删除缓存条目（按查询参数过滤） |
|
||
| GET | `/api/cache/stats` | 详细缓存统计（按服务商、按模型） |
|
||
| GET | `/api/cache/reasoning` | 推理缓存状态（用于推理回放） |
|
||
| DELETE | `/api/cache/reasoning` | 清除推理缓存 — 查询参数：`?toolCallId=<id>`（单个）或 `?provider=<p>` 或不传参数（全部） |
|
||
|
||
**认证：** 需要管理会话。
|
||
|
||
---
|
||
|
||
## 记忆系统
|
||
|
||
管理持久化记忆（FTS5 + 向量嵌入）。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ---------------------- | ------------------------------------------------------------------ |
|
||
| GET | `/api/memory` | 列出记忆条目（按作用域、类型、搜索查询过滤） |
|
||
| POST | `/api/memory` | 创建新记忆条目 — 请求体：`{scope, type, content, metadata?}` |
|
||
| GET | `/api/memory/[id]` | 获取特定记忆条目 |
|
||
| PUT | `/api/memory/[id]` | 更新记忆条目 |
|
||
| DELETE | `/api/memory/[id]` | 删除记忆条目 |
|
||
| GET | `/api/memory/search` | 搜索记忆（FTS5 + 向量） |
|
||
| POST | `/api/memory/clear` | 清除记忆条目（支持过滤器） |
|
||
| GET | `/api/memory/stats` | 记忆统计（总条目数、嵌入覆盖率等） |
|
||
|
||
**认证：** 需要管理会话或管理权限域的 API Key。
|
||
|
||
---
|
||
|
||
## Webhooks
|
||
|
||
管理事件 Webhook 订阅。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | --------------------------------- | ------------------------------------------------------------------ |
|
||
| GET | `/api/webhooks` | 列出所有 Webhook 订阅 |
|
||
| POST | `/api/webhooks` | 创建 Webhook 订阅 — 请求体：`{url, events[], secret?, active?}` |
|
||
| GET | `/api/webhooks/[id]` | 获取特定 Webhook 订阅 |
|
||
| PUT | `/api/webhooks/[id]` | 更新 Webhook 订阅 |
|
||
| DELETE | `/api/webhooks/[id]` | 删除 Webhook 订阅 |
|
||
| GET | `/api/webhooks/events` | 列出所有可用的 Webhook 事件类型 |
|
||
| GET | `/api/webhooks/[id]/deliveries` | 列出 Webhook 投递历史（成功/失败日志） |
|
||
| POST | `/api/webhooks/[id]/test` | 向 Webhook 发送测试事件 |
|
||
|
||
**认证：** 需要管理会话。
|
||
|
||
完整事件类型参见 [Webhooks Framework](../frameworks/WEBHOOKS.md)。
|
||
|
||
---
|
||
|
||
## Skills 框架
|
||
|
||
管理 Skills（代理扩展框架）。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | -------------------------- | --------------------------------------------------------------------------------- |
|
||
| GET | `/api/skills` | 列出所有已安装的技能（内置 + 自定义） |
|
||
| POST | `/api/skills/install` | 从本地路径或 URL 安装技能 |
|
||
| DELETE | `/api/skills/[id]` | 卸载技能 |
|
||
| PUT | `/api/skills/[id]` | 启用或禁用技能 — 请求体：`{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
|
||
| POST | `/api/skills/executions` | 执行技能 — 请求体：`{skillName, apiKeyId, input?, sessionId?}` |
|
||
| GET | `/api/skills/executions` | 列出所有技能的执行历史（可按 `?apiKeyId=` 过滤） |
|
||
|
||
**认证：** 需要管理会话或管理权限域的 API Key。
|
||
|
||
完整细节参见 [Skills Framework](../frameworks/SKILLS.md)。
|
||
|
||
---
|
||
|
||
## 插件
|
||
|
||
管理 OmniRoute 插件（第三方扩展）。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ------ | ---------------------------------- | ------------------------------------ |
|
||
| GET | `/api/plugins` | 列出已安装的插件 |
|
||
| POST | `/api/plugins/install` | 从本地路径或 URL 安装插件 |
|
||
| DELETE | `/api/plugins/[name]` | 卸载插件 |
|
||
| POST | `/api/plugins/[name]/activate` | 激活插件 |
|
||
| POST | `/api/plugins/[name]/deactivate` | 停用插件 |
|
||
| GET | `/api/plugins/[name]/config` | 获取插件配置 |
|
||
| PUT | `/api/plugins/[name]/config` | 更新插件配置 |
|
||
|
||
**认证：** 需要管理会话。
|
||
|
||
完整细节参见 [Plugins Framework](../frameworks/PLUGIN_SDK.md)。
|
||
|
||
---
|
||
|
||
## Shadow Routing
|
||
|
||
服务商的 Shadow / A-B 对比**不是独立的 REST 面** — 通过 Combo 路由配置（参见 [Auto-Combo](../routing/AUTO-COMBO.md)）。按 Combo 的对比指标通过 `GET /api/combos/metrics` 提供。
|
||
|
||
---
|
||
|
||
## 安全护栏
|
||
|
||
检查运行时安全护栏（PII 检测、提示注入检测、视觉桥接）。安全护栏在每次请求中运行；按调用退出通过 `x-omniroute-disabled-guardrails` 请求头实现 — 没有持久化的启用/禁用地表。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ------------------------ | -------------------------------------------------------------------------------------- |
|
||
| GET | `/api/guardrails` | 列出已注册的安全护栏及其状态（名称 / 启用 / 优先级） |
|
||
| POST | `/api/guardrails/test` | 对示例输入干运行调用前管线 — 请求体：`{input, disabledGuardrails?}` |
|
||
|
||
**认证：** 需要管理会话。
|
||
|
||
完整细节参见 [Security > Guardrails](../security/GUARDRAILS.md)。
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 认证
|
||
|
||
- Dashboard 路由（`/dashboard/*`）使用 `auth_token` cookie
|
||
- 登录使用保存的密码哈希；回退到 `INITIAL_PASSWORD`
|
||
- `requireLogin` 可通过 `/api/settings/require-login` 切换
|
||
- `/v1/*` 路由在 `REQUIRE_API_KEY=true` 时可选要求 Bearer API Key
|
||
|
||
> **重大变更（v3.8.0）** — `/api/v1/agents/tasks/*` 和冷却管理端点现在需要**管理认证**（dashboard `auth_token` cookie 或管理权限域的 API Key）。此前无需认证即可调用这些路由的客户端将收到 `401 Unauthorized`。参见 commit `588a0333`（`fix(auth): require management auth for agent and cooldown APIs`）。
|